blob: abfa8ce2ffcae1336c4e7473d338a86f097893a0 [file] [log] [blame]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001*pi_netrw.txt* For Vim version 7.0aa. Last change: Apr 21, 2004
2
3
4 VIM REFERENCE MANUAL by Charles E. Campbell, Jr.
5
6*dav* *http* *network* *rcp* *scp*
7*fetch* *netrw* *Nread* *rsync* *sftp*
8*ftp* *netrw.vim* *Nwrite* *netrw-file*
9
10==============================================================================
110. Contents *netrw-contents*
12
131. Netrw Reference.....................................|netrw-ref|
142. Network-Oriented File Transfer......................|netrw-xfer|
153. Activation..........................................|netrw-activate|
164. Transparent File Transfer...........................|netrw-transparent|
175. Ex Commands.........................................|netrw-ex|
186. Variables and Options...............................|netrw-var|
197. Debugging...........................................|netrw-debug|
208. New Stuff...........................................|netrw-new|
219. Credits.............................................|netrw-credits|
22
23The functionality mentioned here is done via using |standard-plugin|
24techniques. This plugin is only available if
25
26 set nocp " 'compatible' is not set
27 filetype plugin on " plugins are enabled
28
29You can avoid loading this plugin by setting the "loaded_netrw" variable
30in your <.vimrc> file: >
31
32 :let loaded_netrw = 1
33
34{Vi does not have any of this}
35
36==============================================================================
371. Netrw Reference *netrw-ref*
38
39 OPTIONS
40 let g:netrw_ftp =0 use ftp (default) (uid password)
41 =1 use alternate ftp method (user uid password)
42 If you're having trouble with ftp, try changing the value
43 of this variable in your <.vimrc> to change methods
44
45 let g:netrw_ignorenetrc= 1
46 If you have a <.netrc> file but it doesn't work and you
47 want it ignored, then set this variable as shown. Its mere
48 existence is enough to cause <.netrc> to be ignored.
49
50 Controlling External Applications
51
52 Protocol Variable Default Value
53 -------- ---------------- -------------
54 dav: g:netrw_dav_cmd = "cadaver"
55 fetch: g:netrw_fetch_cmd = "fetch -o"
56 ftp: g:netrw_ftp_cmd = "ftp"
57 http: g:netrw_http_cmd = "fetch -o" else if fetch is available
58 http: g:netrw_http_cmd = "wget -q -O" If wget is available
59 rcp: g:netrw_rcp_cmd = "rcp"
60 rsync: g:netrw_rsync_cmd = "rsync -a"
61 scp: g:netrw_scp_cmd = "scp -q"
62 sftp: g:netrw_sftp_cmd = "sftp"
63
64 READING
65 :Nread ? give help
66 :Nread "machine:file" uses rcp
67 :Nread "machine file" uses ftp with <.netrc>
68 :Nread "machine id password file" uses ftp
69 :Nread "dav://machine[:port]/file" uses cadaver
70 :Nread "fetch://[user@]machine/file" uses fetch
71 :Nread "ftp://[user@]machine[[:#]port]/file" uses ftp autodetects <.netrc>
72 :Nread "http://[user@]machine/file" uses http uses wget
73 :Nread "rcp://[user@]machine/file" uses rcp
74 :Nread "rsync://[user@]machine[:port]/file" uses rsync
75 :Nread "scp://[user@]machine[[:#]port]/file" uses scp
76 :Nread "sftp://[user@]machine/file" uses sftp
77
78 WRITING
79 :Nwrite ? give help
80 :Nwrite "machine:file" uses rcp
81 :Nwrite "machine file" uses ftp with <.netrc>
82 :Nwrite "machine id password file" uses ftp
83 :Nwrite "dav://machine[:port]/file" uses cadaver
84 :Nwrite "ftp://[user@]machine[[:#]port]/file" uses ftp autodetects <.netrc>
85 :Nwrite "rcp://[user@]machine/file" uses rcp
86 :Nwrite "rsync://[user@]machine[:port]/file" uses rsync
87 :Nwrite "scp://[user@]machine[[:#]port]/file" uses scp
88 :Nwrite "sftp://[user@]machine/file" uses sftp
89 http: not supported!
90
91 USER AND PASSWORD CHANGING
92 Attempts to use ftp will prompt you for a user-id and a password.
93 These will be saved in g:netrw_uid and g:netrw_passwd Subsequent uses
94 of ftp will re-use those. If you need to use a different user id
95 and/or password, you'll want to call NetUserPass() first.
96
97 :NetUserPass [uid [password]] -- prompts as needed
98 :call NetUserPass() -- prompts for uid and password
99 :call NetUserPass("uid") -- prompts for password
100 :call NetUserPass("uid","password") -- sets global uid and password
101
102 VARIABLES
103 b:netrw_lastfile last file Network-read/written retained on
104 a per-buffer basis (supports plain :Nw )
105 s:netrw_line during Nw/NetWrite, holds current line number
106 s:netrw_col during Nw/NetWrite, holds current column number
107 s:netrw_line and s:netrw_col are used to
108 restore the cursor position on writes
109 g:netrw_ftp if it doesn't exist, use default ftp
110 =0 use default ftp (uid password)
111 =1 use alternate ftp method (user uid password)
112 g:netrw_ftpmode ="binary" (default)
113 ="ascii" (or your choice)
114 g:netrw_uid (ftp) user-id, retained on a per-session basis
115 g:netrw_passwd (ftp) password, retained on a per-session basis
116 g:netrw_win95ftp =0 use unix-style ftp even if win95/win98/winME
117 =1 use default method to do ftp
118 g:netrw_cygwin =1 assume scp under windows is from cygwin
119 (default if windows)
120 =0 assume scp under windows accepts
121 windows-style paths (default otherwise)
122 g:netrw_use_nt_rcp=0 don't use the rcp of WinNT, Win2000 and WinXP (default)
123 =1 use the rcp of WinNT,... in binary mode
124
125
126==============================================================================
1272. Network-Oriented File Transfer *netrw-xfer*
128
129Network-oriented file transfer under Vim is implemented by a VimL-based script
130(<netrw.vim>) using plugin techniques. It currently supports both reading
131and writing across networks using rcp, scp, ftp or ftp+<.netrc>, scp, fetch,
132dav/cadaver, rsync, or sftp.
133
134http is currently supported read-only via use of wget or fetch.
135
136<netrw.vim> is a standard plugin which acts as glue between Vim and the
137various file transfer programs. It uses autocommand events (BufReadCmd,
138FileReadCmd, BufWriteCmd) to intercept reads/writes with url-like filenames. >
139
140 ex. vim ftp://hostname/path/to/file
141<
142The characters preceding the colon specify the protocol to use;
143in the example, its ftp. The <netrw.vim> script then formulates
144a command or a series of commands (typically ftp) which it issues
145to an external program (ftp, scp, etc) which does the actual file
146transfer/protocol. Files are read from/written to a temporary file
147(under Unix/Linux, /tmp/...) which the <netrw.vim> script will
148clean up.
149
150One may modify any protocol's implementing external application
151by setting a variable (ex. scp uses the variable g:netrw_scp_cmd,
152which is defaulted to "scp -q").
153
154Ftp, an old protocol, seems to be blessed by numerous implementations.
155Unfortunately, some implementations are noisy (ie., add junk to the end
156of the file). Thus, concerned users may decide to write a NetReadFixup()
157function that will clean up after reading with their ftp. Some Unix systems
158(ie., FreeBSD) provide a utility called "fetch" which uses the ftp protocol
159but is not noisy and more convenient, actually, for <netrw.vim> to use.
160Consequently, if "fetch" is executable, it will be used to do reads for
161ftp://... (and http://...) . See |netrw-var| for more about this.
162
163For rcp, scp, sftp, and http, one may use network-oriented file transfers
164transparently; ie.
165>
166 vim rcp://[user@]machine/path
167 vim scp://[user@]machine/path
168<
169If your ftp supports <.netrc>, then it too can be just as transparently used
170if the needed triad of machine name, user id, and password are present in
171that file. Your ftp must be able to use the <.netrc> file on its own, however.
172>
173 vim ftp://[user@]machine[[:#]portnumber]/path
174<
175However, ftp will often need to query the user for the userid and password.
176The latter will be done "silently"; ie. asterisks will show up instead of
177the actually-typed-in password. Netrw will retain the userid and password
178for subsequent read/writes from the most recent transfer so subsequent
179transfers (read/write) to or from that machine will take place without
180additional prompting.
181
182 *netrw-urls*
183 +=================================+============================+============+
184 | Reading | Writing | Uses |
185 +=================================+============================+============+
186 | DAV: | | |
187 | dav://host/path | | cadaver |
188 | :Nread dav://host/path | :Nwrite dav://host/path | cadaver |
189 +---------------------------------+----------------------------+------------+
190 | FETCH: | | |
191 | fetch://[user@]host/path | | |
192 | fetch://[user@]host:http/path | Not Available | fetch |
193 | :Nread fetch://[user@]host/path| | |
194 +---------------------------------+----------------------------+------------+
195 | FILE: | | |
196 | file:///* | file:///* | |
197 | file://localhost/* | file://localhost/* | |
198 +---------------------------------+----------------------------+------------+
199 | FTP: (*3) | (*3) | |
200 | ftp://[user@]host/path | ftp://[user@]host/path | ftp (*2) |
201 | :Nread ftp://host/path | :Nwrite ftp://host/path | ftp+.netrc |
202 | :Nread host path | :Nwrite host path | ftp+.netrc |
203 | :Nread host uid pass path | :Nwrite host uid pass path | ftp |
204 +---------------------------------+----------------------------+------------+
205 | HTTP: wget is executable: (*4) | | |
206 | http://[user@]host/path | Not Available | wget |
207 +---------------------------------+----------------------------+------------+
208 | HTTP: fetch is executable (*4) | | |
209 | http://[user@]host/path | Not Available | fetch |
210 +---------------------------------+----------------------------+------------+
211 | RCP: | | |
212 | rcp://[user@]host/path | rcp://[user@]host/path | rcp |
213 +---------------------------------+----------------------------+------------+
214 | RSYNC: | | |
215 | rsync://[user@]host/path | rsync://[user@]host/path | rsync |
216 | :Nread rsync://host/path | :Nwrite rsync://host/path | rsync |
217 | :Nread rcp://host/path | :Nwrite rcp://host/path | rcp |
218 +---------------------------------+----------------------------+------------+
219 | SCP: | | |
220 | scp://[user@]host/path | scp://[user@]host/path | scp |
221 | :Nread scp://host/path | :Nwrite scp://host/path | scp (*1) |
222 +---------------------------------+----------------------------+------------+
223 | SFTP: | | |
224 | sftp://[user@]host/path | sftp://[user@]host/path | sftp |
225 | :Nread sftp://host/path | :Nwrite sftp://host/path | sftp (*1) |
226 +=================================+============================+============+
227
228 (*1) For an absolute path use scp://machine//path.
229
230 (*2) if <.netrc> is present, it is assumed that it will
231 work with your ftp client. Otherwise the script will
232 prompt for user-id and password.
233
234 (*3) for ftp, "machine" may be machine#port or machine:port
235 if a different port is needed than the standard ftp port
236
237 (*4) for http:..., if wget is available it will be used. Otherwise,
238 if fetch is available it will be used.
239
240Both the :Nread and the :Nwrite ex-commands can accept multiple filenames.
241
242
243NETRC *netrw-netrc*
244
245The typical syntax for lines in a <.netrc> file is given as shown below.
246Ftp under Unix usually support <.netrc>; Windows' ftp usually doesn't.
247>
248 machine {full machine name} login {user-id} password "{password}"
249 default login {user-id} password "{password}"
250
251Your ftp client must handle the use of <.netrc> on its own, but if the
252<.netrc> file exists, an ftp transfer will not ask for the user-id or
253password.
254
255 Note:
256 Since this file contains passwords, make very sure nobody else can
257 read this file! Most programs will refuse to use a .netrc that is
258 readable for others. Don't forget that the system administrator can
259 still read the file!
260
261
262PASSWORD *netrw-passwd*
263
264The script attempts to get passwords for ftp invisibly using |inputsecret()|,
265a built-in Vim function. See |netrw-uidpass| for how to change the password
266after one has set it.
267
268Unfortunately there doesn't appear to be a way for netrw to feed a password
269to scp. Thus every transfer via scp will require re-entry of the password.
270
271
272==============================================================================
2733. Activation *netrw-activate*
274
275Network-oriented file transfers are available by default whenever
276|'nocompatible'| mode is enabled. The <netrw.vim> file resides in your
277system's vim-plugin directory and is sourced automatically whenever you
278bring up vim.
279
280
281==============================================================================
2824. Transparent File Transfer *netrw-transparent*
283
284Transparent file transfers occur whenever a regular file read or write
285(invoked via an |:autocmd| for |BufReadCmd| or |BufWriteCmd| events) is made.
286Thus one may use files across networks as if they were local. >
287
288 vim ftp://[user@]machine/path
289 ...
290 :wq
291
292
293==============================================================================
2945. Ex Commands *netrw-ex*
295
296The usual read/write commands are supported. There are also a couple of
297additional commands available.
298
299:[range]Nw Write the specified lines to the current
300 file as specified in b:netrw_lastfile.
301
302:[range]Nw {netfile} [{netfile}]...
303 Write the specified lines to the {netfile}.
304
305:Nread
306 Read the specified lines into the current
307 buffer from the file specified in
308 b:netrw_lastfile.
309
310:Nread {netfile} {netfile}...
311 Read the {netfile} after the current line.
312
313 *netrw-uidpass*
314:call NetUserPass()
315 If b:netrw_uid and b:netrw_passwd don't exist,
316 this function query the user for them.
317
318:call NetUserPass("userid")
319 This call will set the b:netrw_uid and, if
320 the password doesn't exist, will query the user for it.
321
322:call NetUserPass("userid","passwd")
323 This call will set both the b:netrw_uid and b:netrw_passwd.
324 The user-id and password are used by ftp transfers. One may
325 effectively remove the user-id and password by using ""
326 strings.
327
328
329==============================================================================
3306. Variables and Options *netrw-options* *netrw-var*
331
332The script <netrw.vim> uses several variables which can affect <netrw.vim>'s
333behavior. These variables typically may be set in the user's <.vimrc> file:
334
335 g:netrw_uid Holds current user-id for ftp.
336 g:netrw_passwd Holds current password for ftp.
337 b:netrw_lastfile Holds latest method/machine/path.
338 b:netrw_line Holds current line number (during NetWrite)
339 b:netrw_col Holds current cursor position (during NetWrite)
340 g:netrw_ftp =0 use default ftp (uid password)
341 =1 use alternate ftp (user uid password)
342 (see |netrw-options|)
343 g:netrw_ftpmode ="binary" (default)
344 ="ascii" (your choice)
345 g:netrw_ignorenetrc =1 (default)
346 if you have a <.netrc> file but you don't
347 want it used, then set this variable. Its
348 mere existence is enough to cause <.netrc>
349 to be ignored.
350 g:netrw_win95ftp =0 use unix-style ftp even if win95/98/ME/etc
351 =1 use default method to do ftp
352 g:netrw_cygwin =1 assume scp under windows is from cygwin
353 (default/windows)
354 =0 assume scp under windows accepts windows
355 style paths (default/else)
356 g:netrw_use_nt_rcp =0 don't use WinNT/2K/XP's rcp (default)
357 =1 use WinNT/2K/XP's rcp, binary mode
358
359
360The script will also make use of the following variables internally, albeit
361temporarily.
362
363 g:netrw_method Index indicating rcp/ftp+.netrc/ftp
364 g:netrw_machine Holds machine name parsed from input
365 g:netrw_fname Holds filename being accessed
366
367 *netrw-protocol*
368>
369 ------------------------
370 Protocol Control Options
371 ------------------------
372 Option Type Setting Meaning ~
373 --------- -------- -------------- --------------------------- >
374 netrw_ftp variable =doesn't exist userid set by "user userid"
375 =0 userid set by "user userid"
376 =1 userid set by "userid"
377 NetReadFixup function =doesn't exist no change
378 =exists Allows user to have files
379 read via ftp automatically
380 transformed however they wish
381 by NetReadFixup()
382 g:netrw_dav_cmd variable ="cadaver"
383 g:netrw_fetch_cmd variable ="fetch -o"
384 g:netrw_ftp_cmd variable ="ftp"
385 g:netrw_http_cmd variable ="fetch -o" else if fetch is executable
386 g:netrw_http_cmd variable ="wget -O" if wget is executable
387 g:netrw_rcp_cmd variable ="rcp"
388 g:netrw_rsync_cmd variable ="rsync -a"
389 g:netrw_scp_cmd variable ="scp -q"
390 g:netrw_sftp_cmd variable ="sftp"
391<
392The first two options both help with certain ftp's that give trouble otherwise.
393In order to best understand how to use these options if ftp is giving you
394troubles, a bit of discussion follows on how netrw does ftp reads.
395
396The g:netrw_..._cmd variables specify the external program to use handle
397the associated protocol (rcp, ftp, etc), plus any options.
398
399Netrw typically builds up lines of one of the following formats in a
400temporary file:
401>
402 IF g:netrw_ftp !exists or is not 1 IF g:netrw_ftp exists and is 1
403 ---------------------------------- ------------------------------
404 open machine [port] open machine [port]
405 user userid password userid password
406 [g:netrw_ftpmode] password
407 get filename tempfile [g:netrw_ftpmode]
408 get filename tempfile
409<
410Netrw then executes the lines above by use of a filter:
411>
412 :%! {g:netrw_ftp_cmd} -i [-n]
413<
414
415where
416 g:netrw_ftp_cmd is usually "ftp",
417 -i tells ftp not to be interactive
418 -n means don't use netrc and is used for Method #3 (ftp w/o <.netrc>)
419
420If <.netrc> exists it will be used to avoid having to query the user for
421userid and password). The transferred file is put into a temporary file.
422The temporary file is then read into the main editing session window that
423requested it and the temporary file deleted.
424
425If your ftp doesn't accept the "user" command and immediately just demands
426a userid, then try putting "let netrw_ftp=1" in your <.vimrc>.
427
428 *netrw-fixup*
429If your ftp for whatever reason generates unwanted lines (such as AUTH
430messages) you may write a NetReadFixup(tmpfile) function:
431>
432 function! NetReadFixup(method,line1,line2)
433 " a:line1: first new line in current file
434 " a:line2: last new line in current file
435 if a:method == 1 "rcp
436 elseif a:method == 2 "ftp + <.netrc>
437 elseif a:method == 3 "ftp + machine,uid,password,filename
438 elseif a:method == 4 "scp
439 elseif a:method == 5 "http/wget
440 elseif a:method == 6 "dav/cadaver
441 elseif a:method == 7 "rsync
442 elseif a:method == 8 "fetch
443 elseif a:method == 9 "sftp
444 else " complain
445 endif
446 endfunction
447>
448The NetReadFixup() function will be called if it exists and thus allows
449you to customize your reading process. As a further example, <netrw.vim>
450contains just such a function to handle Windows 95 ftp. For whatever
451reason, Windows 95's ftp dumps four blank lines at the end of a transfer,
452and so it is desirable to automate their removal. Here's some code taken
453from <netrw.vim> itself:
454>
455 if has("win95") && g:netrw_win95ftp
456 fu! NetReadFixup(method, line1, line2)
457 if method == 3 " ftp (no <.netrc>)
458 let fourblanklines= line2 - 3
459 silent fourblanklines.",".line2."g/^\s*/d"
460 endif
461 endfunction
462 endif
463>
464
465==============================================================================
4667. Debugging *netrw-debug*
467
468The <netrw.vim> script is typically available as:
469
470 /usr/local/share/vim/vim6x/plugin/netrw.vim
471
472which is loaded automatically at startup (assuming :set nocp).
473
474 1. Get the <Decho.vim> script, available as:
475
476 http://mysite.verizon.net/astronaut/vim/index.html#vimlinks_scripts
477 as "Decho, a vimL debugging aid"
478 or
479 http://vim.sourceforge.net/scripts/script.php?script_id=120
480
481 and put it into your local plugin directory
482
483 2. Edit the <netrw.vim> file as follows:
484
485 :DechoOn
486
487 (to restore to normal, use :DechoOff )
488
489 3. Then bring up vim and attempt a transfer. A set of messages
490 should appear concerning the steps that <netrw.vim> took in
491 attempting to read/write your file over the network. Please
492 send that information to <netrw.vim>'s maintainer,
493
494 drchipNOSPAM at campbellfamily.biz - NOSPAM
495
496==============================================================================
4978. New Stuff *netrw-new* *netrw-newstuff*
498
499 v43: * moved "Explanation" comments to <pi_netrw.txt> help file
500 as "Network Reference" (|netrw-ref|)
501 * <netrw.vim> now uses Dfunc() Decho() and Dret() for debugging
502 * removed superfluous NetRestorePosn() calls
503 v42: * now does BufReadPre and BufReadPost events on file:///*
504 and file://localhost/*
505 v41: * installed file:///* and file://localhost/* handling
506 v40: * prevents redraw when a protocol error occurs so that the
507 user may see it
508 v39: * sftp support
509 v38: * Now uses NetRestorePosn() calls with Nread/Nwrite commands
510 * Temporary files now removed via bwipe! instead of bwipe
511 (thanks to Dave Roberts)
512 v37: * Claar's modifications which test if ftp is successful, otherwise
513 give an error message
514 * After a read, the alternate file was pointing to the temp file.
515 The temp file buffer is now wiped out.
516 * removed silent from transfer methods so user can see what's
517 happening
518
519
520==============================================================================
5219. Credits *netrw-credits*
522
523 Vim editor by Bram Moolenaar (Thanks, Bram!)
524 dav support by C Campbell
525 fetch support by Bram Moolenaar and C Campbell
526 ftp support by C Campbell <NdrOchip@ScampbellPfamily.AbizM> - NOSPAM
527 http support by Bram Moolenaar <bram@moolenaar.net>
528 rcp
529 rsync support by C Campbell (suggested by Erik Warendorph)
530 scp support by raf <raf@comdyn.com.au>
531 sftp support by C Campbell
532
533 inputsecret(), BufReadCmd, BufWriteCmd contributed by C Campbell
534
535 Jérôme Augé -- also using new buffer method with ftp+.netrc
536 Bram Moolenaar -- obviously vim itself, :e and v:cmdarg use, fetch,...
537 Yasuhiro Matsumoto -- pointing out undo+0r problem and a solution
538 Erik Warendorph -- for several suggestions (g:netrw_..._cmd
539 variables, rsync etc)
540 Doug Claar -- modifications to test for success with ftp operation
541
542==============================================================================
543 vim:tw=78:ts=8:ft=help:norl: