/
pi_netrw.txt
4409 lines (3603 loc) · 177 KB
/
pi_netrw.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*pi_netrw.txt* For Vim version 8.2. Last change: 2020 Aug 15
------------------------------------------------
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| )