diff options
Diffstat (limited to 'runtime/doc/pi_netrw.txt')
| -rw-r--r-- | runtime/doc/pi_netrw.txt | 543 |
1 files changed, 543 insertions, 0 deletions
diff --git a/runtime/doc/pi_netrw.txt b/runtime/doc/pi_netrw.txt new file mode 100644 index 000000000..abfa8ce2f --- /dev/null +++ b/runtime/doc/pi_netrw.txt @@ -0,0 +1,543 @@ +*pi_netrw.txt* For Vim version 7.0aa. Last change: Apr 21, 2004 + + + VIM REFERENCE MANUAL by Charles E. Campbell, Jr. + +*dav* *http* *network* *rcp* *scp* +*fetch* *netrw* *Nread* *rsync* *sftp* +*ftp* *netrw.vim* *Nwrite* *netrw-file* + +============================================================================== +0. Contents *netrw-contents* + +1. Netrw Reference.....................................|netrw-ref| +2. Network-Oriented File Transfer......................|netrw-xfer| +3. Activation..........................................|netrw-activate| +4. Transparent File Transfer...........................|netrw-transparent| +5. Ex Commands.........................................|netrw-ex| +6. Variables and Options...............................|netrw-var| +7. Debugging...........................................|netrw-debug| +8. New Stuff...........................................|netrw-new| +9. Credits.............................................|netrw-credits| + +The functionality mentioned here is done via using |standard-plugin| +techniques. This plugin is only available if + + set nocp " 'compatible' is not set + filetype plugin on " plugins are enabled + +You can avoid loading this plugin by setting the "loaded_netrw" variable +in your <.vimrc> file: > + + :let loaded_netrw = 1 + +{Vi does not have any of this} + +============================================================================== +1. Netrw Reference *netrw-ref* + + OPTIONS + let g:netrw_ftp =0 use ftp (default) (uid password) + =1 use alternate ftp method (user uid password) + If you're having trouble with ftp, try changing the value + of this variable in your <.vimrc> to change methods + + let g:netrw_ignorenetrc= 1 + If you have a <.netrc> file but it doesn't work and you + want it ignored, then set this variable as shown. Its mere + existence is enough to cause <.netrc> to be ignored. + + Controlling External Applications + + Protocol Variable Default Value + -------- ---------------- ------------- + dav: g:netrw_dav_cmd = "cadaver" + fetch: g:netrw_fetch_cmd = "fetch -o" + ftp: g:netrw_ftp_cmd = "ftp" + http: g:netrw_http_cmd = "fetch -o" else if fetch is available + http: g:netrw_http_cmd = "wget -q -O" If wget 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" + + READING + :Nread ? give help + :Nread "machine:file" uses rcp + :Nread "machine file" uses ftp with <.netrc> + :Nread "machine id password file" uses ftp + :Nread "dav://machine[:port]/file" uses cadaver + :Nread "fetch://[user@]machine/file" uses fetch + :Nread "ftp://[user@]machine[[:#]port]/file" uses ftp autodetects <.netrc> + :Nread "http://[user@]machine/file" uses http uses wget + :Nread "rcp://[user@]machine/file" uses rcp + :Nread "rsync://[user@]machine[:port]/file" uses rsync + :Nread "scp://[user@]machine[[:#]port]/file" uses scp + :Nread "sftp://[user@]machine/file" uses sftp + + WRITING + :Nwrite ? give help + :Nwrite "machine:file" uses rcp + :Nwrite "machine file" uses ftp with <.netrc> + :Nwrite "machine id password file" uses ftp + :Nwrite "dav://machine[:port]/file" uses cadaver + :Nwrite "ftp://[user@]machine[[:#]port]/file" uses ftp autodetects <.netrc> + :Nwrite "rcp://[user@]machine/file" uses rcp + :Nwrite "rsync://[user@]machine[:port]/file" uses rsync + :Nwrite "scp://[user@]machine[[:#]port]/file" uses scp + :Nwrite "sftp://[user@]machine/file" uses sftp + http: not supported! + + USER AND PASSWORD CHANGING + Attempts to use ftp will prompt you for a user-id and a password. + These will be saved in g:netrw_uid and g:netrw_passwd Subsequent uses + of ftp will re-use those. If you need to use a different user id + and/or password, you'll want to call NetUserPass() first. + + :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 + + VARIABLES + b:netrw_lastfile last file Network-read/written retained on + a per-buffer basis (supports plain :Nw ) + s:netrw_line during Nw/NetWrite, holds current line number + s:netrw_col during Nw/NetWrite, holds current column number + s:netrw_line and s:netrw_col are used to + restore the cursor position on writes + 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) + g:netrw_ftpmode ="binary" (default) + ="ascii" (or your choice) + g:netrw_uid (ftp) user-id, retained on a per-session basis + g:netrw_passwd (ftp) password, retained on a per-session basis + g:netrw_win95ftp =0 use unix-style ftp even if win95/win98/winME + =1 use default method to do ftp + g:netrw_cygwin =1 assume scp under windows is from cygwin + (default if windows) + =0 assume scp under windows accepts + windows-style paths (default otherwise) + g:netrw_use_nt_rcp=0 don't use the rcp of WinNT, Win2000 and WinXP (default) + =1 use the rcp of WinNT,... in binary mode + + +============================================================================== +2. Network-Oriented File Transfer *netrw-xfer* + +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, its 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. + +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"). + +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 executable, it will be used to do reads for +ftp://... (and http://...) . See |netrw-var| for more about this. + +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 just as 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 +< +However, ftp will often 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 | + +---------------------------------+----------------------------+------------+ + | 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 typical syntax for lines in a <.netrc> file is given as shown below. +Ftp under Unix usually support <.netrc>; Windows' ftp 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! + + +PASSWORD *netrw-passwd* + +The script attempts to get passwords for ftp invisibly using |inputsecret()|, +a built-in Vim function. See |netrw-uidpass| 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. + + +============================================================================== +3. Activation *netrw-activate* + +Network-oriented file transfers are available by default whenever +|'nocompatible'| mode is enabled. The <netrw.vim> file resides in your +system's vim-plugin directory and is sourced automatically whenever you +bring up vim. + + +============================================================================== +4. Transparent File Transfer *netrw-transparent* + +Transparent file transfers occur whenever a regular file read or write +(invoked via an |:autocmd| for |BufReadCmd| or |BufWriteCmd| events) is made. +Thus one may use files across networks as if they were local. > + + vim ftp://[user@]machine/path + ... + :wq + + +============================================================================== +5. Ex Commands *netrw-ex* + +The usual read/write commands are supported. There are also a couple of +additional commands available. + +:[range]Nw Write the specified lines to the current + file as specified in b:netrw_lastfile. + +:[range]Nw {netfile} [{netfile}]... + Write the specified lines to the {netfile}. + +:Nread + Read the specified lines into the current + buffer from the file specified in + b:netrw_lastfile. + +:Nread {netfile} {netfile}... + Read the {netfile} after the current line. + + *netrw-uidpass* +:call NetUserPass() + If b:netrw_uid and b:netrw_passwd don't exist, + this function query the user for them. + +:call NetUserPass("userid") + This call will set the b:netrw_uid and, if + the password doesn't exist, will query the user for it. + +:call NetUserPass("userid","passwd") + This call will set both the b:netrw_uid and b:netrw_passwd. + The user-id and password are used by ftp transfers. One may + effectively remove the user-id and password by using "" + strings. + + +============================================================================== +6. Variables and Options *netrw-options* *netrw-var* + +The script <netrw.vim> uses several variables which can affect <netrw.vim>'s +behavior. These variables typically may be set in the user's <.vimrc> file: + + g:netrw_uid Holds current user-id for ftp. + g:netrw_passwd Holds current password for ftp. + b:netrw_lastfile Holds latest method/machine/path. + b:netrw_line Holds current line number (during NetWrite) + b:netrw_col Holds current cursor position (during NetWrite) + g:netrw_ftp =0 use default ftp (uid password) + =1 use alternate ftp (user uid password) + (see |netrw-options|) + 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. + g:netrw_win95ftp =0 use unix-style ftp even if win95/98/ME/etc + =1 use default method to do ftp + 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_use_nt_rcp =0 don't use WinNT/2K/XP's rcp (default) + =1 use WinNT/2K/XP's rcp, binary mode + + +The script will also make use of the following variables internally, albeit +temporarily. + + g:netrw_method Index indicating rcp/ftp+.netrc/ftp + g:netrw_machine Holds machine name parsed from input + g:netrw_fname Holds filename being accessed + + *netrw-protocol* +> + ------------------------ + 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 variable ="cadaver" + g:netrw_fetch_cmd variable ="fetch -o" + g:netrw_ftp_cmd variable ="ftp" + g:netrw_http_cmd variable ="fetch -o" else if fetch is executable + g:netrw_http_cmd variable ="wget -O" if wget is executable + g:netrw_rcp_cmd variable ="rcp" + g:netrw_rsync_cmd variable ="rsync -a" + g:netrw_scp_cmd variable ="scp -q" + g:netrw_sftp_cmd variable ="sftp" +< +The first two options both help with certain ftp's that give trouble otherwise. +In order to best understand how to use these options if ftp is giving you +troubles, a bit of discussion follows on how netrw does ftp reads. + +The g:netrw_..._cmd variables specify the external program to use handle +the associated protocol (rcp, ftp, etc), plus any options. + +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 + get filename tempfile [g:netrw_ftpmode] + get filename tempfile +< +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-fixup* +If your ftp for whatever reason generates unwanted lines (such as AUTH +messages) you may write a NetReadFixup(tmpfile) 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 + fu! NetReadFixup(method, line1, line2) + if method == 3 " ftp (no <.netrc>) + let fourblanklines= line2 - 3 + silent fourblanklines.",".line2."g/^\s*/d" + endif + endfunction + endif +> + +============================================================================== +7. Debugging *netrw-debug* + +The <netrw.vim> script is typically available as: + + /usr/local/share/vim/vim6x/plugin/netrw.vim + +which is loaded automatically at startup (assuming :set nocp). + + 1. Get the <Decho.vim> script, available as: + + http://mysite.verizon.net/astronaut/vim/index.html#vimlinks_scripts + as "Decho, a vimL debugging aid" + or + http://vim.sourceforge.net/scripts/script.php?script_id=120 + + and put it into your local plugin directory + + 2. Edit the <netrw.vim> file as follows: + + :DechoOn + + (to restore to normal, use :DechoOff ) + + 3. Then bring up vim and attempt a transfer. A set of messages + should appear concerning the steps that <netrw.vim> took in + attempting to read/write your file over the network. Please + send that information to <netrw.vim>'s maintainer, + + drchipNOSPAM at campbellfamily.biz - NOSPAM + +============================================================================== +8. New Stuff *netrw-new* *netrw-newstuff* + + v43: * moved "Explanation" comments to <pi_netrw.txt> help file + as "Network Reference" (|netrw-ref|) + * <netrw.vim> now uses Dfunc() Decho() and Dret() for debugging + * removed superfluous NetRestorePosn() calls + v42: * now does BufReadPre and BufReadPost events on file:///* + and file://localhost/* + v41: * installed file:///* and file://localhost/* handling + v40: * prevents redraw when a protocol error occurs so that the + user may see it + v39: * sftp support + v38: * Now uses NetRestorePosn() calls with Nread/Nwrite commands + * Temporary files now removed via bwipe! instead of bwipe + (thanks to Dave Roberts) + v37: * Claar's modifications which test if ftp is successful, otherwise + give an error message + * After a read, the alternate file was pointing to the temp file. + The temp file buffer is now wiped out. + * removed silent from transfer methods so user can see what's + happening + + +============================================================================== +9. Credits *netrw-credits* + + Vim editor by Bram Moolenaar (Thanks, Bram!) + dav support by C Campbell + fetch support by Bram Moolenaar and C Campbell + ftp support by C Campbell <NdrOchip@ScampbellPfamily.AbizM> - NOSPAM + http support by Bram Moolenaar <bram@moolenaar.net> + rcp + rsync support by C Campbell (suggested by Erik Warendorph) + scp support by raf <raf@comdyn.com.au> + sftp support by C Campbell + + inputsecret(), BufReadCmd, BufWriteCmd contributed by C Campbell + + Jérôme Augé -- also using new buffer method with ftp+.netrc + Bram Moolenaar -- obviously vim itself, :e and v:cmdarg use, fetch,... + Yasuhiro Matsumoto -- pointing out undo+0r problem and a solution + Erik Warendorph -- for several suggestions (g:netrw_..._cmd + variables, rsync etc) + Doug Claar -- modifications to test for success with ftp operation + +============================================================================== + vim:tw=78:ts=8:ft=help:norl: |