blob: fd18e6720e62ad1fdc2f012af8d5b6d6583e43f3 [file] [log] [blame]
Bram Moolenaar066b6222008-01-04 14:17:47 +00001*cmdline.txt* For Vim version 7.1. Last change: 2008 Jan 04
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7 *Cmdline-mode* *Command-line-mode*
8Command-line mode *Cmdline* *Command-line* *mode-cmdline* *:*
9
10Command-line mode is used to enter Ex commands (":"), search patterns
11("/" and "?"), and filter commands ("!").
12
13Basic command line editing is explained in chapter 20 of the user manual
14|usr_20.txt|.
15
161. Command-line editing |cmdline-editing|
172. Command-line completion |cmdline-completion|
183. Ex command-lines |cmdline-lines|
194. Ex command-line ranges |cmdline-ranges|
Bram Moolenaardf177f62005-02-22 08:39:57 +0000205. Ex command-line flags |ex-flags|
216. Ex special characters |cmdline-special|
227. Command-line window |cmdline-window|
Bram Moolenaar071d4272004-06-13 20:20:40 +000023
24==============================================================================
251. Command-line editing *cmdline-editing*
26
27Normally characters are inserted in front of the cursor position. You can
28move around in the command-line with the left and right cursor keys. With the
29<Insert> key, you can toggle between inserting and overstriking characters.
30{Vi: can only alter the last character in the line}
31
32Note that if your keyboard does not have working cursor keys or any of the
33other special keys, you can use ":cnoremap" to define another key for them.
34For example, to define tcsh style editing keys: *tcsh-style* >
35 :cnoremap <C-A> <Home>
36 :cnoremap <C-F> <Right>
37 :cnoremap <C-B> <Left>
38 :cnoremap <Esc>b <S-Left>
39 :cnoremap <Esc>f <S-Right>
40(<> notation |<>|; type all this literally)
41
42 *cmdline-too-long*
43When the command line is getting longer than what fits on the screen, only the
44part that fits will be shown. The cursor can only move in this visible part,
45thus you cannot edit beyond that.
46
47 *cmdline-history* *history*
48The command-lines that you enter are remembered in a history table. You can
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +000049recall them with the up and down cursor keys. There are actually five
Bram Moolenaar071d4272004-06-13 20:20:40 +000050history tables:
51- one for ':' commands
52- one for search strings
53- one for expressions
54- one for input lines, typed for the |input()| function.
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +000055- one for debug mode commands
Bram Moolenaar071d4272004-06-13 20:20:40 +000056These are completely separate. Each history can only be accessed when
57entering the same type of line.
58Use the 'history' option to set the number of lines that are remembered
59(default: 20).
60Notes:
61- When you enter a command-line that is exactly the same as an older one, the
62 old one is removed (to avoid repeated commands moving older commands out of
63 the history).
64- Only commands that are typed are remembered. Ones that completely come from
65 mappings are not put in the history
66- All searches are put in the search history, including the ones that come
67 from commands like "*" and "#". But for a mapping, only the last search is
68 remembered (to avoid that long mappings trash the history).
69{Vi: no history}
70{not available when compiled without the |+cmdline_hist| feature}
71
72There is an automatic completion of names on the command-line; see
73|cmdline-completion|.
74
75 *c_CTRL-V*
76CTRL-V Insert next non-digit literally. Up to three digits form the
77 decimal value of a single byte. The non-digit and the three
78 digits are not considered for mapping. This works the same
79 way as in Insert mode (see above, |i_CTRL-V|).
80 Note: Under Windows CTRL-V is often mapped to paste text.
81 Use CTRL-Q instead then.
82 *c_CTRL-Q*
83CTRL-Q Same as CTRL-V. But with some terminals it is used for
84 control flow, it doesn't work then.
85
86 *c_<Left>*
87<Left> cursor left
88 *c_<Right>*
89<Right> cursor right
90 *c_<S-Left>*
91<S-Left> or <C-Left> *c_<C-Left>*
92 cursor one WORD left
93 *c_<S-Right>*
94<S-Right> or <C-Right> *c_<C-Right>*
95 cursor one WORD right
96CTRL-B or <Home> *c_CTRL-B* *c_<Home>*
97 cursor to beginning of command-line
98CTRL-E or <End> *c_CTRL-E* *c_<End>*
99 cursor to end of command-line
100
101 *c_<LeftMouse>*
102<LeftMouse> cursor to position of mouse click.
103
104CTRL-H *c_<BS>* *c_CTRL-H*
105<BS> delete the character in front of the cursor (see |:fixdel| if
106 your <BS> key does not do what you want).
107 *c_<Del>*
108<Del> delete the character under the cursor (at end of line:
109 character before the cursor) (see |:fixdel| if your <Del>
110 key does not do what you want).
111 *c_CTRL-W*
112CTRL-W delete the word before the cursor
113 *c_CTRL-U*
114CTRL-U remove all characters between the cursor position and
115 the beginning of the line. Previous versions of vim
116 deleted all characters on the line. If that is the
117 preferred behavior, add the following to your .vimrc: >
118 :cnoremap <C-U> <C-E><C-U>
119<
120 Note: if the command-line becomes empty with one of the
121 delete commands, Command-line mode is quit.
122 *c_<Insert>*
123<Insert> Toggle between insert and overstrike. {not in Vi}
124
125{char1} <BS> {char2} or *c_digraph*
126CTRL-K {char1} {char2} *c_CTRL-K*
127 enter digraph (see |digraphs|). When {char1} is a special
128 key, the code for that key is inserted in <> form. {not in Vi}
129
130CTRL-R {0-9a-z"%#:-=.} *c_CTRL-R* *c_<C-R>*
131 Insert the contents of a numbered or named register. Between
132 typing CTRL-R and the second character '"' will be displayed
133 to indicate that you are expected to enter the name of a
134 register.
135 The text is inserted as if you typed it, but mappings and
136 abbreviations are not used. Command-line completion through
137 'wildchar' is not triggered though. And characters that end
138 the command line are inserted literally (<Esc>, <CR>, <NL>,
139 <C-C>). A <BS> or CTRL-W could still end the command line
140 though, and remaining characters will then be interpreted in
141 another mode, which might not be what you intended.
142 Special registers:
143 '"' the unnamed register, containing the text of
144 the last delete or yank
145 '%' the current file name
146 '#' the alternate file name
147 '*' the clipboard contents (X11: primary selection)
148 '+' the clipboard contents
149 '/' the last search pattern
150 ':' the last command-line
151 '-' the last small (less than a line) delete
152 '.' the last inserted text
153 *c_CTRL-R_=*
154 '=' the expression register: you are prompted to
155 enter an expression (see |expression|)
Bram Moolenaar05a7bb32006-01-19 22:09:32 +0000156 (doesn't work at the expression prompt; some
157 things such as changing the buffer or current
158 window are not allowed to avoid side effects)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000159 See |registers| about registers. {not in Vi}
Bram Moolenaarfd371682005-01-14 21:42:54 +0000160 Implementation detail: When using the |expression| register
161 and invoking setcmdpos(), this sets the position before
162 inserting the resulting string. Use CTRL-R CTRL-R to set the
163 position afterwards.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000164
165CTRL-R CTRL-F *c_CTRL-R_CTRL-F* *c_<C-R>_<C-F>*
166CTRL-R CTRL-P *c_CTRL-R_CTRL-P* *c_<C-R>_<C-P>*
167CTRL-R CTRL-W *c_CTRL-R_CTRL-W* *c_<C-R>_<C-W>*
168CTRL-R CTRL-A *c_CTRL-R_CTRL-A* *c_<C-R>_<C-A>*
169 Insert the object under the cursor:
170 CTRL-F the Filename under the cursor
171 CTRL-P the Filename under the cursor, expanded with
172 'path' as in |gf|
173 CTRL-W the Word under the cursor
174 CTRL-A the WORD under the cursor; see |WORD|
Bram Moolenaard3667a22006-03-16 21:35:52 +0000175
176 When 'incsearch' is set the cursor position at the end of the
177 currently displayed match is used. With CTRL-W the part of
178 the word that was already typed is not inserted again.
179
Bram Moolenaar071d4272004-06-13 20:20:40 +0000180 {not in Vi}
181 CTRL-F and CTRL-P: {only when +file_in_path feature is
182 included}
183
184 *c_CTRL-R_CTRL-R* *c_<C-R>_<C-R>*
185 *c_CTRL-R_CTRL-O* *c_<C-R>_<C-O>*
186CTRL-R CTRL-R {0-9a-z"%#:-=. CTRL-F CTRL-P CTRL-W CTRL-A}
187CTRL-R CTRL-O {0-9a-z"%#:-=. CTRL-F CTRL-P CTRL-W CTRL-A}
188 Insert register or object under the cursor. Works like
189 |c_CTRL-R| but inserts the text literally. For example, if
190 register a contains "xy^Hz" (where ^H is a backspace),
191 "CTRL-R a" will insert "xz" while "CTRL-R CTRL-R a" will
192 insert "xy^Hz".
193
194CTRL-\ e {expr} *c_CTRL-\_e*
195 Evaluate {expr} and replace the whole command line with the
196 result. You will be prompted for the expression, type <Enter>
197 to finish it. It's most useful in mappings though. See
198 |expression|.
199 See |c_CTRL-R_=| for inserting the result of an expression.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +0000200 Useful functions are |getcmdtype()|, |getcmdline()| and
201 |getcmdpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000202 The cursor position is unchanged, except when the cursor was
203 at the end of the line, then it stays at the end.
204 |setcmdpos()| can be used to set the cursor position.
Bram Moolenaar4770d092006-01-12 23:22:24 +0000205 The |sandbox| is used for evaluating the expression to avoid
206 nasty side effects.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000207 Example: >
208 :cmap <F7> <C-\>eAppendSome()<CR>
209 :func AppendSome()
210 :let cmd = getcmdline() . " Some()"
211 :" place the cursor on the )
212 :call setcmdpos(strlen(cmd))
213 :return cmd
214 :endfunc
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +0000215< This doesn't work recursively, thus not when already editing
216 an expression.
217
Bram Moolenaar071d4272004-06-13 20:20:40 +0000218 *c_CTRL-Y*
219CTRL-Y When there is a modeless selection, copy the selection into
220 the clipboard. |modeless-selection|
221 If there is no selection CTRL-Y is inserted as a character.
222
223CTRL-J *c_CTRL-J* *c_<NL>* *c_<CR>*
224<CR> or <NL> start entered command
225 *c_<Esc>*
226<Esc> When typed and 'x' not present in 'cpoptions', quit
227 Command-line mode without executing. In macros or when 'x'
228 present in 'cpoptions', start entered command.
229 *c_CTRL-C*
230CTRL-C quit command-line without executing
231
232 *c_<Up>*
233<Up> recall older command-line from history, whose beginning
234 matches the current command-line (see below).
235 {not available when compiled without the |+cmdline_hist|
236 feature}
237 *c_<Down>*
238<Down> recall more recent command-line from history, whose beginning
239 matches the current command-line (see below).
240 {not available when compiled without the |+cmdline_hist|
241 feature}
242
243 *c_<S-Up>* *c_<PageUp>*
244<S-Up> or <PageUp>
245 recall older command-line from history
246 {not available when compiled without the |+cmdline_hist|
247 feature}
248 *c_<S-Down>* *c_<PageDown>*
249<S-Down> or <PageDown>
250 recall more recent command-line from history
251 {not available when compiled without the |+cmdline_hist|
252 feature}
253
254CTRL-D command-line completion (see |cmdline-completion|)
255'wildchar' option
256 command-line completion (see |cmdline-completion|)
257CTRL-N command-line completion (see |cmdline-completion|)
258CTRL-P command-line completion (see |cmdline-completion|)
259CTRL-A command-line completion (see |cmdline-completion|)
260CTRL-L command-line completion (see |cmdline-completion|)
261
262 *c_CTRL-_*
263CTRL-_ a - switch between Hebrew and English keyboard mode, which is
264 private to the command-line and not related to hkmap.
265 This is useful when Hebrew text entry is required in the
266 command-line, searches, abbreviations, etc. Applies only if
267 Vim is compiled with the |+rightleft| feature and the
268 'allowrevins' option is set.
269 See |rileft.txt|.
270
271 b - switch between Farsi and English keyboard mode, which is
272 private to the command-line and not related to fkmap. In
273 Farsi keyboard mode the characters are inserted in reverse
274 insert manner. This is useful when Farsi text entry is
275 required in the command-line, searches, abbreviations, etc.
276 Applies only if Vim is compiled with the |+farsi| feature.
277 See |farsi.txt|.
278
279 *c_CTRL-^*
280CTRL-^ Toggle the use of language |:lmap| mappings and/or Input
281 Method.
282 When typing a pattern for a search command and 'imsearch' is
283 not -1, VAL is the value of 'imsearch', otherwise VAL is the
284 value of 'iminsert'.
285 When language mappings are defined:
286 - If VAL is 1 (langmap mappings used) it becomes 0 (no langmap
287 mappings used).
288 - If VAL was not 1 it becomes 1, thus langmap mappings are
289 enabled.
290 When no language mappings are defined:
291 - If VAL is 2 (Input Method is used) it becomes 0 (no input
292 method used)
293 - If VAL has another value it becomes 2, thus the Input Method
294 is enabled.
295 These language mappings are normally used to type characters
296 that are different from what the keyboard produces. The
297 'keymap' option can be used to install a whole number of them.
298 When entering a command line, langmap mappings are switched
299 off, since you are expected to type a command. After
300 switching it on with CTRL-^, the new state is not used again
301 for the next command or Search pattern.
302 {not in Vi}
303
Bram Moolenaar9964e462007-05-05 17:54:07 +0000304 *c_CTRL-]*
305CTRL-] Trigger abbreviation, without inserting a character. {not in
306 Vi}
307
Bram Moolenaar071d4272004-06-13 20:20:40 +0000308For Emacs-style editing on the command-line see |emacs-keys|.
309
310The <Up> and <Down> keys take the current command-line as a search string.
311The beginning of the next/previous command-lines are compared with this
312string. The first line that matches is the new command-line. When typing
313these two keys repeatedly, the same string is used again. For example, this
314can be used to find the previous substitute command: Type ":s" and then <Up>.
315The same could be done by typing <S-Up> a number of times until the desired
316command-line is shown. (Note: the shifted arrow keys do not work on all
317terminals)
318
Bram Moolenaar066b6222008-01-04 14:17:47 +0000319 *:his* *:history*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000320:his[tory] Print the history of last entered commands.
321 {not in Vi}
322 {not available when compiled without the |+cmdline_hist|
323 feature}
324
325:his[tory] [{name}] [{first}][, [{last}]]
326 List the contents of history {name} which can be:
327 c[md] or : command-line history
328 s[earch] or / search string history
329 e[xpr] or = expression register history
330 i[nput] or @ input line history
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +0000331 d[ebug] or > debug command history
Bram Moolenaar071d4272004-06-13 20:20:40 +0000332 a[ll] all of the above
333 {not in Vi}
334
335 If the numbers {first} and/or {last} are given, the respective
336 range of entries from a history is listed. These numbers can
337 be specified in the following form:
338 *:history-indexing*
339 A positive number represents the absolute index of an entry
340 as it is given in the first column of a :history listing.
341 This number remains fixed even if other entries are deleted.
342
343 A negative number means the relative position of an entry,
344 counted from the newest entry (which has index -1) backwards.
345
346 Examples:
347 List entries 6 to 12 from the search history: >
348 :history / 6,12
349<
350 List the recent five entries from all histories: >
351 :history all -5,
352
353==============================================================================
3542. Command-line completion *cmdline-completion*
355
356When editing the command-line, a few commands can be used to complete the
357word before the cursor. This is available for:
358
359- Command names: At the start of the command-line.
360- Tags: Only after the ":tag" command.
361- File names: Only after a command that accepts a file name or a setting for
362 an option that can be set to a file name. This is called file name
363 completion.
Bram Moolenaara2031822006-03-07 22:29:51 +0000364- Shell command names: After ":!cmd", ":r !cmd" and ":w !cmd". $PATH is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000365- Options: Only after the ":set" command.
366- Mappings: Only after a ":map" or similar command.
367- Variable and function names: Only after a ":if", ":call" or similar command.
368
369When Vim was compiled with the |+cmdline_compl| feature disabled, only file
370names, directories and help items can be completed.
371
372These are the commands that can be used:
373
374 *c_CTRL-D*
375CTRL-D List names that match the pattern in front of the cursor.
376 When showing file names, directories are highlighted (see
377 'highlight' option). Names where 'suffixes' matches are moved
378 to the end.
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +0000379 The 'wildoptions' option can be set to "tagfile" to list the
380 file of matching tags.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000381 *c_CTRL-I* *c_wildchar* *c_<Tab>*
382'wildchar' option
383 A match is done on the pattern in front of the cursor. The
384 match (if there are several, the first match) is inserted
385 in place of the pattern. (Note: does not work inside a
386 macro, because <Tab> or <Esc> are mostly used as 'wildchar',
387 and these have a special meaning in some macros.) When typed
388 again and there were multiple matches, the next
389 match is inserted. After the last match, the first is used
390 again (wrap around).
391 The behavior can be changed with the 'wildmode' option.
392 *c_CTRL-N*
393CTRL-N After using 'wildchar' which got multiple matches, go to next
394 match. Otherwise recall more recent command-line from history.
395<S-Tab> *c_CTRL-P* *c_<S-Tab>*
396CTRL-P After using 'wildchar' which got multiple matches, go to
397 previous match. Otherwise recall older command-line from
398 history. <S-Tab> only works with the GUI, on the Amiga and
399 with MS-DOS.
400 *c_CTRL-A*
401CTRL-A All names that match the pattern in front of the cursor are
402 inserted.
403 *c_CTRL-L*
404CTRL-L A match is done on the pattern in front of the cursor. If
405 there is one match, it is inserted in place of the pattern.
406 If there are multiple matches the longest common part is
407 inserted in place of the pattern. If the result is shorter
408 than the pattern, no completion is done.
Bram Moolenaard3667a22006-03-16 21:35:52 +0000409 When 'incsearch' is set, entering a search pattern for "/" or
410 "?" and the current match is displayed then CTRL-L will add
411 one character from the end of the current match.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000412
413The 'wildchar' option defaults to <Tab> (CTRL-E when in Vi compatible mode; in
414a previous version <Esc> was used). In the pattern standard wildcards '*' and
415'?' are accepted. '*' matches any string, '?' matches exactly one character.
416
417If you like tcsh's autolist completion, you can use this mapping:
418 :cnoremap X <C-L><C-D>
419(Where X is the command key to use, <C-L> is CTRL-L and <C-D> is CTRL-D)
420This will find the longest match and then list all matching files.
421
422If you like tcsh's autolist completion, you can use the 'wildmode' option to
423emulate it. For example, this mimics autolist=ambiguous:
424 :set wildmode=longest,list
425This will find the longest match with the first 'wildchar', then list all
426matching files with the next.
427
428 *suffixes*
429For file name completion you can use the 'suffixes' option to set a priority
430between files with almost the same name. If there are multiple matches,
431those files with an extension that is in the 'suffixes' option are ignored.
432The default is ".bak,~,.o,.h,.info,.swp,.obj", which means that files ending
433in ".bak", "~", ".o", ".h", ".info", ".swp" and ".obj" are sometimes ignored.
434It is impossible to ignore suffixes with two dots. Examples:
435
436 pattern: files: match: ~
437 test* test.c test.h test.o test.c
438 test* test.h test.o test.h and test.o
439 test* test.i test.h test.c test.i and test.c
440
441If there is more than one matching file (after ignoring the ones matching
442the 'suffixes' option) the first file name is inserted. You can see that
443there is only one match when you type 'wildchar' twice and the completed
444match stays the same. You can get to the other matches by entering
445'wildchar', CTRL-N or CTRL-P. All files are included, also the ones with
446extensions matching the 'suffixes' option.
447
448To completely ignore files with some extension use 'wildignore'.
449
Bram Moolenaar066b6222008-01-04 14:17:47 +0000450To match only files that end at the end of the typed text append a "$". For
451example, to match only files that end in ".c": >
452 :e *.c$
453This will not match a file ending in ".cpp". Without the "$" it does match.
454
Bram Moolenaar071d4272004-06-13 20:20:40 +0000455The old value of an option can be obtained by hitting 'wildchar' just after
456the '='. For example, typing 'wildchar' after ":set dir=" will insert the
457current value of 'dir'. This overrules file name completion for the options
458that take a file name.
459
460If you would like using <S-Tab> for CTRL-P in an xterm, put this command in
461your .cshrc: >
462 xmodmap -e "keysym Tab = Tab Find"
463And this in your .vimrc: >
464 :cmap <Esc>[1~ <C-P>
465
466==============================================================================
4673. Ex command-lines *cmdline-lines*
468
469The Ex commands have a few specialties:
470
471 *:quote*
472'"' at the start of a line causes the whole line to be ignored. '"'
473after a command causes the rest of the line to be ignored. This can be used
474to add comments. Example: >
475 :set ai "set 'autoindent' option
476It is not possible to add a comment to a shell command ":!cmd" or to the
477":map" command and friends, because they see the '"' as part of their
478argument.
479
480 *:bar* *:\bar*
481'|' can be used to separate commands, so you can give multiple commands in one
482line. If you want to use '|' in an argument, precede it with '\'.
483
484These commands see the '|' as their argument, and can therefore not be
485followed by another command:
486 :argdo
487 :autocmd
488 :bufdo
489 :command
490 :cscope
491 :debug
492 :folddoopen
493 :folddoclosed
494 :function
495 :global
496 :help
497 :helpfind
Bram Moolenaar110bc6b2006-02-10 23:13:40 +0000498 :lcscope
Bram Moolenaar071d4272004-06-13 20:20:40 +0000499 :make
500 :normal
501 :perl
502 :perldo
503 :promptfind
504 :promptrepl
505 :pyfile
506 :python
507 :registers
508 :read !
509 :scscope
510 :tcl
511 :tcldo
512 :tclfile
513 :vglobal
514 :windo
515 :write !
516 :[range]!
517 a user defined command without the "-bar" argument |:command|
518
519Note that this is confusing (inherited from Vi): With ":g" the '|' is included
520in the command, with ":s" it is not.
521
522To be able to use another command anyway, use the ":execute" command.
523Example (append the output of "ls" and jump to the first line): >
524 :execute 'r !ls' | '[
525
526There is one exception: When the 'b' flag is present in 'cpoptions', with the
527":map" and ":abbr" commands and friends CTRL-V needs to be used instead of
528'\'. You can also use "<Bar>" instead. See also |map_bar|.
529
530Examples: >
531 :!ls | wc view the output of two commands
532 :r !ls | wc insert the same output in the text
533 :%g/foo/p|> moves all matching lines one shiftwidth
534 :%s/foo/bar/|> moves one line one shiftwidth
535 :map q 10^V| map "q" to "10|"
536 :map q 10\| map \ l map "q" to "10\" and map "\" to "l"
537 (when 'b' is present in 'cpoptions')
538
539You can also use <NL> to separate commands in the same way as with '|'. To
540insert a <NL> use CTRL-V CTRL-J. "^@" will be shown. Using '|' is the
541preferred method. But for external commands a <NL> must be used, because a
542'|' is included in the external command. To avoid the special meaning of <NL>
543it must be preceded with a backslash. Example: >
544 :r !date<NL>-join
545This reads the current date into the file and joins it with the previous line.
546
547Note that when the command before the '|' generates an error, the following
548commands will not be executed.
549
550
551Because of Vi compatibility the following strange commands are supported: >
552 :| print current line (like ":p")
553 :3| print line 3 (like ":3p")
554 :3 goto line 3
555
556A colon is allowed between the range and the command name. It is ignored
557(this is Vi compatible). For example: >
558 :1,$:s/pat/string
559
560When the character '%' or '#' is used where a file name is expected, they are
561expanded to the current and alternate file name (see the chapter "editing
562files" |:_%| |:_#|).
563
564Embedded spaces in file names are allowed on the Amiga if one file name is
565expected as argument. Trailing spaces will be ignored, unless escaped with a
566backslash or CTRL-V. Note that the ":next" command uses spaces to separate
567file names. Escape the spaces to include them in a file name. Example: >
568 :next foo\ bar goes\ to school\
569starts editing the three files "foo bar", "goes to" and "school ".
570
571When you want to use the special characters '"' or '|' in a command, or want
572to use '%' or '#' in a file name, precede them with a backslash. The
573backslash is not required in a range and in the ":substitute" command.
574
575 *:_!*
576The '!' (bang) character after an Ex command makes the command behave in a
577different way. The '!' should be placed immediately after the command, without
578any blanks in between. If you insert blanks the '!' will be seen as an
579argument for the command, which has a different meaning. For example:
580 :w! name write the current buffer to file "name", overwriting
581 any existing file
582 :w !name send the current buffer as standard input to command
583 "name"
584
585==============================================================================
Bram Moolenaara5792f52005-11-23 21:25:05 +00005864. Ex command-line ranges *cmdline-ranges* *[range]* *E16*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000587
588Some Ex commands accept a line range in front of them. This is noted as
589[range]. It consists of one or more line specifiers, separated with ',' or
590';'.
591
592The basics are explained in section |10.3| of the user manual.
593
594 *:,* *:;*
595When separated with ';' the cursor position will be set to that line
596before interpreting the next line specifier. This doesn't happen for ','.
597Examples: >
598 4,/this line/
599< from line 4 till match with "this line" after the cursor line. >
600 5;/that line/
601< from line 5 till match with "that line" after line 5.
602
603The default line specifier for most commands is the cursor position, but the
604commands ":write" and ":global" have the whole file (1,$) as default.
605
606If more line specifiers are given than required for the command, the first
607one(s) will be ignored.
608
609Line numbers may be specified with: *:range* *E14* *{address}*
610 {number} an absolute line number
611 . the current line *:.*
612 $ the last line in the file *:$*
613 % equal to 1,$ (the entire file) *:%*
614 't position of mark t (lowercase) *:'*
615 'T position of mark T (uppercase); when the mark is in
616 another file it cannot be used in a range
617 /{pattern}[/] the next line where {pattern} matches *:/*
618 ?{pattern}[?] the previous line where {pattern} matches *:?*
619 \/ the next line where the previously used search
620 pattern matches
621 \? the previous line where the previously used search
622 pattern matches
623 \& the next line where the previously used substitute
624 pattern matches
625
626Each may be followed (several times) by '+' or '-' and an optional number.
627This number is added or subtracted from the preceding line number. If the
628number is omitted, 1 is used.
629
630The "/" and "?" after {pattern} are required to separate the pattern from
631anything that follows.
632
633The "/" and "?" may be preceded with another address. The search starts from
634there. The difference from using ';' is that the cursor isn't moved.
635Examples: >
636 /pat1//pat2/ Find line containing "pat2" after line containing
637 "pat1", without moving the cursor.
638 7;/pat2/ Find line containing "pat2", after line 7, leaving
639 the cursor in line 7.
640
641The {number} must be between 0 and the number of lines in the file. When
642using a 0 (zero) this is interpreted as a 1 by most commands. Commands that
643use it as a count do use it as a zero (|:tag|, |:pop|, etc). Some commands
644interpret the zero as "before the first line" (|:read|, search pattern, etc).
645
646Examples: >
647 .+3 three lines below the cursor
648 /that/+1 the line below the next line containing "that"
649 .,$ from current line until end of file
650 0;/that the first line containing "that", also matches in the
651 first line.
652 1;/that the first line after line 1 containing "that"
653
654Some commands allow for a count after the command. This count is used as the
655number of lines to be used, starting with the line given in the last line
656specifier (the default is the cursor line). The commands that accept a count
657are the ones that use a range but do not have a file name argument (because
658a file name can also be a number).
659
660Examples: >
661 :s/x/X/g 5 substitute 'x' by 'X' in the current line and four
662 following lines
663 :23d 4 delete lines 23, 24, 25 and 26
664
665
666Folds and Range
667
668When folds are active the line numbers are rounded off to include the whole
669closed fold. See |fold-behavior|.
670
671
Bram Moolenaara5792f52005-11-23 21:25:05 +0000672Reverse Range *E493*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000673
674A range should have the lower line number first. If this is not the case, Vim
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000675will ask you if it should swap the line numbers.
Bram Moolenaara5792f52005-11-23 21:25:05 +0000676 Backwards range given, OK to swap ~
677This is not done within the global command ":g".
678
679You can use ":silent" before a command to avoid the question, the range will
680always be swapped then.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000681
682
683Count and Range *N:*
684
685When giving a count before entering ":", this is translated into:
686 :.,.+(count - 1)
687In words: The 'count' lines at and after the cursor. Example: To delete
688three lines: >
689 3:d<CR> is translated into: .,.+2d<CR>
690<
691
692Visual Mode and Range *v_:*
693
694{Visual}: Starts a command-line with the Visual selected lines as a
695 range. The code ":'<,'>" is used for this range, which makes
696 it possible to select a similar line from the command-line
697 history for repeating a command on different Visually selected
698 lines.
699
700==============================================================================
Bram Moolenaardf177f62005-02-22 08:39:57 +00007015. Ex command-line flags *ex-flags*
702
703These flags are supported by a selection of Ex commands. They print the line
704that the cursor ends up after executing the command:
705
706 l output like for |:list|
707 # add line number
708 p output like for |:print|
709
710The flags can be combined, thus "l#" uses both a line number and |:list| style
711output.
712
713==============================================================================
7146. Ex special characters *cmdline-special*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000715
Bram Moolenaar8fa04452005-12-23 22:13:51 +0000716Note: These are special characters in the executed command line. If you want
717to insert special things while typing you can use the CTRL-R command. For
718example, "%" stands for the current file name, while CTRL-R % inserts the
719current file name right away. See |c_CTRL-R|.
720
721
Bram Moolenaar071d4272004-06-13 20:20:40 +0000722In Ex commands, at places where a file name can be used, the following
723characters have a special meaning. These can also be used in the expression
724function expand() |expand()|.
725 % is replaced with the current file name *:_%*
726 # is replaced with the alternate file name *:_#*
727 #n (where n is a number) is replaced with the file name of
728 buffer n. "#0" is the same as "#"
729 ## is replaced with all names in the argument list *:_##*
730 concatenated, separated by spaces. Each space in a name
731 is preceded with a backslash.
732Note that these give the file name as it was typed. If an absolute path is
733needed (when using the file name from a different directory), you need to add
734":p". See |filename-modifiers|.
735Note that backslashes are inserted before spaces, so that the command will
736correctly interpret the file name. But this doesn't happen for shell
737commands. For those you probably have to use quotes: >
738 :!ls "%"
739 :r !spell "%"
740
741To avoid the special meaning of '%' and '#' insert a backslash before it.
742Detail: The special meaning is always escaped when there is a backslash before
743it, no matter how many backslashes.
744 you type: result ~
745 # alternate.file
746 \# #
747 \\# \#
748
749 *:<cword>* *:<cWORD>* *:<cfile>* *<cfile>*
750 *:<sfile>* *<sfile>* *:<afile>* *<afile>*
751 *:<abuf>* *<abuf>* *:<amatch>* *<amatch>*
752 *E495* *E496* *E497* *E498* *E499* *E500*
753Note: these are typed literally, they are not special keys!
754 <cword> is replaced with the word under the cursor (like |star|)
755 <cWORD> is replaced with the WORD under the cursor (see |WORD|)
756 <cfile> is replaced with the path name under the cursor (like what
757 |gf| uses)
758 <afile> when executing autocommands, is replaced with the file name
759 for a file read or write
760 <abuf> when executing autocommands, is replaced with the currently
Bram Moolenaara2031822006-03-07 22:29:51 +0000761 effective buffer number (for ":r file" and ":so file" it is
762 the current buffer, the file being read/sourced is not in a
763 buffer).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000764 <amatch> when executing autocommands, is replaced with the match for
Bram Moolenaar53180ce2005-07-05 21:48:14 +0000765 which this autocommand was executed. It differs from
Bram Moolenaar071d4272004-06-13 20:20:40 +0000766 <afile> only when the file name isn't used to match with
Bram Moolenaarb8a7b562006-02-01 21:47:16 +0000767 (for FileType, Syntax and SpellFileMissing events).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000768 <sfile> when executing a ":source" command, is replaced with the
769 file name of the sourced file;
770 when executing a function, is replaced with
771 "function {function-name}"; function call nesting is
772 indicated like this:
773 "function {function-name1}..{function-name2}". Note that
774 filename-modifiers are useless when <sfile> is used inside
775 a function.
776
777 *filename-modifiers*
778 *:_%:* *::8* *::p* *::.* *::~* *::h* *::t* *::r* *::e* *::s* *::gs*
779The file name modifiers can be used after "%", "#", "#n", "<cfile>", "<sfile>",
780"<afile>" or "<abuf>". They are also used with the |fnamemodify()| function.
781These are not available when Vim has been compiled without the |+modify_fname|
782feature.
783These modifiers can be given, in this order:
784 :p Make file name a full path. Must be the first modifier. Also
785 changes "~/" (and "~user/" for Unix and VMS) to the path for
786 the home directory. If the name is a directory a path
787 separator is added at the end. For a file name that does not
788 exist and does not have an absolute path the result is
789 unpredictable.
790 :8 Converts the path to 8.3 short format (currently only on
791 win32). Will act on as much of a path that is an existing
792 path.
793 :~ Reduce file name to be relative to the home directory, if
794 possible. File name is unmodified if it is not below the home
795 directory.
796 :. Reduce file name to be relative to current directory, if
797 possible. File name is unmodified if it is not below the
798 current directory.
799 For maximum shortness, use ":~:.".
800 :h Head of the file name (the last component and any separators
801 removed). Cannot be used with :e, :r or :t.
802 Can be repeated to remove several components at the end.
803 When the file name ends in a path separator, only the path
804 separator is removed. Thus ":p:h" on a directory name results
805 on the directory name itself (without trailing slash).
806 When the file name is an absolute path (starts with "/" for
807 Unix; "x:\" for MS-DOS, WIN32, OS/2; "drive:" for Amiga), that
808 part is not removed. When there is no head (path is relative
809 to current directory) the result is empty.
810 :t Tail of the file name (last component of the name). Must
811 precede any :r or :e.
812 :r Root of the file name (the last extension removed). When
813 there is only an extension (file name that starts with '.',
814 e.g., ".vimrc"), it is not removed. Can be repeated to remove
815 several extensions (last one first).
816 :e Extension of the file name. Only makes sense when used alone.
817 When there is no extension the result is empty.
818 When there is only an extension (file name that starts with
819 '.'), the result is empty. Can be repeated to include more
820 extensions. If there are not enough extensions (but at least
821 one) as much as possible are included.
822 :s?pat?sub?
823 Substitute the first occurrence of "pat" with "sub". This
824 works like the |:s| command. "pat" is a regular expression.
825 Any character can be used for '?', but it must not occur in
826 "pat" or "sub".
827 After this, the previous modifiers can be used again. For
828 example ":p", to make a full path after the substitution.
829 :gs?pat?sub?
830 Substitute all occurrences of "path" with "sub". Otherwise
831 this works like ":s".
832
833Examples, when the file name is "src/version.c", current dir
834"/home/mool/vim": >
835 :p /home/mool/vim/src/version.c
836 :p:. src/version.c
837 :p:~ ~/vim/src/version.c
838 :h src
839 :p:h /home/mool/vim/src
840 :p:h:h /home/mool/vim
841 :t version.c
842 :p:t version.c
843 :r src/version
844 :p:r /home/mool/vim/src/version
845 :t:r version
846 :e c
847 :s?version?main? src/main.c
848 :s?version?main?:p /home/mool/vim/src/main.c
849 :p:gs?/?\\? \home\mool\vim\src\version.c
850
851Examples, when the file name is "src/version.c.gz": >
852 :p /home/mool/vim/src/version.c.gz
853 :e gz
854 :e:e c.gz
855 :e:e:e c.gz
856 :e:e:r c
857 :r src/version.c
858 :r:e c
859 :r:r src/version
860 :r:r:r src/version
861<
862 *extension-removal* *:_%<*
863If a "<" is appended to "%", "#", "#n" or "CTRL-V p" the extension of the file
864name is removed (everything after and including the last '.' in the file
865name). This is included for backwards compatibility with version 3.0, the
866":r" form is preferred. Examples: >
867
868 % current file name
869 %< current file name without extension
870 # alternate file name for current window
871 #< idem, without extension
872 #31 alternate file number 31
873 #31< idem, without extension
874 <cword> word under the cursor
875 <cWORD> WORD under the cursor (see |WORD|)
876 <cfile> path name under the cursor
877 <cfile>< idem, without extension
878
879Note: Where a file name is expected wildcards expansion is done. On Unix the
880shell is used for this, unless it can be done internally (for speed).
881Backticks also work, like in >
882 :n `echo *.c`
883(backtick expansion is not possible in |restricted-mode|)
884But expansion is only done if there are any wildcards before expanding the
885'%', '#', etc.. This avoids expanding wildcards inside a file name. If you
886want to expand the result of <cfile>, add a wildcard character to it.
887Examples: (alternate file name is "?readme?")
888 command expands to ~
889 :e # :e ?readme?
890 :e `ls #` :e {files matching "?readme?"}
891 :e #.* :e {files matching "?readme?.*"}
892 :cd <cfile> :cd {file name under cursor}
893 :cd <cfile>* :cd {file name under cursor plus "*" and then expanded}
894
895When the expanded argument contains a "!" and it is used for a shell command
896(":!cmd", ":r !cmd" or ":w !cmd"), it is escaped with a backslash to avoid it
897being expanded into a previously used command. When the 'shell' option
898contains "sh", this is done twice, to avoid the shell trying to expand the
899"!".
900
901 *filename-backslash*
902For filesystems that use a backslash as directory separator (MS-DOS, Windows,
903OS/2), it's a bit difficult to recognize a backslash that is used to escape
904the special meaning of the next character. The general rule is: If the
905backslash is followed by a normal file name character, it does not have a
906special meaning. Therefore "\file\foo" is a valid file name, you don't have
907to type the backslash twice.
908
909An exception is the '$' sign. It is a valid character in a file name. But
910to avoid a file name like "$home" to be interpreted as an environment variable,
911it needs to be preceded by a backslash. Therefore you need to use "/\$home"
912for the file "$home" in the root directory. A few examples:
913
914 FILE NAME INTERPRETED AS ~
915 $home expanded to value of environment var $home
916 \$home file "$home" in current directory
917 /\$home file "$home" in root directory
918 \\$home file "\\", followed by expanded $home
919
920==============================================================================
9216. Command-line window *cmdline-window* *cmdwin*
922
923In the command-line window the command line can be edited just like editing
924text in any window. It is a special kind of window, because you cannot leave
925it in a normal way.
926{not available when compiled without the |+cmdline_hist| or |+vertsplit|
927feature}
928
929
930OPEN
931
932There are two ways to open the command-line window:
9331. From Command-line mode, use the key specified with the 'cedit' option.
934 The default is CTRL-F when 'compatible' is not set.
9352. From Normal mode, use the "q:", "q/" or "q?" command. *q:* *q/* *q?*
936 This starts editing an Ex command-line ("q:") or search string ("q/" or
937 "q?"). Note that this is not possible while recording is in progress (the
938 "q" stops recording then).
939
940When the window opens it is filled with the command-line history. The last
941line contains the command as typed so far. The left column will show a
942character that indicates the type of command-line being edited, see
943|cmdwin-char|.
944
945Vim will be in Normal mode when the editor is opened, except when 'insertmode'
946is set.
947
948The height of the window is specified with 'cmdwinheight' (or smaller if there
949is no room). The window is always full width and is positioned just above the
950command-line.
951
952
953EDIT
954
955You can now use commands to move around and edit the text in the window. Both
956in Normal mode and Insert mode.
957
958It is possible to use ":", "/" and other commands that use the command-line,
959but it's not possible to open another command-line window then. There is no
960nesting.
961 *E11*
962The command-line window is not a normal window. It is not possible to move to
963another window or edit another buffer. All commands that would do this are
964disabled in the command-line window. Of course it _is_ possible to execute
965any command that you entered in the command-line window.
966
967
968CLOSE *E199*
969
970There are several ways to leave the command-line window:
971
972<CR> Execute the command-line under the cursor. Works both in
973 Insert and in Normal mode.
974CTRL-C Continue in Command-line mode. The command-line under the
975 cursor is used as the command-line. Works both in Insert and
976 in Normal mode. ":close" also works. There is no redraw,
977 thus the window will remain visible.
978:quit Discard the command line and go back to Normal mode.
979 ":exit", ":xit" and CTRL-\ CTRL-N also work.
980:qall Quit Vim, unless there are changes in some buffer.
981:qall! Quit Vim, discarding changes to any buffer.
982
983Once the command-line window is closed the old window sizes are restored. The
984executed command applies to the window and buffer where the command-line was
985started from. This works as if the command-line window was not there, except
986that there will be an extra screen redraw.
987The buffer used for the command-line window is deleted. Any changes to lines
988other than the one that is executed with <CR> are lost.
989
Bram Moolenaar36fc5352006-03-04 21:49:37 +0000990If you would like to execute the command under the cursor and then have the
991command-line window open again, you may find this mapping useful: >
992
993 :map <F5> <CR>q:
994
Bram Moolenaar071d4272004-06-13 20:20:40 +0000995
996VARIOUS
997
998The command-line window cannot be used:
999- when there already is a command-line window (no nesting)
1000- for entering a encryption key or when using inputsecret()
1001- when Vim was not compiled with the +vertsplit feature
1002
1003Some options are set when the command-line window is opened:
1004'filetype' "vim", when editing an Ex command-line; this starts Vim syntax
1005 highlighting if it was enabled
1006'rightleft' off
1007'modifiable' on
1008'buftype' "nofile"
1009'swapfile' off
1010
1011It is allowed to write the buffer contents to a file. This is an easy way to
1012save the command-line history and read it back later.
1013
1014If the 'wildchar' option is set to <Tab>, and the command-line window is used
1015for an Ex command, then two mappings will be added to use <Tab> for completion
1016in the command-line window, like this: >
1017 :imap <buffer> <Tab> <C-X><C-V>
1018 :nmap <buffer> <Tab> a<C-X><C-V>
1019Note that hitting <Tab> in Normal mode will do completion on the next
1020character. That way it works at the end of the line.
1021If you don't want these mappings, disable them with: >
1022 au CmdwinEnter [:>] iunmap <Tab>
1023 au CmdwinEnter [:>] nunmap <Tab>
1024You could put these lines in your vimrc file.
1025
1026While in the command-line window you cannot use the mouse to put the cursor in
1027another window, or drag statuslines of other windows. You can drag the
1028statusline of the command-line window itself and the statusline above it.
1029Thus you can resize the command-line window, but not others.
1030
1031
1032AUTOCOMMANDS
1033
1034Two autocommand events are used: |CmdwinEnter| and |CmdwinLeave|. Since this
1035window is of a special type, the WinEnter, WinLeave, BufEnter and BufLeave
1036events are not triggered. You can use the Cmdwin events to do settings
1037specifically for the command-line window. Be careful not to cause side
1038effects!
1039Example: >
1040 :au CmdwinEnter : let b:cpt_save = &cpt | set cpt=v
1041 :au CmdwinLeave : let &cpt = b:cpt_save
1042This sets 'complete' to use command-line completion in Insert mode for CTRL-N.
1043Another example: >
1044 :au CmdwinEnter [/?] startinsert
1045This will make Vim start in Insert mode in the command-line window.
1046
1047 *cmdwin-char*
1048The character used for the pattern indicates the type of command-line:
1049 : normal Ex command
1050 > debug mode command |debug-mode|
1051 / forward search string
1052 ? backward search string
1053 = expression for "= |expr-register|
1054 @ string for |input()|
1055 - text for |:insert| or |:append|
1056
1057 vim:tw=78:ts=8:ft=help:norl: