diff options
Diffstat (limited to 'runtime/pack/dist/opt/netrw/doc/netrw.txt')
| -rw-r--r-- | runtime/pack/dist/opt/netrw/doc/netrw.txt | 3786 |
1 files changed, 3786 insertions, 0 deletions
diff --git a/runtime/pack/dist/opt/netrw/doc/netrw.txt b/runtime/pack/dist/opt/netrw/doc/netrw.txt new file mode 100644 index 0000000000..9fc7b42bb7 --- /dev/null +++ b/runtime/pack/dist/opt/netrw/doc/netrw.txt @@ -0,0 +1,3786 @@ +*netrw.txt* Nvim + + ------------------------------------------------ + NETRW REFERENCE MANUAL by Charles E. Campbell + ------------------------------------------------ +Original Author: Charles E. Campbell +Copyright: Copyright (C) 2017 Charles E Campbell *netrw-copyright* + The VIM LICENSE applies to the files in this package, including + netrw.vim, netrw.txt, netrwSettings.vim, and + syntax/netrw.vim. Like anything else that's free, netrw.vim and its + associated files are provided *as is* and comes with no warranty of + any kind, either expressed or implied. No guarantees of + merchantability. No guarantees of suitability for any purpose. By + using this plugin, you agree that in no event will the copyright + holder be liable for any damages resulting from the use of this + software. Use at your own risk! + + *netrw* + *dav* *ftp* *netrw-file* *rcp* *scp* + *davs* *http* *netrw.vim* *rsync* *sftp* + *fetch* *network* + +============================================================================== +1. Contents *netrw-contents* {{{1 + +1. Contents..............................................|netrw-contents| +2. Starting With Netrw...................................|netrw-start| +3. Netrw Reference.......................................|netrw-ref| + EXTERNAL APPLICATIONS AND PROTOCOLS.................|netrw-externapp| + READING.............................................|netrw-read| + WRITING.............................................|netrw-write| + SOURCING............................................|netrw-source| + DIRECTORY LISTING...................................|netrw-dirlist| + CHANGING THE USERID AND PASSWORD....................|netrw-chgup| + VARIABLES AND SETTINGS..............................|netrw-variables| + PATHS...............................................|netrw-path| +4. Network-Oriented File Transfer........................|netrw-xfer| + NETRC...............................................|netrw-netrc| + PASSWORD............................................|netrw-passwd| +5. Activation............................................|netrw-activate| +6. Transparent Remote File Editing.......................|netrw-transparent| +7. Ex Commands...........................................|netrw-ex| +8. Variables and Options.................................|netrw-variables| +9. Browsing..............................................|netrw-browse| + Introduction To Browsing............................|netrw-intro-browse| + Quick Reference: Maps...............................|netrw-browse-maps| + Quick Reference: Commands...........................|netrw-browse-cmds| + Banner Display......................................|netrw-I| + Bookmarking A Directory.............................|netrw-mb| + Browsing............................................|netrw-cr| + Squeezing the Current Tree-Listing Directory........|netrw-s-cr| + Browsing With A Horizontally Split Window...........|netrw-o| + Browsing With A New Tab.............................|netrw-t| + Browsing With A Vertically Split Window.............|netrw-v| + Change Listing Style (thin wide long tree)..........|netrw-i| + Changing To A Bookmarked Directory..................|netrw-gb| + Quick hide/unhide of dot-files......................|netrw-gh| + Changing local-only File Permission.................|netrw-gp| + Changing To A Predecessor Directory.................|netrw-u| + Changing To A Successor Directory...................|netrw-U| + Customizing Browsing With A Special Handler.........|netrw-x| + Deleting Bookmarks..................................|netrw-mB| + Deleting Files Or Directories.......................|netrw-D| + Directory Exploring Commands........................|netrw-explore| + Exploring With Stars and Patterns...................|netrw-star| + Displaying Information About File...................|netrw-qf| + Edit File Or Directory Hiding List..................|netrw-ctrl-h| + Editing The Sorting Sequence........................|netrw-S| + Forcing treatment as a file or directory............|netrw-gd| |netrw-gf| + Going Up............................................|netrw--| + Hiding Files Or Directories.........................|netrw-a| + Improving Browsing..................................|netrw-ssh-hack| + Listing Bookmarks And History.......................|netrw-qb| + Making A New Directory..............................|netrw-d| + Making The Browsing Directory The Current Directory.|netrw-cd| + Marking Files.......................................|netrw-mf| + Unmarking Files.....................................|netrw-mF| + Marking Files By Location List......................|netrw-qL| + Marking Files By QuickFix List......................|netrw-qF| + Marking Files By Regular Expression.................|netrw-mr| + Marked Files: Arbitrary Shell Command...............|netrw-mx| + Marked Files: Arbitrary Shell Command, En Bloc......|netrw-mX| + Marked Files: Arbitrary Vim Command.................|netrw-mv| + Marked Files: Argument List.........................|netrw-ma| |netrw-mA| + Marked Files: Buffer List...........................|netrw-cb| |netrw-cB| + Marked Files: Compression And Decompression.........|netrw-mz| + Marked Files: Copying...............................|netrw-mc| + Marked Files: Diff..................................|netrw-md| + Marked Files: Editing...............................|netrw-me| + Marked Files: Grep..................................|netrw-mg| + Marked Files: Hiding and Unhiding by Suffix.........|netrw-mh| + Marked Files: Moving................................|netrw-mm| + Marked Files: Sourcing..............................|netrw-ms| + Marked Files: Setting the Target Directory..........|netrw-mt| + Marked Files: Tagging...............................|netrw-mT| + Marked Files: Target Directory Using Bookmarks......|netrw-Tb| + Marked Files: Target Directory Using History........|netrw-Th| + Marked Files: Unmarking.............................|netrw-mu| + Netrw Browser Variables.............................|netrw-browser-var| + Netrw Browsing And Option Incompatibilities.........|netrw-incompatible| + Netrw Settings Window...............................|netrw-settings-window| + Obtaining A File....................................|netrw-O| + Preview Window......................................|netrw-p| + Previous Window.....................................|netrw-P| + Refreshing The Listing..............................|netrw-ctrl-l| + Reversing Sorting Order.............................|netrw-r| + Renaming Files Or Directories.......................|netrw-R| + Selecting Sorting Style.............................|netrw-s| + Setting Editing Window..............................|netrw-C| +10. Problems and Fixes....................................|netrw-problems| +11. Credits...............................................|netrw-credits| + +============================================================================== +2. Starting With Netrw *netrw-start* {{{1 + +Netrw makes reading files, writing files, browsing over a network, and +local browsing easy! First, make sure that you have plugins enabled, so +you'll need to have at least the following in your <.vimrc>: +(or see |netrw-activate|) > + + set nocp " 'compatible' is not set + filetype plugin on " plugins are enabled +< +(see |'cp'| and |:filetype-plugin-on|) + +Netrw supports "transparent" editing of files on other machines using urls +(see |netrw-transparent|). As an example of this, let's assume you have an +account on some other machine; if you can use scp, try: > + + vim scp://hostname/path/to/file +< +Want to make ssh/scp easier to use? Check out |netrw-ssh-hack|! + +So, what if you have ftp, not ssh/scp? That's easy, too; try > + + vim ftp://hostname/path/to/file +< +Want to make ftp simpler to use? See if your ftp supports a file called +<.netrc> -- typically it goes in your home directory, has read/write +permissions for only the user to read (ie. not group, world, other, etc), +and has lines resembling > + + machine HOSTNAME login USERID password "PASSWORD" + machine HOSTNAME login USERID password "PASSWORD" + ... + default login USERID password "PASSWORD" +< +Windows' ftp doesn't support .netrc; however, one may have in one's .vimrc: > + + let g:netrw_ftp_cmd= 'c:\Windows\System32\ftp -s:C:\Users\MyUserName\MACHINE' +< +Netrw will substitute the host's machine name for "MACHINE" from the URL it is +attempting to open, and so one may specify > + userid + password +for each site in a separate file: c:\Users\MyUserName\MachineName. + +Now about browsing -- when you just want to look around before editing a +file. For browsing on your current host, just "edit" a directory: > + + vim . + vim /home/userid/path +< +For browsing on a remote host, "edit" a directory (but make sure that +the directory name is followed by a "/"): > + + vim scp://hostname/ + vim ftp://hostname/path/to/dir/ +< +See |netrw-browse| for more! + +There are more protocols supported by netrw than just scp and ftp, too: see the +next section, |netrw-externapp|, on how to use these external applications with +netrw and vim. + +PREVENTING LOADING *netrw-noload* + +If you want to use plugins, but for some reason don't wish to use netrw, then +you need to avoid loading both the plugin and the autoload portions of netrw. +You may do so by placing the following two lines in your <.vimrc>: > + + :let g:loaded_netrw = 1 + :let g:loaded_netrwPlugin = 1 +< + +============================================================================== +3. Netrw Reference *netrw-ref* {{{1 + + Netrw supports several protocols in addition to scp and ftp as mentioned + in |netrw-start|. These include dav, fetch, http,... well, just look + at the list in |netrw-externapp|. Each protocol is associated with a + variable which holds the default command supporting that protocol. + +EXTERNAL APPLICATIONS AND PROTOCOLS *netrw-externapp* {{{2 + + Protocol Variable Default Value + -------- ---------------- ------------- + dav: *g:netrw_dav_cmd* = "cadaver" if cadaver is executable + dav: g:netrw_dav_cmd = "curl -o" elseif curl is available + fetch: *g:netrw_fetch_cmd* = "fetch -o" if fetch is available + ftp: *g:netrw_ftp_cmd* = "ftp" + http: *g:netrw_http_cmd* = "elinks" if elinks is available + http: g:netrw_http_cmd = "links" elseif links is available + http: g:netrw_http_cmd = "curl" elseif curl is available + http: g:netrw_http_cmd = "wget" elseif wget is available + http: g:netrw_http_cmd = "fetch" elseif fetch is available + http: *g:netrw_http_put_cmd* = "curl -T" + rcp: *g:netrw_rcp_cmd* = "rcp" + rsync: *g:netrw_rsync_cmd* = "rsync" (see |g:netrw_rsync_sep|) + scp: *g:netrw_scp_cmd* = "scp -q" + sftp: *g:netrw_sftp_cmd* = "sftp" + file: *g:netrw_file_cmd* = "elinks" or "links" + + *g:netrw_http_xcmd* : the option string for http://... protocols are + specified via this variable and may be independently overridden. By + default, the option arguments for the http-handling commands are: > + + elinks : "-source >" + links : "-dump >" + curl : "-L -o" + wget : "-q -O" + fetch : "-o" +< + For example, if your system has elinks, and you'd rather see the + page using an attempt at rendering the text, you may wish to have > + let g:netrw_http_xcmd= "-dump >" +< in your .vimrc. + + g:netrw_http_put_cmd: this option specifies both the executable and + any needed options. This command does a PUT operation to the url. + + +READING *netrw-read* *netrw-nread* {{{2 + + Generally, one may just use the URL notation with a normal editing + command, such as > + + :e ftp://[user@]machine/path +< + Netrw also provides the Nread command: + + :Nread ? give help + :Nread "machine:path" uses rcp + :Nread "machine path" uses ftp w/ <.netrc> + :Nread "machine id password path" uses ftp + :Nread "dav://machine[:port]/path" uses cadaver + :Nread "fetch://[user@]machine/path" uses fetch + :Nread "ftp://[user@]machine[[:#]port]/path" uses ftp w/ <.netrc> + :Nread "http://[user@]machine/path" uses http uses wget + :Nread "rcp://[user@]machine/path" uses rcp + :Nread "rsync://[user@]machine[:port]/path" uses rsync + :Nread "scp://[user@]machine[[:#]port]/path" uses scp + :Nread "sftp://[user@]machine/path" uses sftp + +WRITING *netrw-write* *netrw-nwrite* {{{2 + + One may just use the URL notation with a normal file writing + command, such as > + + :w ftp://[user@]machine/path +< + Netrw also provides the Nwrite command: + + :Nwrite ? give help + :Nwrite "machine:path" uses rcp + :Nwrite "machine path" uses ftp w/ <.netrc> + :Nwrite "machine id password path" uses ftp + :Nwrite "dav://machine[:port]/path" uses cadaver + :Nwrite "ftp://[user@]machine[[:#]port]/path" uses ftp w/ <.netrc> + :Nwrite "rcp://[user@]machine/path" uses rcp + :Nwrite "rsync://[user@]machine[:port]/path" uses rsync + :Nwrite "scp://[user@]machine[[:#]port]/path" uses scp + :Nwrite "sftp://[user@]machine/path" uses sftp + http: not supported! + +SOURCING *netrw-source* {{{2 + + One may just use the URL notation with the normal file sourcing + command, such as > + + :so ftp://[user@]machine/path +< + Netrw also provides the Nsource command: + + :Nsource ? give help + :Nsource "dav://machine[:port]/path" uses cadaver + :Nsource "fetch://[user@]machine/path" uses fetch + :Nsource "ftp://[user@]machine[[:#]port]/path" uses ftp w/ <.netrc> + :Nsource "http://[user@]machine/path" uses http uses wget + :Nsource "rcp://[user@]machine/path" uses rcp + :Nsource "rsync://[user@]machine[:port]/path" uses rsync + :Nsource "scp://[user@]machine[[:#]port]/path" uses scp + :Nsource "sftp://[user@]machine/path" uses sftp + +DIRECTORY LISTING *netrw-trailingslash* *netrw-dirlist* {{{2 + + One may browse a directory to get a listing by simply attempting to + edit the directory: > + + :e scp://[user]@hostname/path/ + :e ftp://[user]@hostname/path/ +< + For remote directory listings (ie. those using scp or ftp), that + trailing "/" is necessary (the slash tells netrw to treat the argument + as a directory to browse instead of as a file to download). + + The Nread command may also be used to accomplish this (again, that + trailing slash is necessary): > + + :Nread [protocol]://[user]@hostname/path/ +< + *netrw-login* *netrw-password* +CHANGING USERID AND PASSWORD *netrw-chgup* *netrw-userpass* {{{2 + + Attempts to use ftp will prompt you for a user-id and a password. + These will be saved in global variables |g:netrw_uid| and + |s:netrw_passwd|; subsequent use of ftp will re-use those two strings, + thereby simplifying use of ftp. However, if you need to use a + different user id and/or password, you'll want to call |NetUserPass()| + first. To work around the need to enter passwords, check if your ftp + supports a <.netrc> file in your home directory. Also see + |netrw-passwd| (and if you're using ssh/scp hoping to figure out how + to not need to use passwords for scp, look at |netrw-ssh-hack|). + + :NetUserPass [uid [password]] -- prompts as needed + :call NetUserPass() -- prompts for uid and password + :call NetUserPass("uid") -- prompts for password + :call NetUserPass("uid","password") -- sets global uid and password + +(Related topics: |ftp| |netrw-userpass| |netrw-start|) + +NETRW VARIABLES AND SETTINGS *netrw-variables* {{{2 + (Also see: + |netrw-browser-var| : netrw browser option variables + |netrw-protocol| : file transfer protocol option variables + |netrw-settings| : additional file transfer options + |netrw-browser-options| : these options affect browsing directories + ) + +Netrw provides a lot of variables which allow you to customize netrw to your +preferences. One way to look at them is via the command :NetrwSettings (see +|netrw-settings|) which will display your current netrw settings. Most such +settings are described below, in |netrw-browser-options|, and in +|netrw-externapp|: + + *b:netrw_lastfile* last file Network-read/written retained on a + per-buffer basis (supports plain :Nw ) + + *g:netrw_bufsettings* the settings that netrw buffers have + (default) noma nomod nonu nowrap ro nobl + + *g:netrw_chgwin* specifies a window number where subsequent file edits + will take place. (also see |netrw-C|) + (default) -1 + + *g:Netrw_funcref* specifies a function (or functions) to be called when + netrw edits a file. The file is first edited, and + then the function reference (|Funcref|) is called. + This variable may also hold a |List| of Funcrefs. + (default) not defined. (the capital in g:Netrw... + is required by its holding a function reference) +> + Example: place in .vimrc; affects all file opening + fun! MyFuncRef() + endfun + let g:Netrw_funcref= function("MyFuncRef") + +< + *g:Netrw_UserMaps* specifies a function or |List| of functions which can + be used to set up user-specified maps and functionality. + See |netrw-usermaps| + + *g:netrw_ftp* if it doesn't exist, use default ftp + =0 use default ftp (uid password) + =1 use alternate ftp method (user uid password) + If you're having trouble with ftp, try changing the + value of this variable to see if the alternate ftp + method works for your setup. + + *g:netrw_ftp_options* Chosen by default, these options are supposed to + turn interactive prompting off and to restrain ftp + from attempting auto-login upon initial connection. + However, it appears that not all ftp implementations + support this (ex. ncftp). + ="-i -n" + + *g:netrw_ftpextracmd* default: doesn't exist + If this variable exists, then any string it contains + will be placed into the commands set to your ftp + client. As an example: + ="passive" + + *g:netrw_ftpmode* ="binary" (default) + ="ascii" + + *g:netrw_ignorenetrc* =0 (default for linux, cygwin) + =1 If you have a <.netrc> file but it doesn't work and + you want it ignored, then set this variable as + shown. (default for Windows + cmd.exe) + + *g:netrw_menu* =0 disable netrw's menu + =1 (default) netrw's menu enabled + + *g:netrw_nogx* if this variable exists, then the "gx" map will not + be available (see |netrw-gx|) + + *g:netrw_uid* (ftp) user-id, retained on a per-vim-session basis + *s:netrw_passwd* (ftp) password, retained on a per-vim-session basis + + *g:netrw_preview* =0 (default) preview window shown in a horizontally + split window + =1 preview window shown in a vertically split window. + Also affects the "previous window" (see |netrw-P|) + in the same way. + The |g:netrw_alto| variable may be used to provide + additional splitting control: + g:netrw_preview g:netrw_alto result + 0 0 |:aboveleft| + 0 1 |:belowright| + 1 0 |:topleft| + 1 1 |:botright| + To control sizing, see |g:netrw_winsize| + + *g:netrw_scpport* = "-P" : option to use to set port for scp + *g:netrw_sshport* = "-p" : option to use to set port for ssh + + *g:netrw_sepchr* =\0xff + =\0x01 for enc == euc-jp (and perhaps it should be for + others, too, please let me know) + Separates priority codes from filenames internally. + See |netrw-p12|. + + *g:netrw_silent* =0 : transfers done normally + =1 : transfers done silently + + *g:netrw_use_errorwindow* =2: messages from netrw will use a popup window + Move the mouse and pause to remove the popup window. + =1 : messages from netrw will use a separate one + line window. This window provides reliable + delivery of messages. + =0 : (default) messages from netrw will use echoerr ; + messages don't always seem to show up this + way, but one doesn't have to quit the window. + + *g:netrw_cygwin* =1 assume scp under windows is from cygwin. Also + permits network browsing to use ls with time and + size sorting (default if windows) + =0 assume Windows' scp accepts windows-style paths + Network browsing uses dir instead of ls + This option is ignored if you're using unix + + *g:netrw_use_nt_rcp* =0 don't use the rcp of WinNT, Win2000 and WinXP + =1 use WinNT's rcp in binary mode (default) + +PATHS *netrw-path* {{{2 + +Paths to files are generally user-directory relative for most protocols. +It is possible that some protocol will make paths relative to some +associated directory, however. +> + example: vim scp://user@host/somefile + example: vim scp://user@host/subdir1/subdir2/somefile +< +where "somefile" is in the "user"'s home directory. If you wish to get a +file using root-relative paths, use the full path: +> + example: vim scp://user@host//somefile + example: vim scp://user@host//subdir1/subdir2/somefile +< + +============================================================================== +4. Network-Oriented File Transfer *netrw-xfer* {{{1 + +Network-oriented file transfer under Vim is implemented by a vim script +(<netrw.vim>) using plugin techniques. It currently supports both reading and +writing across networks using rcp, scp, ftp or ftp+<.netrc>, scp, fetch, +dav/cadaver, rsync, or sftp. + +http is currently supported read-only via use of wget or fetch. + +<netrw.vim> is a standard plugin which acts as glue between Vim and the +various file transfer programs. It uses autocommand events (BufReadCmd, +FileReadCmd, BufWriteCmd) to intercept reads/writes with url-like filenames. > + + ex. vim ftp://hostname/path/to/file +< +The characters preceding the colon specify the protocol to use; in the +example, it's ftp. The <netrw.vim> script then formulates a command or a +series of commands (typically ftp) which it issues to an external program +(ftp, scp, etc) which does the actual file transfer/protocol. Files are read +from/written to a temporary file (under Unix/Linux, /tmp/...) which the +<netrw.vim> script will clean up. + +Now, a word about Jan Minář's "FTP User Name and Password Disclosure"; first, +ftp is not a secure protocol. User names and passwords are transmitted "in +the clear" over the internet; any snooper tool can pick these up; this is not +a netrw thing, this is a ftp thing. If you're concerned about this, please +try to use scp or sftp instead. + +Netrw re-uses the user id and password during the same vim session and so long +as the remote hostname remains the same. + +Jan seems to be a bit confused about how netrw handles ftp; normally multiple +commands are performed in a "ftp session", and he seems to feel that the +uid/password should only be retained over one ftp session. However, netrw +does every ftp operation in a separate "ftp session"; so remembering the +uid/password for just one "ftp session" would be the same as not remembering +the uid/password at all. IMHO this would rapidly grow tiresome as one +browsed remote directories, for example. + +On the other hand, thanks go to Jan M. for pointing out the many +vulnerabilities that netrw (and vim itself) had had in handling "crafted" +filenames. The |shellescape()| and |fnameescape()| functions were written in +response by Bram Moolenaar to handle these sort of problems, and netrw has +been modified to use them. Still, my advice is, if the "filename" looks like +a vim command that you aren't comfortable with having executed, don't open it. + + *netrw-putty* *netrw-pscp* *netrw-psftp* +One may modify any protocol's implementing external application by setting a +variable (ex. scp uses the variable g:netrw_scp_cmd, which is defaulted to +"scp -q"). As an example, consider using PuTTY: > + + let g:netrw_scp_cmd = '"c:\Program Files\PuTTY\pscp.exe" -q -batch' + let g:netrw_sftp_cmd= '"c:\Program Files\PuTTY\psftp.exe"' +< +(note: it has been reported that windows 7 with putty v0.6's "-batch" option + doesn't work, so its best to leave it off for that system) + +See |netrw-p8| for more about putty, pscp, psftp, etc. + +Ftp, an old protocol, seems to be blessed by numerous implementations. +Unfortunately, some implementations are noisy (ie., add junk to the end of the +file). Thus, concerned users may decide to write a NetReadFixup() function +that will clean up after reading with their ftp. Some Unix systems (ie., +FreeBSD) provide a utility called "fetch" which uses the ftp protocol but is +not noisy and more convenient, actually, for <netrw.vim> to use. +Consequently, if "fetch" is available (ie. executable), it may be preferable +to use it for ftp://... based transfers. + +For rcp, scp, sftp, and http, one may use network-oriented file transfers +transparently; ie. +> + vim rcp://[user@]machine/path + vim scp://[user@]machine/path +< +If your ftp supports <.netrc>, then it too can be transparently used +if the needed triad of machine name, user id, and password are present in +that file. Your ftp must be able to use the <.netrc> file on its own, however. +> + vim ftp://[user@]machine[[:#]portnumber]/path +< +Windows provides an ftp (typically c:\Windows\System32\ftp.exe) which uses +an option, -s:filename (filename can and probably should be a full path) +which contains ftp commands which will be automatically run whenever ftp +starts. You may use this feature to enter a user and password for one site: > + userid + password +< *netrw-windows-netrc* *netrw-windows-s* +If |g:netrw_ftp_cmd| contains -s:[path/]MACHINE, then (on Windows machines +only) netrw will substitute the current machine name requested for ftp +connections for MACHINE. Hence one can have multiple machine.ftp files +containing login and password for ftp. Example: > + + let g:netrw_ftp_cmd= 'c:\Windows\System32\ftp -s:C:\Users\Myself\MACHINE' + vim ftp://myhost.somewhere.net/ + +will use a file > + + C:\Users\Myself\myhost.ftp +< +Often, ftp will need to query the user for the userid and password. +The latter will be done "silently"; ie. asterisks will show up instead of +the actually-typed-in password. Netrw will retain the userid and password +for subsequent read/writes from the most recent transfer so subsequent +transfers (read/write) to or from that machine will take place without +additional prompting. + + *netrw-urls* + +=================================+============================+============+ + | Reading | Writing | Uses | + +=================================+============================+============+ + | DAV: | | | + | dav://host/path | | cadaver | + | :Nread dav://host/path | :Nwrite dav://host/path | cadaver | + +---------------------------------+----------------------------+------------+ + | DAV + SSL: | | | + | davs://host/path | | cadaver | + | :Nread davs://host/path | :Nwrite davs://host/path | cadaver | + +---------------------------------+----------------------------+------------+ + | FETCH: | | | + | fetch://[user@]host/path | | | + | fetch://[user@]host:http/path | Not Available | fetch | + | :Nread fetch://[user@]host/path| | | + +---------------------------------+----------------------------+------------+ + | FILE: | | | + | file:///* | file:///* | | + | file://localhost/* | file://localhost/* | | + +---------------------------------+----------------------------+------------+ + | FTP: (*3) | (*3) | | + | ftp://[user@]host/path | ftp://[user@]host/path | ftp (*2) | + | :Nread ftp://host/path | :Nwrite ftp://host/path | ftp+.netrc | + | :Nread host path | :Nwrite host path | ftp+.netrc | + | :Nread host uid pass path | :Nwrite host uid pass path | ftp | + +---------------------------------+----------------------------+------------+ + | HTTP: wget is executable: (*4) | | | + | http://[user@]host/path | Not Available | wget | + +---------------------------------+----------------------------+------------+ + | HTTP: fetch is executable (*4) | | | + | http://[user@]host/path | Not Available | fetch | + +---------------------------------+----------------------------+------------+ + | RCP: | | | + | rcp://[user@]host/path | rcp://[user@]host/path | rcp | + +---------------------------------+----------------------------+------------+ + | RSYNC: | | | + | rsync://[user@]host/path | rsync://[user@]host/path | rsync | + | :Nread rsync://host/path | :Nwrite rsync://host/path | rsync | + | :Nread rcp://host/path | :Nwrite rcp://host/path | rcp | + +---------------------------------+----------------------------+------------+ + | SCP: | | | + | scp://[user@]host/path | scp://[user@]host/path | scp | + | :Nread scp://host/path | :Nwrite scp://host/path | scp (*1) | + +---------------------------------+----------------------------+------------+ + | SFTP: | | | + | sftp://[user@]host/path | sftp://[user@]host/path | sftp | + | :Nread sftp://host/path | :Nwrite sftp://host/path | sftp (*1) | + +=================================+============================+============+ + + (*1) For an absolute path use scp://machine//path. + + (*2) if <.netrc> is present, it is assumed that it will + work with your ftp client. Otherwise the script will + prompt for user-id and password. + + (*3) for ftp, "machine" may be machine#port or machine:port + if a different port is needed than the standard ftp port + + (*4) for http:..., if wget is available it will be used. Otherwise, + if fetch is available it will be used. + +Both the :Nread and the :Nwrite ex-commands can accept multiple filenames. + + +NETRC *netrw-netrc* + +The <.netrc> file, typically located in your home directory, contains lines +therein which map a hostname (machine name) to the user id and password you +prefer to use with it. + +The typical syntax for lines in a <.netrc> file is given as shown below. +Ftp under Unix usually supports <.netrc>; ftp under Windows usually doesn't. +> + machine {full machine name} login {user-id} password "{password}" + default login {user-id} password "{password}" + +Your ftp client must handle the use of <.netrc> on its own, but if the +<.netrc> file exists, an ftp transfer will not ask for the user-id or +password. + + Note: + Since this file contains passwords, make very sure nobody else can + read this file! Most programs will refuse to use a .netrc that is + readable for others. Don't forget that the system administrator can + still read the file! Ie. for Linux/Unix: chmod 600 .netrc + +Even though Windows' ftp clients typically do not support .netrc, netrw has +a work-around: see |netrw-windows-s|. + + +PASSWORD *netrw-passwd* + +The script attempts to get passwords for ftp invisibly using |inputsecret()|, +a built-in Vim function. See |netrw-userpass| for how to change the password +after one has set it. + +Unfortunately there doesn't appear to be a way for netrw to feed a password to +scp. Thus every transfer via scp will require re-entry of the password. +However, |netrw-ssh-hack| can help with this problem. + + +============================================================================== +5. Activation *netrw-activate* {{{1 + +Network-oriented file transfers are available by default whenever Vim's +|'nocompatible'| mode is enabled. Netrw's script files reside in your +system's plugin, autoload, and syntax directories; just the +plugin/netrwPlugin.vim script is sourced automatically whenever you bring up +vim. The main script in autoload/netrw.vim is only loaded when you actually +use netrw. I suggest that, at a minimum, you have at least the following in +your <.vimrc> customization file: > + + set nocp + if version >= 600 + filetype plugin indent on + endif +< +By also including the following lines in your .vimrc, one may have netrw +immediately activate when using [g]vim without any filenames, showing the +current directory: > + + " Augroup VimStartup: + augroup VimStartup + au! + au VimEnter * if expand("%") == "" | e . | endif + augroup END +< + +============================================================================== +6. Transparent Remote File Editing *netrw-transparent* {{{1 + +Transparent file transfers occur whenever a regular file read or write +(invoked via an |:autocmd| for |BufReadCmd|, |BufWriteCmd|, or |SourceCmd| +events) is made. Thus one may read, write, or source files across networks +just as easily as if they were local files! > + + vim ftp://[user@]machine/path + ... + :wq + +See |netrw-activate| for more on how to encourage your vim to use plugins +such as netrw. + +For password-free use of scp:, see |netrw-ssh-hack|. + + +============================================================================== +7. Ex Commands *netrw-ex* {{{1 + +The usual read/write commands are supported. There are also a few +additional commands available. Often you won't need to use Nwrite or +Nread as shown in |netrw-transparent| (ie. simply use > + :e URL + :r URL + :w URL +instead, as appropriate) -- see |netrw-urls|. In the explanations +below, a {netfile} is a URL to a remote file. + + *:Nwrite* *:Nw* +:[range]Nw[rite] Write the specified lines to the current + file as specified in b:netrw_lastfile. + (related: |netrw-nwrite|) + +:[range]Nw[rite] {netfile} [{netfile}]... + Write the specified lines to the {netfile}. + + *:Nread* *:Nr* +:Nr[ead] Read the lines from the file specified in b:netrw_lastfile + into the current buffer. (related: |netrw-nread|) + +:Nr[ead] {netfile} {netfile}... + Read the {netfile} after the current line. + + *:Nsource* *:Ns* +:Ns[ource] {netfile} + Source the {netfile}. + To start up vim using a remote .vimrc, one may use + the following (all on one line) (tnx to Antoine Mechelynck) > + vim -u NORC -N + --cmd "runtime plugin/netrwPlugin.vim" + --cmd "source scp://HOSTNAME/.vimrc" +< (related: |netrw-source|) + +:call NetUserPass() *NetUserPass()* + If g:netrw_uid and s:netrw_passwd don't exist, + this function will query the user for them. + (related: |netrw-userpass|) + +:call NetUserPass("userid") + This call will set the g:netrw_uid and, if + the password doesn't exist, will query the user for it. + (related: |netrw-userpass|) + +:call NetUserPass("userid","passwd") + This call will set both the g:netrw_uid and s:netrw_passwd. + The user-id and password are used by ftp transfers. One may + effectively remove the user-id and password by using empty + strings (ie. ""). + (related: |netrw-userpass|) + +:NetrwSettings This command is described in |netrw-settings| -- used to + display netrw settings and change netrw behavior. + + +============================================================================== +8. Variables and Options *netrw-var* *netrw-settings* {{{1 + +(also see: |netrw-options| |netrw-variables| |netrw-protocol| + |netrw-browser-settings| |netrw-browser-options| ) + +The <netrw.vim> script provides several variables which act as options to +affect <netrw.vim>'s file transfer behavior. These variables typically may be +set in the user's <.vimrc> file: (see also |netrw-settings| |netrw-protocol|) + *netrw-options* +> + ------------- + Netrw Options + ------------- + Option Meaning + -------------- ----------------------------------------------- +< + b:netrw_col Holds current cursor position (during NetWrite) + g:netrw_cygwin =1 assume scp under windows is from cygwin + (default/windows) + =0 assume scp under windows accepts windows + style paths (default/else) + g:netrw_ftp =0 use default ftp (uid password) + g:netrw_ftpmode ="binary" (default) + ="ascii" (your choice) + g:netrw_ignorenetrc =1 (default) + if you have a <.netrc> file but you don't + want it used, then set this variable. Its + mere existence is enough to cause <.netrc> + to be ignored. + b:netrw_lastfile Holds latest method/machine/path. + b:netrw_line Holds current line number (during NetWrite) + g:netrw_silent =0 transfers done normally + =1 transfers done silently + g:netrw_uid Holds current user-id for ftp. + g:netrw_use_nt_rcp =0 don't use WinNT/2K/XP's rcp (default) + =1 use WinNT/2K/XP's rcp, binary mode + ----------------------------------------------------------------------- +< + *netrw-internal-variables* +The script will also make use of the following variables internally, albeit +temporarily. +> + ------------------- + Temporary Variables + ------------------- + Variable Meaning + -------- ------------------------------------ +< + b:netrw_method Index indicating rcp/ftp+.netrc/ftp + w:netrw_method (same as b:netrw_method) + g:netrw_machine Holds machine name parsed from input + b:netrw_fname Holds filename being accessed > + ------------------------------------------------------------ +< + *netrw-protocol* + +Netrw supports a number of protocols. These protocols are invoked using the +variables listed below, and may be modified by the user. +> + ------------------------ + Protocol Control Options + ------------------------ + Option Type Setting Meaning + --------- -------- -------------- --------------------------- +< netrw_ftp variable =doesn't exist userid set by "user userid" + =0 userid set by "user userid" + =1 userid set by "userid" + NetReadFixup function =doesn't exist no change + =exists Allows user to have files + read via ftp automatically + transformed however they wish |