| blob | 826abc9392ee6cb6ca1c512e5e042aeb5ed3f551 |
1 *cmdline.txt* For Vim version 5.8. Last change: 2000 Nov 16
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 *Cmdline-mode* *Command-line-mode*
8 Command-line mode *Cmdline* *Command-line* *mode-cmdline* *:*
10 Command-line mode is used to enter Ex commands (":"), search patterns
11 ("/" and "?"), and filter commands ("!").
13 1. Command-line editing |cmdline-editing|
14 2. Command-line completion |cmdline-completion|
15 3. Ex command-lines |cmdline-lines|
16 4. Ex command-line ranges |cmdline-ranges|
17 5. Ex special characters |cmdline-special|
19 ==============================================================================
20 1. Command-line editing *cmdline-editing*
22 Normally characters are inserted in front of the cursor position. You can
23 move around in the command-line with the left and right cursor keys. With the
24 <Insert> key, you can toggle between inserting and overstriking characters.
25 {Vi: can only alter the last character in the line}
27 Note that if your keyboard does not have working cursor keys or any of the
28 other special keys, you can use ":cnoremap" to define another key for them.
29 For example, to define tcsh style editing keys: *tcsh-style*
30 > :cnoremap <C-A> <Home>
31 > :cnoremap <C-F> <Right>
32 > :cnoremap <C-B> <Left>
33 > :cnoremap <Esc>b <S-Left>
34 > :cnoremap <Esc>f <S-Right>
35 (<> notation |<>|; type all this literally)
37 *cmdline-too-long*
38 When the command line is getting longer than what fits on the screen, only the
39 part that fits will be shown. The cursor can only move in this visible part,
40 thus you cannot edit beyond that.
42 *cmdline-history*
43 The command-lines that you enter are remembered in a history table. You can
44 recall them with the up and down cursor keys. There are actually four
45 history tables:
46 - one for ':' commands
47 - one for search strings
48 - one for expressions
49 - one for input lines, typed for the |input()| function.
50 These are completely separate. Each history can only be accessed when
51 entering the same type of line.
52 Use the 'history' option to set the number of lines that are remembered
53 (default: 20).
54 Notes:
55 - When you enter a command-line that is exactly the same as an older one, the
56 old one is removed (to avoid repeated commands moving older commands out of
57 the history).
58 - Only commands that are typed are remembered. Ones that completely come from
59 mappings are not put in the history
60 - All searches are put in the search history, including the ones that come
61 from commands like "*" and "#". But for a mapping, only the last search is
62 remembered (to avoid that long mappings trash the history).
63 {Vi: no history}
65 There is an automatic completion of names on the command-line; see
66 |cmdline-completion|.
68 *c_CTRL-V*
69 CTRL-V Insert next non-digit literally. Up to three digits form the
70 decimal value of a single byte. The non-digit and the three
71 digits are not considered for mapping. This works the same
72 way as in Insert mode (see above, |i_CTRL-V|).
73 Note: Under Windows CTRL-V is often mapped to paste text.
74 Use CTRL-Q instead then.
75 *c_CTRL-Q*
76 CTRL-Q Same as CTRL-V.
78 *c_<Left>*
79 <Left> cursor left
80 *c_<Right>*
81 <Right> cursor right
82 *c_<S-Left>*
83 <S-Left> or <C-Left> *c_<C-Left>*
84 cursor one WORD left
85 *c_<S-Right>*
86 <S-Right> or <C-Right> *c_<C-Right>*
87 cursor one WORD right
88 CTRL-B or <Home> *c_CTRL-B* *c_<Home>*
89 cursor to beginning of command-line
90 CTRL-E or <End> *c_CTRL-E* *c_<End>*
91 cursor to end of command-line
93 *c_<LeftMouse>*
94 <LeftMouse> cursor to position of mouse click.
96 CTRL-H *c_<BS>* *c_CTRL-H*
97 <BS> delete the character in front of the cursor (see |:fixdel| if
98 your <BS> key does not do what you want).
99 *c_<Del>*
100 <Del> delete the character under the cursor (at end of line:
101 character before the cursor) (see |:fixdel| if your <Del>
102 key does not do what you want).
103 *c_CTRL-W*
104 CTRL-W delete the word before the cursor
105 *c_CTRL-U*
106 CTRL-U remove all characters
108 Note: if the command-line becomes empty with one of the
109 delete commands, Command-line mode is quit.
110 *c_<Insert>*
111 <Insert> Toggle between insert and overstrike. {not in Vi}
113 {char1} <BS> {char2} or *c_digraph*
114 CTRL-K {char1} {char2} *c_CTRL-K*
115 enter digraph (see |digraphs|). When {char1} is a special
116 key, the code for that key is inserted in <> form. {not in Vi}
118 CTRL-R {0-9a-z"%#:-=.} *c_CTRL-R* *c_<C-R>*
119 Insert the contents of a numbered or named register. Between
120 typing CTRL-R and the second character '"' will be displayed
121 to indicate that you are expected to enter the name of a
122 register.
123 The text is inserted as if you typed it, but mappings and
124 abbreviations are not used. Characters that end the command
125 line are inserted literally (<Esc>, <CR>, <NL>, <C-C>). A
126 <BS> or CTRL-W could still end the command line though, and
127 remaining characters will then be interpreted in another mode,
128 which might not be what you intended.
129 Special registers:
130 '"' the unnamed register, containing the text of
131 the last delete or yank
132 '%' the current file name
133 '#' the alternate file name
134 '*' the clipboard contents
135 '/' the last search pattern
136 ':' the last command-line
137 '-' the last small (less than a line) delete
138 '.' the last inserted text
139 '=' the expression register: you are prompted to
140 enter an expression (see |expression|)
141 See |registers| about registers. {not in Vi}
142 CTRL-R CTRL-F
143 CTRL-R CTRL-P
144 CTRL-R CTRL-W
145 CTRL-R CTRL-A
146 Insert the object under the cursor:
147 CTRL-F the Filename under the cursor
148 CTRL-P the Filename under the cursor, expanded with
149 'path' as in |gf|
150 CTRL-W the Word under the cursor
151 CTRL-A the WORD under the cursor; see |WORD|
152 {not in Vi}
153 CTRL-F and CTRL-P: {only when +file_in_path feature is
154 included}
156 *c_CTRL-R_CTRL-R* *c_<C-R>_<C-R>*
157 CTRL-R CTRL-R {0-9a-z"%#:-=. CTRL-F CTRL-P CTRL-W CTRL-A}
158 Insert register or object under the cursor. Works like
159 |c_CTRL-R| but inserts the text literally. For example, if
160 register a contains "xy^Hz" (where ^H is a backspace),
161 "CTRL-R a" will insert "xz" while "CTRL-R CTRL-R a" will
162 insert "xy^Hz".
164 CTRL-J *c_CTRL-J* *c_<NL>* *c_<CR>*
165 <CR> or <NL> start entered command
166 *c_<Esc>*
167 <Esc> When typed and 'x' not present in 'cpoptions', quit
168 Command-line mode without executing. In macros or when 'x'
169 present in 'cpoptions', start entered command.
170 *c_CTRL-C*
171 CTRL-C quit command-line without executing
173 *c_<Up>*
174 <Up> recall older command-line from history, whose beginning
175 matches the current command-line (see below).
176 *c_<Down>*
177 <Down> recall more recent command-line from history, whose beginning
178 matches the current command-line (see below).
180 *c_<S-Up>* *c_<PageUp>*
181 <S-Up> or <PageUp>
182 recall older command-line from history
183 *c_<S-Down>* *c_<PageDown>*
184 <S-Down> or <PageDown>
185 recall more recent command-line from history
187 CTRL-D command-line completion (see |cmdline-completion|)
188 'wildchar' option
189 command-line completion (see |cmdline-completion|)
190 CTRL-N command-line completion (see |cmdline-completion|)
191 CTRL-P command-line completion (see |cmdline-completion|)
192 CTRL-A command-line completion (see |cmdline-completion|)
193 CTRL-L command-line completion (see |cmdline-completion|)
195 *c_CTRL-_*
196 CTRL-_ a - switch between Hebrew and English keyboard mode, which is
197 private to the command-line and not related to hkmap.
198 This is useful when Hebrew text entry is required in the
199 command-line, searches, abbreviations, etc. Applies only if
200 Vim is compiled with the |+rightleft| feature and the
201 'allowrevins' option is set.
202 See |rightleft.txt|.
204 b - switch between Farsi and English keyboard mode, which is
205 private to the command-line and not related to fkmap. In
206 Farsi keyboard mode the characters are inserted in reverse
207 insert manner. This is useful when Farsi text entry is
208 required in the command-line, searches, abbreviations, etc.
209 Applies only if Vim is compiled with the |+farsi| feature.
210 See |farsi.txt|.
212 The <Up> and <Down> keys take the current command-line as a search string.
213 The beginning of the next/previous command-lines are compared with this
214 string. The first line that matches is the new command-line. When typing
215 these two keys repeatedly, the same string is used again. For example, this
216 can be used to find the previous substitute command: Type ":s" and then <Up>.
217 The same could be done by typing <S-Up> a number of times until the desired
218 command-line is shown. (Note: the shifted arrow keys do not work on all
219 terminals)
221 *his* *:history*
222 :his[tory] Print the history of last entered commands. {not in Vi}
224 :his[tory] [{name}] [{first}][, [{last}]]
225 List the contents of history {name} which can be:
226 c[md] or : command-line history
227 s[earch] or / search string history
228 e[xpr] or = expression register history
229 i[nput] or @ input line history
230 a[ll] all of the above
231 {not in Vi}
233 If the numbers {first} and/or {last} are given, the respective
234 range of entries from a history is listed. These numbers can
235 be specified in the following form:
236 *:history-indexing*
237 A positive number represents the absolute index of an entry
238 as it is given in the first column of a :history listing.
239 This number remains fixed even if other entries are deleted.
241 A negative number means the relative position of an entry,
242 counted from the newest entry (which has index -1) backwards.
244 Examples:
245 List entries 6 to 12 from the search history:
246 > :history / 6,12
248 List the recent five entries from all histories:
249 > :history all -5,
251 ==============================================================================
252 2. Command-line completion *cmdline-completion*
254 When editing the command-line, a few commands can be used to complete the
255 word before the cursor. This is available for:
257 - Command names: At the start of the command-line.
258 - Tags: Only after the ":tag" command.
259 - File names: Only after a command that accepts a file name or a setting for
260 an option that can be set to a file name. This is called file name
261 completion.
262 - Options: Only after the ":set" command.
263 - Mappings: Only after a ":map" or similar command.
264 - Variable and function names: Only after a ":if", ":call" or similar command.
266 When Vim was compiled with the |+cmdline_compl| feature disabled, only file
267 names, directories and help items can be completed.
269 These are the commands that can be used:
271 *c_CTRL-D*
272 CTRL-D List names that match the pattern in front of the cursor.
273 When showing file names, directories are highlighted (see
274 'highlight' option). Names where 'suffixes' matches are moved
275 to the end.
276 *c_CTRL-I* *c_wildchar* *c_<Tab>*
277 'wildchar' option
278 A match is done on the pattern in front of the cursor. The
279 match (if there are several, the first match) is inserted
280 in place of the pattern. (Note: does not work inside a
281 macro, because <Tab> or <Esc> are mostly used as 'wildchar',
282 and these have a special meaning in some macros.) When typed
283 again and there were multiple matches, the next
284 match is inserted. After the last match, the first is used
285 again (wrap around).
286 The behavior can be changed with the 'wildmode' option.
287 *c_CTRL-N*
288 CTRL-N After using 'wildchar' which got multiple matches, go to next
289 match. Otherwise recall more recent command-line from history.
290 <S-Tab> *c_CTRL-P* *c_<S-Tab>*
291 CTRL-P After using 'wildchar' which got multiple matches, go to
292 previous match. Otherwise recall older command-line from
293 history. <S-Tab> only works with the GUI, on the Amiga and
294 with MS-DOS.
295 *c_CTRL-A*
296 CTRL-A All names that match the pattern in front of the cursor are
297 inserted.
298 *c_CTRL-L*
299 CTRL-L A match is done on the pattern in front of the cursor. If
300 there is one match, it is inserted in place of the pattern.
301 If there are multiple matches the longest common part is
302 inserted in place of the pattern. If the result is shorter
303 than the pattern, no completion is done.
305 The 'wildchar' option defaults to <Tab> (CTRL-E when in Vi compatible mode; in
306 a previous version <Esc> was used). In the pattern standard wildcards '*' and
307 '?' are accepted. '*' matches any string, '?' matches exactly one character.
309 If you like tcsh's autolist completion, you can use this mapping:
310 :cnoremap X <C-L><C-D>
311 (Where X is the command key to use, <C-L> is CTRL-L and <C-D> is CTRL-D)
312 This will find the longest match and then list all matching files.
314 If you like tcsh's autolist completion, you can use the 'wildmode' option to
315 emulate it. For example, this mimics autolist=ambiguous:
316 :set wildmode=longest,list
317 This will find the longest match with the first 'wildchar', then list all
318 matching files with the next.
320 *suffixes*
321 For file name completion you can use the 'suffixes' option to set a priority
322 between files with almost the same name. If there are multiple matches,
323 those files with an extension that is in the 'suffixes' option are ignored.
324 The default is ".bak,~,.o,.h,.info,.swp", which means that files ending in
325 ".bak", "~", ".o", ".h", ".info" and ".swp" are sometimes ignored. It is
326 impossible to ignore suffixes with two dots. Examples:
328 pattern: files: match: ~
329 test* test.c test.h test.o test.c
330 test* test.h test.o test.h and test.o
331 test* test.i test.h test.c test.i and test.c
333 If there is more than one matching file (after ignoring the ones matching
334 the 'suffixes' option) the first file name is inserted. You can see that
335 there is only one match when you type 'wildchar' twice and the completed
336 match stays the same. You can get to the other matches by entering
337 'wildchar', CTRL-N or CTRL-P. All files are included, also the ones with
338 extensions matching the 'suffixes' option.
340 The old value of an option can be obtained by hitting 'wildchar' just after
341 the '='. For example, typing 'wildchar' after ":set dir=" will insert the
342 current value of 'dir'. This overrules file name completion for the options
343 that take a file name.
345 If you would like using <S-Tab> for CTRL-P in an xterm, put this command in
346 your .cshrc:
347 > xmodmap -e "keysym Tab = Tab Find"
348 And this in your .vimrc:
349 > cmap <Esc>[1~ <C-P> (<C-P> is CTRL-P)
351 ==============================================================================
352 3. Ex command-lines *cmdline-lines*
354 The Ex commands have a few specialties:
356 *:quote*
357 '"' at the start of a line causes the whole line to be ignored. '"'
358 after a command causes the rest of the line to be ignored. This can be used
359 to add comments. Example:
360 > :set ai "set 'autoindent' option
361 It is not possible to add a comment to a shell command ":!cmd" or to the
362 ":map" command and friends, because they see the '"' as part of their
363 argument.
365 *:bar* *:\bar*
366 '|' can be used to separate commands, so you can give multiple commands in one
367 line. If you want to use '|' in an argument, precede it with '\'.
369 These commands see the '|' as their argument, and can therefore not be
370 followed by another command:
371 :autocmd
372 :global
373 :normal
374 :perl
375 :perldo
376 :pyfile
377 :python
378 :read !
379 :tcl
380 :tcldo
381 :tclfile
382 :vglobal
383 :write !
384 :[range]!
386 Note that this is confusing (inherited from Vi): With ":g" the '|' is included
387 in the command, with ":s" it is not.
389 To be able to use another command anyway, use the ":execute" command.
390 Example (append the output of "ls" and jump to the first line):
391 > :execute 'r !ls' | '[
393 There is one exception: When the 'b' flag is present in 'cpoptions', with the
394 ":map" and ":abbr" commands and friends CTRL-V needs to be used instead of
395 '\'. You can also use "<Bar>" instead. See also |map_bar|.
397 Examples:
398 > :!ls | wc view the output of two commands
399 > :r !ls | wc insert the same output in the text
400 > :%g/foo/p|> moves all matching lines one shiftwidth
401 > :%s/foo/bar/|> moves one line one shiftwidth
402 > :map q 10^V| map "q" to "10|"
403 > :map q 10\| map \ l map "q" to "10\" and map "\" to "l"
404 > (when 'b' is present in 'cpoptions')
406 You can also use <NL> to separate commands in the same way as with '|'. To
407 insert a <NL> use CTRL-V CTRL-J. "^@" will be shown. Using '|' is the
408 preferred method. But for external commands a <NL> must be used, because a
409 '|' is included in the external command. To avoid the special meaning of <NL>
410 it must be preceded with a backslash. Example:
411 > :r !date<NL>-join
412 This reads the current date into the file and joins it with the previous line.
414 Note that when the command before the '|' generates an error, the following
415 commands will not be executed.
418 Because of Vi compatibility the following strange commands are supported:
419 > :| print current line (like ":p")
420 > :3| print line 3 (like ":3p")
421 > :3 goto line 3
423 A colon is allowed between the range and the command name. It is ignored
424 (this is Vi compatible). For example:
425 > :1,$:s/pat/string
427 When the character '%' or '#' is used where a file name is expected, they are
428 expanded to the current and alternate file name (see the chapter "editing
429 files" |:_%| |:_#|).
431 Embedded spaces in file names are allowed on the Amiga if one file name is
432 expected as argument. Trailing spaces will be ignored, unless escaped with a
433 backslash or CTRL-V. Note that the ":next" command uses spaces to separate
434 file names. Escape the spaces to include them in a file name. Example:
435 > :next foo\ bar goes\ to school\
436 starts editing the three files "foo bar", "goes to" and "school ".
438 When you want to use the special characters '"' or '|' in a command, or want
439 to use '%' or '#' in a file name, precede them with a backslash. The
440 backslash is not required in a range and in the ":substitute" command.
442 *:_!*
443 The '!' (bang) character after an Ex command makes the command behave in a
444 different way. The '!' should be placed immediately after the command, without
445 any blanks in between. If you insert blanks the '!' will be seen as an
446 argument for the command, which has a different meaning. For example:
447 :w! name write the current buffer to file "name", overwriting
448 any existing file
449 :w !name send the current buffer as standard input to command
450 "name"
452 ==============================================================================
453 4. Ex command-line ranges *cmdline-ranges* *[range]*
455 Some Ex commands accept a line range in front of them. This is noted as
456 [range]. It consists of one or more line specifiers, separated with ',' or
457 ';'.
459 *:,* *:;*
460 When separated with ';' the cursor position will be set to that line
461 before interpreting the next line specifier. This doesn't happen for ','.
462 Examples:
463 > 4,/this line/ from line 4 till match with "this line" after
464 > the cursor line.
465 > 5;/that line/ from line 5 till match with "that line" after
466 > line 5.
468 The default line specifier for most commands is the cursor position, but the
469 commands ":write" and ":global" have the whole file (1,$) as default.
471 If more line specifiers are given than required for the command, the first
472 one(s) will be ignored.
474 Line numbers may be specified with: *:range*
475 {number} an absolute line number
476 . the current line *:.*
477 $ the last line in the file *:$*
478 % equal to 1,$ (the entire file) *:%*
479 't position of mark t (lower case) *:'*
480 /{pattern}[/] the next line where {pattern} matches *:/*
481 ?{pattern}[?] the previous line where {pattern} matches *:?*
482 \/ the next line where the previously used search
483 pattern matches
484 \? the previous line where the previously used search
485 pattern matches
486 \& the next line where the previously used substitute
487 pattern matches
489 Each may be followed (several times) by '+' or '-' and an optional number.
490 This number is added or subtracted from the preceding line number. If the
491 number is omitted, 1 is used.
493 The "/" and "?" after {pattern} are required to separate the pattern from
494 anything that follows.
496 The "/" and "?" may be preceded with another address. The search starts from
497 there. The difference from using ';' is that the cursor isn't moved.
498 Examples:
499 > /pat1//pat2/ Find line containing "pat2" after line containing
500 > "pat1", without moving the cursor.
501 > 7;/pat2/ Find line containing "pat2", after line 7, leaving
502 > the cursor in line 7.
504 The {number} must be between 0 and the number of lines in the file. When
505 using a 0 (zero) this is interpreted as a 1 by most commands. Commands that
506 use it as a count do use it as a zero (|:tag|, |:pop|, etc). Some commands
507 interpret the zero as "before the first line" (|:read|, search pattern, etc).
509 Examples:
510 > .+3 three lines below the cursor
511 > /that/+1 the line below the next line containing "that"
512 > .,$ from current line until end of file
513 > 0;/that the first line containing "that", also matches in the
514 > first line.
515 > 1;/that the first line after line 1 containing "that"
517 Some commands allow for a count after the command. This count is used as the
518 number of lines to be used, starting with the line given in the last line
519 specifier (the default is the cursor line). The commands that accept a count
520 are the ones that use a range but do not have a file name argument (because
521 a file name can also be a number).
523 Examples:
524 > :s/x/X/g 5 substitute 'x' by 'X' in the current line and four
525 > following lines
526 > :23d 4 delete lines 23, 24, 25 and 26
528 A range should have the lower line number first. If this is not the case, Vim
529 will ask you if it should swap the line numbers. This is not done within the
530 global command ":g".
532 *N:*
533 When giving a count before entering ":", this is translated into:
534 :.,.+(count - 1)
535 In words: The 'count' lines at and after the cursor. Example: To delete
536 three lines:
537 > 3:d<CR> is translated into: .,.+2d<CR>
539 *v_:*
540 {Visual}: Starts a command-line with the Visual selected lines as a
541 range. The code ":'<,'>" is used for this range, which makes
542 it possible to select a similar line from the command-line
543 history for repeating a command on different Visually selected
544 lines.
546 ==============================================================================
547 5. Ex special characters *cmdline-special*
549 In Ex commands, at places where a file name can be used, the following
550 characters have a special meaning. These can also be used in the expression
551 function expand() |expand()|.
552 % is replaced with the current file name *:_%*
553 # is replaced with the alternate file name *:_#*
554 #n (where n is a number) is replaced with the file name of
555 buffer n. "#0" is the same as "#"
556 Note that these give the file name as it was typed. If an absolute path is
557 needed (when using the file name from a different directory), you need to add
558 ":p". See |filename-modifiers|.
560 To avoid the special meaning of '%' and '#' insert a backslash before it.
561 Detail: The special meaning is always escaped when there is a backslash before
562 it, no matter how many backslashes.
563 you type: result ~
564 # alternate.file
565 \# #
566 \\# \#
568 *:<cword>* *:<cWORD>* *:<cfile>* *<cfile>*
569 *:<sfile>* *<sfile>* *:<afile>* *<afile>*
570 *:<abuf>* *<abuf>* *:<amatch>* *<amatch>*
571 Note: these are typed literally, they are not special keys!
572 <cword> is replaced with the word under the cursor (like |star|)
573 <cWORD> is replaced with the WORD under the cursor (see |WORD|)
574 <cfile> is replaced with the path name under the cursor
575 <afile> when executing autocommands, is replaced with the file name
576 for a file read or write
577 <abuf> when executing autocommands, is replaced with the currently
578 effective buffer number (for ":r file" it is the current
579 buffer, the file being read is not in a buffer).
580 <amatch> when executing autocommands, is replaced with the match for
581 which this autocommand was executed. It differs form
582 <afile> only when the file name isn't used to match with
583 (for FileType and Syntax events).
584 <sfile> when executing a ":source" command, is replaced with the
585 file name of the sourced file;
586 when executing a function, is replaced with
587 "function {function-name}"; function call nesting is
588 indicated like this:
589 "function {function-name1}->{function-name2}". Note that
590 filename-modifiers are useless when <sfile> is used inside
591 a function.
593 *filename-modifiers*
594 *:_%:* *::p* *::.* *::~* *::h* *::t* *::r* *::e* *::s* *::gs*
595 The file name modifiers can be used after "%", "#", "#n", "<cfile>", "<sfile>",
596 "<afile>" or "<abuf>". They are also used with the |fnamemodify()| function.
597 These are not available when Vim has been compiled without the |+modify_fname|
598 feature.
599 These modifiers can be given, in this order:
600 :p Make file name a full path. Must be the first modifier.
601 :~ Reduce file name to be relative to the home directory, if
602 possible. File name is unmodified if it is not below the home
603 directory.
604 :. Reduce file name to be relative to current directory, if
605 possible. File name is unmodified if it is not below the
606 current directory.
607 For maximum shortness, use ":~:.".
608 :h Head of the file name (the last component and any separators
609 removed). Cannot be used with :e, :r or :t.
610 Can be repeated to remove several components at the end.
611 When the file name is an absolute path (starts with "/" for
612 Unix; "x:\" for MS-DOS, WIN32, OS/2; "drive:" for Amiga), that
613 part is not removed. When there is no head (path is relative
614 to current directory) the result is empty.
615 :t Tail of the file name (last component of the name). Must
616 precede any :r or :e.
617 :r Root of the file name (the last extension removed). When
618 there is only an extension (file name that starts with '.',
619 e.g., ".vimrc"), it is not removed. Can be repeated to remove
620 several extensions (last one first).
621 :e Extension of the file name. Only makes sense when used alone.
622 When there is no extension the result is empty.
623 When there is only an extension (file name that starts with
624 '.'), the result is empty. Can be repeated to include more
625 extensions. If there are not enough extensions (but at least
626 one) as much as possible are included.
627 :s?pat?sub?
628 Substitute the first occurrence of "pat" with "sub". This
629 works like the |:s| command. "pat" is a regular expression.
630 Any character can be used for '?', but it must not occur in
631 "pat" or "sub".
632 After this, the previous modifiers can be used again. For
633 example ":p", to make a full path after the substitution.
634 :gs?pat?sub?
635 Substitute all occurrences of "path" with "sub". Otherwise
636 this works like ":s".
638 Examples, when the file name is "src/version.c", current dir "/home/mool/vim":
639 > :p /home/mool/vim/src/version.c
640 > :p:. src/version.c
641 > :p:~ ~/vim/src/version.c
642 > :h src
643 > :p:h /home/mool/vim/src
644 > :p:h:h /home/mool/vim
645 > :t version.c
646 > :p:t version.c
647 > :r src/version
648 > :p:r /home/mool/vim/src/version
649 > :t:r version
650 > :e c
651 > :s?version?main? src/main.c
652 > :s?version?main?:p /home/mool/vim/src/main.c
653 > :p:gs?/?\\? \home\mool\vim\src\version.c
655 Examples, when the file name is "src/version.c.gz":
656 > :p /home/mool/vim/src/version.c.gz
657 > :e gz
658 > :e:e c.gz
659 > :e:e:e c.gz
660 > :e:e:r c
661 > :r src/version.c
662 > :r:e c
663 > :r:r src/version
664 > :r:r:r src/version
666 *extension-removal* *:_%<*
667 If a "<" is appended to "%", "#", "#n" or "CTRL-V p" the extension of the file
668 name is removed (everything after and including the last '.' in the file
669 name). This is included for backwards compatibility with version 3.0, the
670 ":r" form is preferred. Examples:
672 > % current file name
673 > %< current file name without extension
674 > # alternate file name for current window
675 > #< idem, without extension
676 > #31 alternate file number 31
677 > #31< idem, without extension
678 > <cword> word under the cursor
679 > <cWORD> WORD under the cursor (see |WORD|)
680 > <cfile> path name under the cursor
681 > <cfile>< idem, without extension
683 Note: Where a file name is expected wildcards expansion is done. On Unix the
684 shell is used for this. Backticks also work, like in
685 > :n `echo *.c`
686 (backtick expansion is not possible in |restricted-mode|)
687 But expansion is only done if there are any wildcards before expanding the
688 '%', '#', etc.. This avoids expanding wildcards inside a file name. If you
689 want to expand the result of <cfile>, add a wildcard character to it.
690 Examples: (alternate file name is "?readme?")
691 command expands to ~
692 :e # :e ?readme?
693 :e `ls #` :e {files matching "?readme?"}
694 :e #.* :e {files matching "?readme?.*"}
695 :cd <cfile> :cd {file name under cursor}
696 :cd <cfile>* :cd {file name under cursor plus "*" and then expanded}
698 *filename-backslash*
699 For filesystems that use a backslash as directory separator (MS-DOS, Windows,
700 OS/2), it's a bit difficult to recognize a backslash that is used to escape
701 the special meaning of the next character. The general rule is: If the
702 backslash is followed by a normal file name character, it does not have a
703 special meaning. Therefore "\file\foo" is a valid file name, you don't have
704 to type the backslash twice.
706 And exception is the '$' sign. It is a valid character in a file name. But
707 to avoid a file name like "$home" to be interpreted as an environment variable,
708 it needs to be preceded by a backslash. Therefore you need to use "/\$home"
709 for the file "$home" in the root directory. A few examples:
711 FILE NAME INTERPRETED AS ~
712 $home expanded to value of environment var $home
713 \$home file "$home" in current directory
714 /\$home file "$home" in root directory
715 \\$home file "\\", followed by expanded $home
717 vim:tw=78:ts=8:sw=8: