tea-test-dao

*pi_netrw.txt* For Vim version 9.1. Last change: 2023 May 14 ------------------------------------------------ NETRW REFERENCE MANUAL by Charles E. Campbell ------------------------------------------------ Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM> (remove NOSPAM from Campbell's email first) Copyright: Copyright (C) 2017 Charles E Campbell *netrw-copyright* The VIM LICENSE applies to the files in this package, including netrw.vim, pi_netrw.txt, netrwFileHandlers.vim, 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 File Permission..............................|netrw-gp| Change Listing Style.(thin wide long tree)..........|netrw-i| Changing To A Bookmarked Directory..................|netrw-gb| 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: Printing..............................|netrw-mp| 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. Debugging Netrw Itself................................|netrw-debug| 12. History...............................................|netrw-history| 13. Todo..................................................|netrw-todo| 14. 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. (default value if popup windows are available) =1 : messages from netrw will use a separate one line window. This window provides reliable delivery of messages. (default value if popup windows are not available) =0 : 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_win95ftp* =1 if using Win95, will remove four trailing blank lines that o/s's ftp "provides" on transfers =0 force normal ftp behavior (no trailing line removal) *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 g:netrw_win95ftp =0 use unix-style ftp even if win95/98/ME/etc =1 use default method to do ftp > ----------------------------------------------------------------------- < *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 by NetReadFixup() g:netrw_dav_cmd var ="cadaver" if cadaver is executable g:netrw_dav_cmd var ="curl -o" elseif curl is executable g:netrw_fetch_cmd var ="fetch -o" if fetch is available g:netrw_ftp_cmd var ="ftp" g:netrw_http_cmd var ="fetch -o" if fetch is available g:netrw_http_cmd var ="wget -O" else if wget is available g:netrw_http_put_cmd var ="curl -T" |g:netrw_list_cmd| var ="ssh USEPORT HOSTNAME ls -Fa" g:netrw_rcp_cmd var ="rcp" g:netrw_rsync_cmd var ="rsync" *g:netrw_rsync_sep* var ="/" used to separate the hostname from the file spec g:netrw_scp_cmd var ="scp -q" g:netrw_sftp_cmd var ="sftp" > ------------------------------------------------------------------------- < *netrw-ftp* The g:netrw_..._cmd options (|g:netrw_ftp_cmd| and |g:netrw_sftp_cmd|) specify the external program to use handle the ftp protocol. They may include command line options (such as -p for passive mode). Example: > let g:netrw_ftp_cmd= "ftp -p" < Browsing is supported by using the |g:netrw_list_cmd|; the substring "HOSTNAME" will be changed via substitution with whatever the current request is for a hostname. Two options (|g:netrw_ftp| and |netrw-fixup|) both help with certain ftp's that give trouble . In order to best understand how to use these options if ftp is giving you troubles, a bit of discussion is provided on how netrw does ftp reads. For ftp, netrw typically builds up lines of one of the following formats in a temporary file: > IF g:netrw_ftp !exists or is not 1 IF g:netrw_ftp exists and is 1 ---------------------------------- ------------------------------ < open machine [port] open machine [port] user userid password userid password [g:netrw_ftpmode] password [g:netrw_ftpextracmd] [g:netrw_ftpmode] get filename tempfile [g:netrw_extracmd] get filename tempfile > --------------------------------------------------------------------- < The |g:netrw_ftpmode| and |g:netrw_ftpextracmd| are optional. Netrw then executes the lines above by use of a filter: > :%! {g:netrw_ftp_cmd} -i [-n] < where g:netrw_ftp_cmd is usually "ftp", -i tells ftp not to be interactive -n means don't use netrc and is used for Method #3 (ftp w/o <.netrc>) If <.netrc> exists it will be used to avoid having to query the user for userid and password. The transferred file is put into a temporary file. The temporary file is then read into the main editing session window that requested it and the temporary file deleted. If your ftp doesn't accept the "user" command and immediately just demands a userid, then try putting "let netrw_ftp=1" in your <.vimrc>. *netrw-cadaver* To handle the SSL certificate dialog for untrusted servers, one may pull down the certificate and place it into /usr/ssl/cert.pem. This operation renders the server treatment as "trusted". *netrw-fixup* *netreadfixup* If your ftp for whatever reason generates unwanted lines (such as AUTH messages) you may write a NetReadFixup() function: > function! NetReadFixup(method,line1,line2) " a:line1: first new line in current file " a:line2: last new line in current file if a:method == 1 "rcp elseif a:method == 2 "ftp + <.netrc> elseif a:method == 3 "ftp + machine,uid,password,filename elseif a:method == 4 "scp elseif a:method == 5 "http/wget elseif a:method == 6 "dav/cadaver elseif a:method == 7 "rsync elseif a:method == 8 "fetch elseif a:method == 9 "sftp else " complain endif endfunction > The NetReadFixup() function will be called if it exists and thus allows you to customize your reading process. As a further example, <netrw.vim> contains just such a function to handle Windows 95 ftp. For whatever reason, Windows 95's ftp dumps four blank lines at the end of a transfer, and so it is desirable to automate their removal. Here's some code taken from <netrw.vim> itself: > if has("win95") && g:netrw_win95ftp fun! NetReadFixup(method, line1, line2) if method == 3 " ftp (no <.netrc>) let fourblanklines= line2 - 3 silent fourblanklines .. "," .. line2 .. "g/^\s*/d" endif endfunction endif > (Related topics: |ftp| |netrw-userpass| |netrw-start|) ============================================================================== 9. Browsing *netrw-browsing* *netrw-browse* *netrw-help* {{{1 *netrw-browser* *netrw-dir* *netrw-list* INTRODUCTION TO BROWSING *netrw-intro-browse* {{{2 (Quick References: |netrw-quickmaps| |netrw-quickcoms|) Netrw supports the browsing of directories on your local system and on remote hosts; browsing includes listing files and directories, entering directories, editing files therein, deleting files/directories, making new directories, moving (renaming) files and directories, copying files and directories, etc. One may mark files and execute any system command on them! The Netrw browser generally implements the previous explorer's maps and commands for remote directories, although details (such as pertinent global variable names) necessarily differ. To browse a directory, simply "edit" it! > vim /your/directory/ vim . vim c:\your\directory\ < (Related topics: |netrw-cr| |netrw-o| |netrw-p| |netrw-P| |netrw-t| |netrw-mf| |netrw-mx| |netrw-D| |netrw-R| |netrw-v| ) The Netrw remote file and directory browser handles two protocols: ssh and ftp. The protocol in the url, if it is ftp, will cause netrw also to use ftp in its remote browsing. Specifying any other protocol will cause it to be used for file transfers; but the ssh protocol will be used to do remote browsing. To use Netrw's remote directory browser, simply attempt to read a "file" with a trailing slash and it will be interpreted as a request to list a directory: > vim [protocol]://[user@]hostname/path/ < where [protocol] is typically scp or ftp. As an example, try: > vim ftp://ftp.home.vim.org/pub/vim/ < For local directories, the trailing slash is not required. Again, because it's easy to miss: to browse remote directories, the URL must terminate with a slash! If you'd like to avoid entering the password repeatedly for remote directory listings with ssh or scp, see |netrw-ssh-hack|. To avoid password entry with ftp, see |netrw-netrc| (if your ftp supports it). There are several things you can do to affect the browser's display of files: * To change the listing style, press the "i" key (|netrw-i|). Currently there are four styles: thin, long, wide, and tree. To make that change "permanent", see |g:netrw_liststyle|. * To hide files (don't want to see those xyz~ files anymore?) see |netrw-ctrl-h|. * Press s to sort files by name, time, or size. See |netrw-browse-cmds| for all the things you can do with netrw! *netrw-getftype* *netrw-filigree* *netrw-ftype* The |getftype()| function is used to append a bit of filigree to indicate filetype to locally listed files: directory : / executable : * fifo : | links : @ sockets : = The filigree also affects the |g:netrw_sort_sequence|. QUICK HELP *netrw-quickhelp* {{{2 (Use ctrl-] to select a topic)~ Intro to Browsing...............................|netrw-intro-browse| Quick Reference: Maps.........................|netrw-quickmap| Quick Reference: Commands.....................|netrw-browse-cmds| Hiding Edit hiding list..............................|netrw-ctrl-h| Hiding Files or Directories...................|netrw-a| Hiding/Unhiding by suffix.....................|netrw-mh| Hiding dot-files.............................|netrw-gh| Listing Style Select listing style (thin/long/wide/tree)....|netrw-i| Associated setting variable...................|g:netrw_liststyle| Shell command used to perform listing.........|g:netrw_list_cmd| Quick file info...............................|netrw-qf| Sorted by Select sorting style (name/time/size).........|netrw-s| Editing the sorting sequence..................|netrw-S| Sorting options...............................|g:netrw_sort_options| Associated setting variable...................|g:netrw_sort_sequence| Reverse sorting order.........................|netrw-r| *netrw-quickmap* *netrw-quickmaps* QUICK REFERENCE: MAPS *netrw-browse-maps* {{{2 > --- ----------------- ---- Map Quick Explanation Link --- ----------------- ---- < <F1> Causes Netrw to issue help <cr> Netrw will enter the directory or read the file |netrw-cr| <del> Netrw will attempt to remove the file/directory |netrw-del| <c-h> Edit file hiding list |netrw-ctrl-h| <c-l> Causes Netrw to refresh the directory listing |netrw-ctrl-l| <c-r> Browse using a gvim server |netrw-ctrl-r| <c-tab> Shrink/expand a netrw/explore window |netrw-c-tab| - Makes Netrw go up one directory |netrw--| a Cycles between normal display, |netrw-a| hiding (suppress display of files matching g:netrw_list_hide) and showing (display only files which match g:netrw_list_hide) cd Make browsing directory the current directory |netrw-cd| C Setting the editing window |netrw-C| d Make a directory |netrw-d| D Attempt to remove the file(s)/directory(ies)