Vim documentation: pi_netrw
main help file
*pi_netrw.txt* For Vim version 7.4b. Last change: 2013 May 18
------------------------------------------------
NETRW REFERENCE MANUAL by Charles E. Campbell
------------------------------------------------
Author: Charles E. Campbell <NdrOchip@ScampbellPfamily.AbizM>
(remove NOSPAM from Campbell's email first)
Copyright: Copyright (C) 1999-2013 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!
*dav* *ftp* *netrw-file* *rcp* *scp*
*davs* *http* *netrw.vim* *rsync* *sftp*
*fetch* *netrw* *network*
==============================================================================
1. Contents *netrw-contents* {{{1
1. Contents..............................................|netrw-contentsYXXY
2. Starting With Netrw...................................|netrw-startYXXY
3. Netrw Reference.......................................|netrw-refYXXY
EXTERNAL APPLICATIONS AND PROTOCOLS.................|netrw-externappYXXY
READING.............................................|netrw-readYXXY
WRITING.............................................|netrw-writeYXXY
SOURCING............................................|netrw-sourceYXXY
DIRECTORY LISTING...................................|netrw-dirlistYXXY
CHANGING THE USERID AND PASSWORD....................|netrw-chgupYXXY
VARIABLES AND SETTINGS..............................|netrw-variablesYXXY
PATHS...............................................|netrw-pathYXXY
4. Network-Oriented File Transfer........................|netrw-xferYXXY
NETRC...............................................|netrw-netrcYXXY
PASSWORD............................................|netrw-passwdYXXY
5. Activation............................................|netrw-activateYXXY
6. Transparent Remote File Editing.......................|netrw-transparentYXXY
7. Ex Commands...........................................|netrw-exYXXY
8. Variables and Options.................................|netrw-variablesYXXY
9. Browsing..............................................|netrw-browseYXXY
Introduction To Browsing............................|netrw-intro-browseYXXY
Quick Reference: Maps...............................|netrw-browse-mapsYXXY
Quick Reference: Commands...........................|netrw-browse-cmdsYXXY
Bookmarking A Directory.............................|netrw-mbYXXY
Browsing............................................|netrw-crYXXY
Browsing With A Horizontally Split Window...........|netrw-oYXXY
Browsing With A New Tab.............................|netrw-tYXXY
Browsing With A Vertically Split Window.............|netrw-vYXXY
Change Listing Style.(thin wide long tree)..........|netrw-iYXXY
Changing To A Bookmarked Directory..................|netrw-gbYXXY
Changing To A Predecessor Directory.................|netrw-uYXXY
Changing To A Successor Directory...................|netrw-UYXXY
Customizing Browsing With A User Function...........|netrw-xYXXY
Deleting Bookmarks..................................|netrw-mBYXXY
Deleting Files Or Directories.......................|netrw-DYXXY
Directory Exploring Commands........................|netrw-exploreYXXY
Exploring With Stars and Patterns...................|netrw-starYXXY
Displaying Information About File...................|netrw-qfYXXY
Edit File Or Directory Hiding List..................|netrw-ctrl-hYXXY
Editing The Sorting Sequence........................|netrw-SYXXY
Forcing treatment as a file or directory............|netrw-gd| |netrw-gf|
Going Up............................................|netrw--YXXY
Hiding Files Or Directories.........................|netrw-aYXXY
Improving Browsing..................................|netrw-ssh-hackYXXY
Listing Bookmarks And History.......................|netrw-qbYXXY
Making A New Directory..............................|netrw-dYXXY
Making The Browsing Directory The Current Directory.|netrw-cYXXY
Marking Files.......................................|netrw-mfYXXY
Unmarking Files.....................................|netrw-mFYXXY
Marking Files By QuickFix List......................|netrw-qFYXXY
Marking Files By Regular Expression.................|netrw-mrYXXY
Marked Files: Arbitrary Command.....................|netrw-mxYXXY
Marked Files: Compression And Decompression.........|netrw-mzYXXY
Marked Files: Copying...............................|netrw-mcYXXY
Marked Files: Diff..................................|netrw-mdYXXY
Marked Files: Editing...............................|netrw-meYXXY
Marked Files: Grep..................................|netrw-mgYXXY
Marked Files: Hiding and Unhiding by Suffix.........|netrw-mhYXXY
Marked Files: Moving................................|netrw-mmYXXY
Marked Files: Printing..............................|netrw-mpYXXY
Marked Files: Sourcing..............................|netrw-msYXXY
Marked Files: Setting the Target Directory..........|netrw-mtYXXY
Marked Files: Tagging...............................|netrw-mTYXXY
Marked Files: Target Directory Using Bookmarks......|netrw-TbYXXY
Marked Files: Target Directory Using History........|netrw-ThYXXY
Marked Files: Unmarking.............................|netrw-muYXXY
Netrw Browser Variables.............................|netrw-browser-varYXXY
Netrw Browsing And Option Incompatibilities.........|netrw-incompatibleYXXY
Netrw Settings Window...............................|netrw-settings-windowYXXY
Obtaining A File....................................|netrw-OYXXY
Preview Window......................................|netrw-pYXXY
Previous Window.....................................|netrw-PYXXY
Refreshing The Listing..............................|netrw-ctrl-lYXXY
Reversing Sorting Order.............................|netrw-rYXXY
Renaming Files Or Directories.......................|netrw-RYXXY
Selecting Sorting Style.............................|netrw-sYXXY
Setting Editing Window..............................|netrw-CYXXY
10. Problems and Fixes....................................|netrw-problemsYXXY
11. Debugging Netrw Itself................................|netrw-debugYXXY
12. History...............................................|netrw-historyYXXY
13. Todo..................................................|netrw-todoYXXY
14. Credits...............................................|netrw-creditsYXXY
{Vi does not have any of this}
==============================================================================
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 YXXYnetrw-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
rcp: *g:netrw_rcp_cmd* = "rcp"
rsync: *g:netrw_rsync_cmd* = "rsync -a"
scp: *g:netrw_scp_cmd* = "scp -q"
sftp: *g:netrw_sftp_cmd* = "sftp"
*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 : "-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.
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
YXXYnetrw-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 file edits will take
place. (also see |netrw-C|)
(default) not defined
*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_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.
*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* =1 : messages from netrw will use a separate one
line window. This window provides reliable
delivery of messages. (default)
=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 VimL-based 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
*