codekingpro/portable-devtools
114k
1*cmdline.txt* For Vim version 9.2. Last change: 2026 Mar 172 3 4 VIM REFERENCE MANUAL by Bram Moolenaar5 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 patterns11("/" and "?"), and filter commands ("!").12 13Basic command line editing is explained in chapter 20 of the user manual14|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|205. Ex command-line flags |ex-flags|216. Ex special characters |cmdline-special|227. Command-line window |cmdline-window|238. Command-line autocompletion |cmdline-autocompletion|24 25==============================================================================261. Command-line editing *cmdline-editing*27 28Normally characters are inserted in front of the cursor position. You can29move around in the command-line with the left and right cursor keys. With the30<Insert> key, you can toggle between inserting and overstriking characters.31 32Note that if your keyboard does not have working cursor keys or any of the33other 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 the44part 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 can49recall them with the up and down cursor keys. There are actually five50history tables:51- one for ':' commands52- one for search strings53- one for expressions54- one for input lines, typed for the |input()| function.55- one for debug mode commands56These are completely separate. Each history can only be accessed when57entering the same type of line.58Use the 'history' option to set the number of lines that are remembered59(default: 50).60Notes:61- When you enter a command-line that is exactly the same as an older one, the62 old one is removed (to avoid repeated commands moving older commands out of63 the history).64- Only commands that are typed are remembered. A command executed completely65 from a mapping is not put in the history.66- All searches are put in the search history, including the ones that come67 from commands like "*" and "#". But for a mapping, only the last search is68 remembered (to avoid that long mappings trash the history).69{not available when compiled without the |+cmdline_hist| feature}70 71There is an automatic completion of names on the command-line; see72|cmdline-completion|.73 74 *c_CTRL-V*75CTRL-V Insert next non-digit literally. Up to three digits form the76 decimal value of a single byte. The non-digit and the three77 digits are not considered for mapping. This works the same78 way as in Insert mode (see above, |i_CTRL-V|).79 Note: Under MS-Windows CTRL-V is often mapped to paste text.80 Use CTRL-Q instead then.81 When |modifyOtherKeys| is enabled then special Escape sequence82 is converted back to what it was without |modifyOtherKeys|,83 unless the Shift key is also pressed.84 *c_CTRL-Q*85CTRL-Q Same as CTRL-V. But with some terminals it is used for86 control flow, it doesn't work then.87 88CTRL-SHIFT-V *c_CTRL-SHIFT-V* *c_CTRL-SHIFT-Q*89CTRL-SHIFT-Q Works just like CTRL-V, unless |modifyOtherKeys| is active,90 then it inserts the Escape sequence for a key with modifiers.91 In the GUI the |key-notation| is inserted without simplifying.92 Note: When CTRL-SHIFT-V is intercepted by your system (e.g.,93 to paste text) you can often use CTRL-SHIFT-Q instead.94 However, in some terminals (e.g. GNOME Terminal), CTRL-SHIFT-Q95 quits the terminal without confirmation.96 97 *c_<Left>* *c_Left*98<Left> cursor left. See 'wildmenu' for behavior during wildmenu99 completion mode.100 *c_<Right>* *c_Right*101<Right> cursor right. See 'wildmenu' for behavior during wildmenu102 completion mode.103 *c_<S-Left>*104<S-Left> or <C-Left> *c_<C-Left>*105 cursor one WORD left106 *c_<S-Right>*107<S-Right> or <C-Right> *c_<C-Right>*108 cursor one WORD right109CTRL-B or <Home> *c_CTRL-B* *c_<Home>* *c_Home*110 cursor to beginning of command-line111CTRL-E or <End> *c_CTRL-E* *c_<End>* *c_End*112 cursor to end of command-line. See 'wildmenu' for behavior113 during wildmenu completion mode.114 115 *c_<LeftMouse>*116<LeftMouse> Move the cursor to the position of the mouse click.117 118 *c_<MiddleMouse>*119<MiddleMouse> Paste the contents of the clipboard (for X11 the primary120 selection). This is similar to using CTRL-R *, but no CR121 characters are inserted between lines.122 123CTRL-H *c_<BS>* *c_CTRL-H* *c_BS*124<BS> Delete the character in front of the cursor (see |:fixdel| if125 your <BS> key does not do what you want).126 *c_<Del>* *c_Del*127<Del> Delete the character under the cursor (at end of line:128 character before the cursor) (see |:fixdel| if your <Del>129 key does not do what you want).130 *c_CTRL-W*131CTRL-W Delete the |word| before the cursor. This depends on the132 'iskeyword' option.133 *c_CTRL-U*134CTRL-U Remove all characters between the cursor position and135 the beginning of the line. Previous versions of vim136 deleted all characters on the line. If that is the137 preferred behavior, add the following to your .vimrc: >138 :cnoremap <C-U> <C-E><C-U>139<140 *c_<Insert>* *c_Insert*141<Insert> Toggle between insert and overstrike.142 143{char1} <BS> {char2} or *c_digraph*144CTRL-K {char1} {char2} *c_CTRL-K*145 enter digraph (see |digraphs|). When {char1} is a special146 key, the code for that key is inserted in <> form.147 148CTRL-R {register} *c_CTRL-R* *c_<C-R>*149 Insert the contents of a numbered or named register. Between150 typing CTRL-R and the second character '"' will be displayed151 to indicate that you are expected to enter the name of a152 register.153 The text is inserted as if you typed it, but mappings and154 abbreviations are not used. Command-line completion through155 'wildchar' is not triggered though. And characters that end156 the command line are inserted literally (<Esc>, <CR>, <NL>,157 <C-C>). A <BS> or CTRL-W could still end the command line158 though, and remaining characters will then be interpreted in159 another mode, which might not be what you intended.160 Special registers:161 '"' the unnamed register, containing the text of162 the last delete or yank163 '%' the current file name164 '#' the alternate file name165 '*' the clipboard contents (X11: primary166 selection)167 '+' the clipboard contents168 '/' the last search pattern169 ':' the last command-line170 '-' the last small (less than a line) delete171 '.' the last inserted text172 *c_CTRL-R_=*173 '=' the expression register: you are prompted to174 enter an expression (see |expression|)175 (doesn't work at the expression prompt; some176 things such as changing the buffer or current177 window are not allowed to avoid side effects)178 When the result is a |List| the items are used179 as lines. They can have line breaks inside180 too.181 When the result is a Float it's automatically182 converted to a String.183 Note that when you only want to move the184 cursor and not insert anything, you must make185 sure the expression evaluates to an empty186 string. E.g.: >187 <C-R><C-R>=setcmdpos(2)[-1]<CR>188< See |registers| about registers.189 Implementation detail: When using the |expression| register190 and invoking setcmdpos(), this sets the position before191 inserting the resulting string. Use CTRL-R CTRL-R to set the192 position afterwards.193 194CTRL-R CTRL-F *c_CTRL-R_CTRL-F* *c_<C-R>_<C-F>*195CTRL-R CTRL-P *c_CTRL-R_CTRL-P* *c_<C-R>_<C-P>*196CTRL-R CTRL-W *c_CTRL-R_CTRL-W* *c_<C-R>_<C-W>*197CTRL-R CTRL-A *c_CTRL-R_CTRL-A* *c_<C-R>_<C-A>*198CTRL-R CTRL-L *c_CTRL-R_CTRL-L* *c_<C-R>_<C-L>*199 Insert the object under the cursor:200 CTRL-F the Filename under the cursor201 CTRL-P the Filename under the cursor, expanded with202 'path' as in |gf|203 CTRL-W the Word under the cursor204 CTRL-A the WORD under the cursor; see |WORD|205 CTRL-L the line under the cursor206 207 When 'incsearch' is set the cursor position at the end of the208 currently displayed match is used. With CTRL-W the part of209 the word that was already typed is not inserted again.210 211 *c_CTRL-R_CTRL-R* *c_<C-R>_<C-R>*212 *c_CTRL-R_CTRL-O* *c_<C-R>_<C-O>*213CTRL-R CTRL-R {register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L}214CTRL-R CTRL-O {register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L}215 Insert register or object under the cursor. Works like216 |c_CTRL-R| but inserts the text literally. For example, if217 register a contains "xy^Hz" (where ^H is a backspace),218 "CTRL-R a" will insert "xz" while "CTRL-R CTRL-R a" will219 insert "xy^Hz".220 221CTRL-\ e {expr} *c_CTRL-\_e*222 Evaluate {expr} and replace the whole command line with the223 result. You will be prompted for the expression, type <Enter>224 to finish it. It's most useful in mappings though. See225 |expression|.226 See |c_CTRL-R_=| for inserting the result of an expression.227 Useful functions are |getcmdtype()|, |getcmdline()| and228 |getcmdpos()|.229 The cursor position is unchanged, except when the cursor was230 at the end of the line, then it stays at the end.231 |setcmdpos()| can be used to set the cursor position.232 The |sandbox| is used for evaluating the expression to avoid233 nasty side effects.234 Example: >235 :cmap <F7> <C-\>eAppendSome()<CR>236 :func AppendSome()237 :let cmd = getcmdline() .. " Some()"238 :" place the cursor on the )239 :call setcmdpos(strlen(cmd))240 :return cmd241 :endfunc242< This doesn't work recursively, thus not when already editing243 an expression. But it is possible to use in a mapping.244 245 *c_CTRL-Y*246CTRL-Y When there is a modeless selection, copy the selection into247 the clipboard. |modeless-selection|248 If there is no selection CTRL-Y is inserted as a character.249 See 'wildmenu' for behavior during wildmenu completion mode.250 251CTRL-M or CTRL-J *c_CTRL-M* *c_CTRL-J* *c_<NL>* *c_<CR>* *c_CR*252<CR> or <NL> start entered command253 254CTRL-[ *c_CTRL-[* *c_<Esc>* *c_Esc*255<Esc> When typed and 'x' not present in 'cpoptions', quit256 Command-line mode without executing. In macros or when 'x'257 present in 'cpoptions', start entered command.258 Note: If your <Esc> key is hard to hit on your keyboard, train259 yourself to use CTRL-[.260 *c_CTRL-C*261CTRL-C quit command-line without executing262 263 *c_<Up>* *c_Up*264<Up> recall older command-line from history, whose beginning265 matches the current command-line (see below). See 'wildmenu'266 for behavior during wildmenu completion mode.267 {not available when compiled without the |+cmdline_hist|268 feature}269 *c_<Down>* *c_Down*270<Down> recall more recent command-line from history, whose beginning271 matches the current command-line (see below). See 'wildmenu'272 for behavior during wildmenu completion mode.273 {not available when compiled without the |+cmdline_hist|274 feature}275 276 *c_<S-Up>* *c_<PageUp>*277<S-Up> or <PageUp>278 recall older command-line from history279 {not available when compiled without the |+cmdline_hist|280 feature}281 *c_<S-Down>* *c_<PageDown>*282<S-Down> or <PageDown>283 recall more recent command-line from history284 {not available when compiled without the |+cmdline_hist|285 feature}286 287CTRL-D command-line completion (see |cmdline-completion|)288'wildchar' option289 command-line completion (see |cmdline-completion|)290CTRL-N command-line completion (see |cmdline-completion|)291CTRL-P command-line completion (see |cmdline-completion|)292CTRL-A command-line completion (see |cmdline-completion|)293CTRL-L command-line completion (see |cmdline-completion|)294 295 *c_CTRL-_*296CTRL-_ a - switch between Hebrew and English keyboard mode, which is297 private to the command-line and not related to hkmap.298 This is useful when Hebrew text entry is required in the299 command-line, searches, abbreviations, etc. Applies only if300 Vim is compiled with the |+rightleft| feature and the301 'allowrevins' option is set.302 See |rileft.txt|.303 304 b - switch between Farsi and English keyboard mode, which is305 private to the command-line and not related to fkmap. In306 Farsi keyboard mode the characters are inserted in reverse307 insert manner. This is useful when Farsi text entry is308 required in the command-line, searches, abbreviations, etc.309 Applies only if Vim is compiled with the |+farsi| feature.310 See |farsi.txt|.311 312 *c_CTRL-^*313CTRL-^ Toggle the use of language |:lmap| mappings and/or Input314 Method.315 When typing a pattern for a search command and 'imsearch' is316 not -1, VAL is the value of 'imsearch', otherwise VAL is the317 value of 'iminsert'.318 When language mappings are defined:319 - If VAL is 1 (langmap mappings used) it becomes 0 (no langmap320 mappings used).321 - If VAL was not 1 it becomes 1, thus langmap mappings are322 enabled.323 When no language mappings are defined:324 - If VAL is 2 (Input Method is used) it becomes 0 (no input325 method used)326 - If VAL has another value it becomes 2, thus the Input Method327 is enabled.328 These language mappings are normally used to type characters329 that are different from what the keyboard produces. The330 'keymap' option can be used to install a whole number of them.331 When entering a command line, langmap mappings are switched332 off, since you are expected to type a command. After333 switching it on with CTRL-^, the new state is not used again334 for the next command or Search pattern.335 336 *c_CTRL-]*337CTRL-] Trigger abbreviation, without inserting a character.338 339For Emacs-style editing on the command-line see |emacs-keys|.340 341The <Up> and <Down> keys take the current command-line as a search string.342The beginning of the next/previous command-lines are compared with this343string. The first line that matches is the new command-line. When typing344these two keys repeatedly, the same string is used again. For example, this345can be used to find the previous substitute command: Type ":s" and then <Up>.346The same could be done by typing <S-Up> a number of times until the desired347command-line is shown. (Note: the shifted arrow keys do not work on all348terminals)349 350 *:his* *:history*351:his[tory] Print the history of last entered commands.352 {not available when compiled without the |+cmdline_hist|353 feature}354 355:his[tory] [{name}] [{first}][, [{last}]]356 List the contents of history {name} which can be:357 c[md] or : command-line history358 s[earch] or / or ? search string history359 e[xpr] or = expression register history360 i[nput] or @ input line history361 d[ebug] or > debug command history362 a[ll] all of the above363 364 If the numbers {first} and/or {last} are given, the respective365 range of entries from a history is listed. These numbers can366 be specified in the following form:367 *:history-indexing*368 A positive number represents the absolute index of an entry369 as it is given in the first column of a :history listing.370 This number remains fixed even if other entries are deleted.371 (see |E1510|)372 373 A negative number means the relative position of an entry,374 counted from the newest entry (which has index -1) backwards.375 376 Examples:377 List entries 6 to 12 from the search history: >378 :history / 6,12379<380 List the penultimate entry from all histories: >381 :history all -2382<383 List the most recent two entries from all histories: >384 :history all -2,385 386:keepp[atterns] {command} *:keepp* *:keeppatterns*387 Execute {command}, without adding anything to the search388 history and, in case of |:s| or |:&|, without modifying the389 last substitute pattern or substitute string.390 391==============================================================================3922. Command-line completion *cmdline-completion*393 394When editing the command-line, a few commands can be used to complete the395word before the cursor. This is available for:396 397- Command names: At the start of the command-line.398- |++opt| values.399- Tags: Only after the ":tag" command.400- File names: Only after a command that accepts a file name or a setting for401 an option that can be set to a file name. This is called file name402 completion.403- Shell command names: After ":!cmd", ":r !cmd" and ":w !cmd". $PATH is used.404- Options: Only after the ":set" command.405- Mappings: Only after a ":map" or similar command.406- Variable and function names: Only after a ":if", ":call" or similar command.407 408The number of help item matches is limited (currently to 300) to avoid a long409delay when there are very many matches.410 411For automatic completion as you type (without pressing a key like <Tab>),412see |cmdline-autocompletion|.413 414These are the commands that can be used:415 416 *c_CTRL-D*417CTRL-D List names that match the pattern in front of the cursor.418 When showing file names, directories are highlighted (see419 'highlight' option). Names where 'suffixes' matches are moved420 to the end.421 The 'wildoptions' option can be set to "tagfile" to list the422 file of matching tags.423 *c_CTRL-I* *c_wildchar* *c_<Tab>* */_<Tab>*424'wildchar' option425 A match is done on the pattern in front of the cursor. The426 match (if there are several, the first match) is inserted427 in place of the pattern. (Note: does not work inside a428 macro, because <Tab> or <Esc> are mostly used as 'wildchar',429 and these have a special meaning in some macros.) When typed430 again and there were multiple matches, the next431 match is inserted. After the last match, the first is used432 again (wrap around).433 434 In search context use <CTRL-V><Tab> or "\t" to search for a435 literal <Tab> instead of triggering completion.436 437 The behavior can be changed with the 'wildmode' option.438 *c_<S-Tab>*439<S-Tab> Like 'wildchar' or <Tab>, but begin with the last match and440 then go to the previous match.441 <S-Tab> does not work everywhere.442 *c_CTRL-N*443CTRL-N After using 'wildchar' which got multiple matches, go to next444 match. Otherwise recall more recent command-line from445 history.446 *c_CTRL-P*447CTRL-P After using 'wildchar' which got multiple matches, go to448 previous match. Otherwise recall older command-line from449 history.450 *c_CTRL-A*451CTRL-A All names that match the pattern in front of the cursor are452 inserted.453 *c_CTRL-L*454CTRL-L A match is done on the pattern in front of the cursor. If455 there is one match, it is inserted in place of the pattern.456 If there are multiple matches the longest common part is457 inserted in place of the pattern. If the result is shorter458 than the pattern, no completion is done.459 */_CTRL-L*460 When 'incsearch' is set, entering a search pattern for "/" or461 "?" and the current match is displayed then CTRL-L will add462 one character from the end of the current match. If463 'ignorecase' and 'smartcase' are set and the command line has464 no uppercase characters, the added character is converted to465 lowercase.466 *c_CTRL-G* */_CTRL-G*467CTRL-G When 'incsearch' is set, entering a search pattern for "/" or468 "?" and the current match is displayed then CTRL-G will move469 to the next match (does not take |search-offset| into account)470 Use CTRL-T to move to the previous match. Hint: on a regular471 keyboard G is below T.472 *c_CTRL-T* */_CTRL-T*473CTRL-T When 'incsearch' is set, entering a search pattern for "/" or474 "?" and the current match is displayed then CTRL-T will move475 to the previous match (does not take |search-offset| into476 account).477 Use CTRL-G to move to the next match. Hint: on a regular478 keyboard T is above G.479 480The 'wildchar' option defaults to <Tab> (CTRL-E when in Vi compatible mode; in481a previous version <Esc> was used). In the pattern standard |wildcards| are482accepted when matching file names.483 484When repeating 'wildchar' or CTRL-N you cycle through the matches, eventually485ending up back to what was typed. If the first match is not what you wanted,486you can use <S-Tab> or CTRL-P to go straight back to what you typed.487 488The 'wildmenu' option can be set to show the matches just above the command489line.490 491The 'wildoptions' option provides additional configuration to use a popup menu492for 'wildmenu', and to use fuzzy matching.493 494The 'wildignorecase' option can be set to ignore case in filenames. For495completing other texts (e.g. command names), the 'ignorecase' option is used496instead (fuzzy matching always ignores case, however).497 498If you like tcsh's autolist completion, you can use this mapping: >499 :cnoremap X <C-L><C-D>500(Where X is the command key to use, <C-L> is CTRL-L and <C-D> is CTRL-D)501This will find the longest match and then list all matching files.502 503If you like tcsh's autolist completion, you can use the 'wildmode' option to504emulate it. For example, this mimics autolist=ambiguous: >505 :set wildmode=longest,list506This will find the longest match with the first 'wildchar', then list all507matching files with the next.508 509 *complete-script-local-functions*510When completing user function names, prepend "s:" to find script-local511functions.512 513 *suffixes*514For file name completion you can use the 'suffixes' option to set a priority515between files with almost the same name. If there are multiple matches,516those files with an extension that is in the 'suffixes' option are ignored.517The default is ".bak,~,.o,.h,.info,.swp,.obj", which means that files ending518in ".bak", "~", ".o", ".h", ".info", ".swp" and ".obj" are sometimes ignored.519 520An empty entry, two consecutive commas, match a file name that does not521contain a ".", thus has no suffix. This is useful to ignore "prog" and prefer522"prog.c".523 524Examples:525 526 pattern: files: match: ~527 test* test.c test.h test.o test.c528 test* test.h test.o test.h and test.o529 test* test.i test.h test.c test.i and test.c530 531It is impossible to ignore suffixes with two dots.532 533If there is more than one matching file (after ignoring the ones matching534the 'suffixes' option) the first file name is inserted. You can see that535there is only one match when you type 'wildchar' twice and the completed536match stays the same. You can get to the other matches by entering537'wildchar', CTRL-N or CTRL-P. All files are included, also the ones with538extensions matching the 'suffixes' option.539 540To completely ignore files with some extension use 'wildignore'.541 542To match only files that end at the end of the typed text append a "$". For543example, to match only files that end in ".c": >544 :e *.c$545This will not match a file ending in ".cpp". Without the "$" it does match.546 547If you would like using <S-Tab> for CTRL-P in an xterm, put this command in548your .cshrc: >549 xmodmap -e "keysym Tab = Tab Find"550And this in your .vimrc: >551 :cmap <Esc>[1~ <C-P>552< *complete-set-option*553When setting an option using |:set=|, the old value of an option can be554obtained by hitting 'wildchar' just after the '='. For example, typing555'wildchar' after ":set dir=" will insert the current value of 'dir'. This556overrules file name completion for the options that take a file name.557 558When using |:set=|, |:set+=|, or |:set^=|, string options that have559pre-defined names or syntax (e.g. 'diffopt', 'listchars') or are a list of560single-character flags (e.g. 'shortmess') will also present a list of possible561values for completion when using 'wildchar'.562 563When using |:set-=|, comma-separated options like 'diffopt' or 'backupdir'564will show each item separately. Flag list options like 'shortmess' will show565both the entire old value and the individual flags. Otherwise completion will566just fill in with the entire old value.567 568==============================================================================5693. Ex command-lines *cmdline-lines*570 571The Ex commands have a few specialties:572 573 *:quote* *:comment*574'"' at the start of a line causes the whole line to be ignored. '"'575after a command causes the rest of the line to be ignored. This can be used576to add comments. Example: >577 :set ai "set 'autoindent' option578It is not possible to add a comment to a shell command ":!cmd" or to the579":map" command and a few others (mainly commands that expect expressions)580that see the '"' as part of their argument:581 582 :argdo583 :autocmd584 :bufdo585 :cexpr (and the like)586 :cdo (and the like)587 :command588 :cscope (and the like)589 :debug590 :display591 :echo (and the like)592 :elseif593 :execute594 :folddoopen595 :folddoclosed596 :for597 :grep (and the like)598 :help (and the like)599 :if600 :let601 :make602 :map (and the like including :abbrev commands)603 :menu (and the like)604 :mkspell605 :normal606 :ownsyntax607 :popup608 :promptfind (and the like)609 :registers610 :return611 :sort612 :syntax613 :tabdo614 :tearoff615 :vimgrep (and the like)616 :while617 :windo618 619 *:bar* *:\bar*620'|' can be used to separate commands, so you can give multiple commands in one621line. If you want to use '|' in an argument, precede it with '\'.622 623These commands see the '|' as their argument, and can therefore not be624followed by another Vim command:625 :argdo626 :autocmd627 :bufdo628 :cdo629 :cfdo630 :command631 :cscope632 :debug633 :eval634 :folddoopen635 :folddoclosed636 :function637 :global638 :help639 :helpfind640 :helpgrep641 :lcscope642 :ldo643 :lfdo644 :lhelpgrep645 :make646 :normal647 :perl648 :perldo649 :promptfind650 :promptrepl651 :pyfile652 :python653 :registers654 :read !655 :scscope656 :sign657 :tabdo658 :tcl659 :tcldo660 :tclfile661 :terminal662 :vglobal663 :windo664 :write !665 :[range]!666 a user defined command without the "-bar" argument |:command|667 668 and the following |Vim9-script| keywords:669 :abstract670 :class671 :enum672 :interface673 674Note that this is confusing (inherited from Vi): With ":g" the '|' is included675in the command, with ":s" it is not.676 677To be able to use another command anyway, use the ":execute" command.678Example (append the output of "ls" and jump to the first line): >679 :execute 'r !ls' | '[680 681There is one exception: When the 'b' flag is present in 'cpoptions', with the682":map" and ":abbr" commands and friends CTRL-V needs to be used instead of683'\'. You can also use "<Bar>" instead. See also |map_bar|.684 685Examples: >686 :!ls | wc view the output of two commands687 :r !ls | wc insert the same output in the text688 :%g/foo/p|> moves all matching lines one shiftwidth689 :%s/foo/bar/|> moves one line one shiftwidth690 :map q 10^V| map "q" to "10|"691 :map q 10\| map \ l map "q" to "10\" and map "\" to "l"692 (when 'b' is present in 'cpoptions')693 694You can also use <NL> to separate commands in the same way as with '|'. To695insert a <NL> use CTRL-V CTRL-J. "^@" will be shown. Using '|' is the696preferred method. But for external commands a <NL> must be used, because a697'|' is included in the external command. To avoid the special meaning of <NL>698it must be preceded with a backslash. Example: >699 :r !date<NL>-join700This reads the current date into the file and joins it with the previous line.701 702Note that when the command before the '|' generates an error, the following703commands will not be executed.704 705 706Because of Vi compatibility the following strange commands are supported: >707 :| print current line (like ":p")708 :3| print line 3 (like ":3p")709 :3 goto line 3710 711A colon is allowed between the range and the command name. It is ignored712(this is Vi compatible). For example: >713 :1,$:s/pat/string714 715When the character '%' or '#' is used where a file name is expected, they are716expanded to the current and alternate file name (see the chapter "editing717files" |:_%| |:_#|).718 719Embedded spaces in file names are allowed on the Amiga if one file name is720expected as argument. Trailing spaces will be ignored, unless escaped with a721backslash or CTRL-V. Note that the ":next" command uses spaces to separate722file names. Escape the spaces to include them in a file name. Example: >723 :next foo\ bar goes\ to school\724starts editing the three files "foo bar", "goes to" and "school ".725 726When you want to use the special characters '"' or '|' in a command, or want727to use '%' or '#' in a file name, precede them with a backslash. The728backslash is not required in a range and in the ":substitute" command.729See also |`=|.730 731 *:_!*732The '!' (bang) character after an Ex command makes the command behave in a733different way. The '!' should be placed immediately after the command,734without any blanks in between. If you insert blanks the '!' will be seen as735an argument for the command, which has a different meaning. For example:736 :w! name write the current buffer to file "name", overwriting737 any existing file738 :w !name send the current buffer as standard input to command739 "name"740 741==============================================================================7424. Ex command-line ranges *cmdline-ranges* *[range]* *E16*743 744Some Ex commands accept a line range in front of them. This is noted as745[range]. It consists of one or more line specifiers, separated with ',' or746';'.747 748The basics are explained in section |10.3| of the user manual.749 750In |Vim9| script, a range needs to be prefixed with a colon to avoid ambiguity751with continuation lines. For example, "+" can be used for a range but is also752a continuation of an expression: >753 var result = start754 + print755<If the "+" is a range, as it is here, in Vim9 script it must be prefixed756with a colon (otherwise you will get error |E1050|): >757 vim9script758 :+ print759<760 *:,* *:;*761When separated with ';' the cursor position will be set to that line762before interpreting the next line specifier. This doesn't happen for ','.763Examples: >764 4,/this line/765< from line 4 till match with "this line" after the cursor line. >766 5;/that line/767< from line 5 till match with "that line" after line 5.768 769The default line specifier for most commands is the cursor position, but the770commands ":write" and ":global" have the whole buffer (1,$) as default.771 772If more line specifiers are given than required for the command, when comma773separated, the leftmost one(s) will be ignored, e.g., the -2,+ in this: >774 :-2,+,-2,. print775<When semicolon separated, the leftmost specifier to the penultimate one are776summed, e.g., -4 + 3 - 1 = -2, in this: >777 :-4;+3;-1;+2 print778<779Line numbers may be specified with: *:range* *{address}*780 {number} an absolute line number *E1247*781 . the current line *:.*782 $ the last line of the buffer *:$*783 % equal to 1,$ (the entire buffer) *:%*784 * equal to '<,'> (the lines of the last785 selected Visual area; see |:star| below)786 'x the line of the position of mark x *:'x*787 (where x is any {a-z} mark)788 'X the line of the position of mark X *:'X*789 (where X is any {A-Z0-9} mark, though790 when X is in another buffer it cannot791 be used in a range)792 '[ the first line of the most recent *:'[*793 change or yank794 '] the last line of the most recent *:']*795 change or yank796 '< the first line of the most recently *:'<*797 selected Visual area798 '> the last line of the most recently *:'>*799 selected Visual area800 '' the line of the position before the *:''*801 latest jump, or where the last "m'"/"m`"802 command was given (though '' is 1 if it803 isn't in the current buffer)804 '" the line of the cursor position when *:'quote*805 last exiting the buffer806 '^ the line of the cursor position the *:'^*807 last time Insert mode was stopped808 '. the line of the cursor position when the *:'.*809 buffer was last changed810 '( the line of the first character of the *:'(*811 current sentence812 ') the line of the first character after *:')*813 the end of the current sentence814 '{ the first empty line before the *:'{*815 paragraph containing the cursor816 '} the first empty line after the *:'}*817 paragraph containing the cursor818 /{pattern}[/] the next line where {pattern} matches *:/*819 also see |:range-pattern| below820 ?{pattern}[?] the previous line where {pattern} matches *:?*821 also see |:range-pattern| below822 \/ the next line where the most recent823 search pattern matches824 \? the previous line where the most recent825 search pattern matches826 \& the next line where the most recent827 substitute pattern matches828 829 Note: "next line" and "previous line" do not include matches appearing830 in the current line.831 832 *:range-offset*833Each line specifier may be followed by one or more '+' or '-' and an optional834number. That value is added or subtracted from the preceding line number.835So, for example, 'x+2 is two lines after the line containing mark x. If the836number is omitted, +1 is used for each '+' and -1 for each '-' so, e.g., 'x++837and 'x+2 are synonymous. If there is nothing before the '+' or '-', for the838first line number in [range] the current line is used as the relative839starting point. So, -,. means, "the line before the current line to the840current line". The value of the second line number in [range] depends on841whether a comma or semicolon separates the line numbers (see |:,| and |:;|).842Examples: If the cursor is within the line below this one, any of these843commands will print the tag line ":range-offset" and the line, "Each...": >844 :-11;+1 print845 :-----------,-10 print846 :?Each line?-;+ print847 :'{+,'{+2 print848 :'{+1;')-1 print849< *:range-closed-fold*850When a line number after the comma is in a closed fold it is adjusted to the851last line of the fold, thus the whole fold is included.852 853When a number is added this is done after the adjustment to the last line of854the fold. This means these lines are additionally included in the range. For855example: >856 :3,4+2print857On this text:858 1 one ~859 2 two ~860 3 three ~861 4 four FOLDED ~862 5 five FOLDED ~863 6 six ~864 7 seven ~865 8 eight ~866Where lines four and five are a closed fold, ends up printing lines 3 to 7.867The 7 comes from the "4" in the range, which is adjusted to the end of the868closed fold, which is 5, and then the offset 2 is added.869 870An example for subtracting (which isn't very useful): >871 :2,4-1print872On this text:873 1 one ~874 2 two ~875 3 three FOLDED ~876 4 four FOLDED ~877 5 five FOLDED ~878 6 six FOLDED ~879 7 seven ~880 8 eight ~881Where lines three to six are a closed fold, ends up printing lines 2 to 6.882The 6 comes from the "4" in the range, which is adjusted to the end of the883closed fold, which is 6, and then 1 is subtracted, then this is still in the884closed fold and the last line of that fold is used, which is 6.885 886 *:range-pattern*887The "/" and "?" after {pattern} are required to separate the pattern from888anything that follows.889 890The "/" and "?" may be preceded with another address. The search starts from891there. The difference from using ';' is that the cursor isn't moved.892Examples: >893 /pat1//pat2/ Find line containing "pat2" after line containing894 "pat1", without moving the cursor.895 7;/pat2/ Find line containing "pat2", after line 7, leaving896 the cursor in line 7.897 898The {number} must be between 0 and the number of lines in the file. When899using a 0 (zero) this is interpreted as a 1 by most commands. Commands that900use it as a count do use it as a zero (|:tag|, |:pop|, etc). Some commands901interpret the zero as "before the first line" (|:read|, search pattern, etc).902 903Examples: >904 .+3 three lines below the cursor905 /that/+1 the line below the next line containing "that"906 .,$ from current line until end of file907 0;/that the first line containing "that", also matches in the908 first line.909 1;/that the first line after line 1 containing "that"910 911Some commands allow for a count after the command. This count is used as the912number of lines to be used, starting with the line given in the last line913specifier (the default is the cursor line). The commands that accept a count914are the ones that use a range but do not have a file name argument (because915a file name can also be a number). The count cannot be negative.916 917Examples: >918 :s/x/X/g 5 substitute 'x' by 'X' in the current line and four919 following lines920 :23d 4 delete lines 23, 24, 25 and 26921 922 923Folds and Range924 925When folds are active the line numbers are rounded off to include the whole926closed fold. See |fold-behavior|.927 928 929Reverse Range *E493*930 931A range should have the lower line number first. If this is not the case, Vim932will ask you if it should swap the line numbers.933 Backwards range given, OK to swap ~934This is not done within the global command ":g".935 936You can use ":silent" before a command to avoid the question, the range will937always be swapped then.938 939 940Count and Range *N:*941 942When giving a count before entering ":", this is translated into: >943 :.,.+(count - 1)944In words: The "count" lines at and after the cursor. Example: To delete945three lines: >946 3:d<CR> is translated into: .,.+2d<CR>947<948 949Visual Mode and Range950 *v_:*951{Visual}: Starts a command-line with the Visual selected lines as a952 range. The code `:'<,'>` is used for this range, which makes953 it possible to select a similar line from the command-line954 history for repeating a command on different Visually selected955 lines.956 957:* *:star* *:star-visual-range*958 When Visual mode was already ended, a short way to use the959 Visual area for a range is `:*`. This requires that "*" does960 not appear in 'cpo', see |cpo-star|. Otherwise you will have961 to type `:'<,'>`962 For when "*" is in 'cpo' see |:star-compatible|.963 964==============================================================================9655. Ex command-line flags *ex-flags*966 967These flags are supported by a selection of Ex commands. They print the line968that the cursor ends up after executing the command:969 970 l output like for |:list|971 # add line number972 p output like for |:print|973 974The flags can be combined, thus "l#" uses both a line number and |:list| style975output.976 977==============================================================================9786. Ex special characters *cmdline-special*979 980Note: These are special characters in the executed command line. If you want981to insert special things while typing you can use the CTRL-R command. For982example, "%" stands for the current file name, while CTRL-R % inserts the983current file name right away. See |c_CTRL-R|.984 985Note: If you want to avoid the effects of special characters in a Vim script986you may want to use |fnameescape()|. Also see |`=|.987 988 989In Ex commands, at places where a file name can be used, the following990characters have a special meaning. These can also be used in the expression991function |expand()|.992 % Is replaced with the current file name. *:_%* *c_%*993 # Is replaced with the alternate file name. *:_#* *c_#*994 This is remembered for every window.995 #n (where n is a number) is replaced with *:_#0* *:_#n*996 the file name of buffer n. "#0" is the same as "#". *c_#n*997 ## Is replaced with all names in the argument list *:_##* *c_##*998 concatenated, separated by spaces. Each space in a name999 is preceded with a backslash.1000 #<n (where n is a number > 0) is replaced with old *:_#<* *c_#<*1001 file name n. See |:oldfiles| or |v:oldfiles| to get the1002 number. *E809*1003 {only when compiled with the |+eval| and |+viminfo| features}1004In |Vim9-script| # is used to start a comment, use %% for the alternate file1005name:1006 % Is replaced with the current file name.1007 %% Is replaced with the alternate file name. *:_%%* *c_%%*1008 %%n (where n is a number) is replaced with *:_%%0* *:_%%n*1009 the file name of buffer n. "%%0" is the same as "%%". *c_%%n*1010 %%% Is replaced with all names in the argument *:_%%%* *c_%%%#*1011 list concatenated, separated by spaces.1012 %%<n (where n is a number > 0) is replaced with old *:_%%<* *c_%%<*1013 file name n.1014 1015Note that these, except "#<n", give the file name as it was typed. If an1016absolute path is needed (when using the file name from a different directory),1017you need to add ":p". See |filename-modifiers|.1018 1019The "#<n" item returns an absolute path, but it will start with "~/" for files1020below your home directory.1021 1022Note that backslashes are inserted before spaces, so that the command will1023correctly interpret the file name. But this doesn't happen for shell1024commands. For those you probably have to use quotes (this fails for files1025that contain a quote and wildcards): >1026 :!ls "%"1027 :r !spell "%"1028 1029To avoid the special meaning of '%' and '#' insert a backslash before it.1030Detail: The special meaning is always escaped when there is a backslash before1031it, no matter how many backslashes.1032 you type: result ~1033 # alternate.file1034 \# #1035 \\# \#1036Also see |`=|.1037 1038 *E499* *E500*1039Note: these are typed literally, they are not special keys!1040 *:<cword>* *<cword>*1041 <cword> is replaced with the word under the cursor (like |star|)1042 *:<cWORD>* *<cWORD>*1043 <cWORD> is replaced with the WORD under the cursor (see |WORD|)1044 *:<cexpr>* *<cexpr>*1045 <cexpr> is replaced with the word under the cursor, including more1046 to form a C expression. E.g., when the cursor is on "arg"1047 of "ptr->arg" then the result is "ptr->arg"; when the1048 cursor is on "]" of "list[idx]" then the result is1049 "list[idx]". This is used for |v:beval_text|.1050 *:<cfile>* *<cfile>*1051 <cfile> is replaced with the path name under the cursor (like what1052 |gf| uses)1053 *:<afile>* *<afile>*1054 <afile> When executing autocommands, is replaced with the file name1055 of the buffer being manipulated, or the file for a read or1056 write. *E495*1057 *:<abuf>* *<abuf>*1058 <abuf> When executing autocommands, is replaced with the currently1059 effective buffer number. It is not set for all events,1060 also see |bufnr()|. For ":r file" and ":so file" it is the1061 current buffer, the file being read/sourced is not in a1062 buffer. *E496*1063 *:<amatch>* *<amatch>*1064 <amatch> When executing autocommands, is replaced with the match for1065 which this autocommand was executed. *E497*1066 It differs from <afile> when the file name isn't used to1067 match with (for FileType, Syntax and SpellFileMissing1068 events).1069 When the match is with a file name, it is expanded to the1070 full path.1071 *:<sfile>* *<sfile>*1072 <sfile> When executing a `:source` command, is replaced with the1073 file name of the sourced file. *E498*1074 When executing a legacy function, is replaced with the call1075 stack, as with <stack> (this is for backwards1076 compatibility, using <stack> or <script> is preferred).1077 In Vim9 script using <sfile> in a function gives error1078 *E1245* .1079 Note that filename-modifiers are useless when <sfile> is1080 not used inside a script.1081 *:<stack>* *<stack>*1082 <stack> is replaced with the call stack, using1083 "function {function-name}[{lnum}]" for a function line1084 and "script {file-name}[{lnum}]" for a script line, and1085 ".." in between items. E.g.:1086 "function {function-name1}[{lnum}]..{function-name2}[{lnum}]"1087 If there is no call stack you get error *E489* .1088 *:<script>* *<script>*1089 <script> When executing a `:source` command, is replaced with the file1090 name of the sourced file. When executing a function, is1091 replaced with the file name of the script where it is1092 defined.1093 If the file name cannot be determined you get error *E1274* .1094 *:<slnum>* *<slnum>*1095 <slnum> When executing a `:source` command, is replaced with the1096 line number. *E842*1097 When executing a function it's the line number relative to1098 the start of the function.1099 *:<sflnum>* *<sflnum>*1100 <sflnum> When executing a script, is replaced with the line number.1101 It differs from <slnum> in that <sflnum> is replaced with1102 the script line number in any situation. *E961*1103 *:<client>* *<client>*1104 <client> is replaced with the {clientid} of the last received1105 message in |server2client()|1106 1107 *filename-modifiers*1108*:_%:* *::8* *::p* *::.* *::~* *::h* *::t* *::r* *::e* *::s* *::gs* *::S*1109 *%:8* *%:p* *%:.* *%:~* *%:h* *%:t* *%:r* *%:e* *%:s* *%:gs* *%:S*1110The file name modifiers can be used after "%", "#", "#n", "<cfile>",1111"<sfile>", "<afile>" or "<abuf>". They are also used with the |fnamemodify()|1112function.1113 1114These modifiers can be given, in this order:1115 :p Make file name a full path. Must be the first modifier. Also1116 changes "~/" (and "~user/" for Unix and VMS) to the path for1117 the home directory. If the name is a directory a path1118 separator is added at the end. For a file name that does not1119 exist and does not have an absolute path the result is1120 unpredictable. On MS-Windows an 8.3 filename is expanded to1121 the long name.1122 :8 Converts the path to 8.3 short format (currently only on1123 MS-Windows). Will act on as much of a path that is an1124 existing path.1125 :~ Reduce file name to be relative to the home directory, if1126 possible. File name is unmodified if it is not below the home1127 directory.1128 :. Reduce file name to be relative to current directory, if1129 possible. File name is unmodified if it is not below the1130 current directory.1131 For maximum shortness, use ":~:.".1132 :h Head of the file name (the last component and any separators1133 removed). Cannot be used with :e, :r or :t.1134 Can be repeated to remove several components at the end.1135 When the file name ends in a path separator, only the path1136 separator is removed. Thus ":p:h" on a directory name results1137 on the directory name itself (without trailing slash).1138 When the file name is an absolute path (starts with "/" for1139 Unix; "x:\" for Win32; "drive:" for Amiga), that part is not1140 removed. When there is no head (path is relative to current1141 directory) the result is empty.1142 :t Tail of the file name (last component of the name). Must1143 precede any :r or :e.1144 :r Root of the file name (the last extension removed). When1145 there is only an extension (file name that starts with '.',1146 e.g., ".vimrc"), it is not removed. Can be repeated to remove1147 several extensions (last one first).1148 :e Extension of the file name. Only makes sense when used alone.1149 When there is no extension the result is empty.1150 When there is only an extension (file name that starts with1151 '.'), the result is empty. Can be repeated to include more1152 extensions. If there are not enough extensions (but at least1153 one) as much as possible are included.1154 :s?pat?sub?1155 Substitute the first occurrence of "pat" with "sub". This1156 works like the |:s| command. "pat" is a regular expression.1157 Any character can be used for '?', but it must not occur in1158 "pat" or "sub".1159 After this, the previous modifiers can be used again. For1160 example ":p", to make a full path after the substitution.1161 :gs?pat?sub?1162 Substitute all occurrences of "pat" with "sub". Otherwise1163 this works like ":s".1164 :S Escape special characters for use with a shell command (see1165 |shellescape()|). Must be the last one. Examples: >1166 :!dir <cfile>:S1167 :call system('chmod +w -- ' .. expand('%:S'))1168 1169Examples, when the file name is "src/version.c", current dir1170"/home/mool/vim": >1171 :p /home/mool/vim/src/version.c1172 :p:. src/version.c1173 :p:~ ~/vim/src/version.c1174 :h src1175 :p:h /home/mool/vim/src1176 :p:h:h /home/mool/vim1177 :t version.c1178 :p:t version.c1179 :r src/version1180 :p:r /home/mool/vim/src/version1181 :t:r version1182 :e c1183 :s?version?main? src/main.c1184 :s?version?main?:p /home/mool/vim/src/main.c1185 :p:gs?/?\\? \home\mool\vim\src\version.c1186 1187Examples, when the file name is "src/version.c.gz": >1188 :p /home/mool/vim/src/version.c.gz1189 :e gz1190 :e:e c.gz1191 :e:e:e c.gz1192 :e:e:r c1193 :r src/version.c1194 :r:e c1195 :r:r src/version1196 :r:r:r src/version1197<1198 *extension-removal* *:_%<*1199If a "<" is appended to "%", "#", "#n" or "CTRL-V p" the extension of the file1200name is removed (everything after and including the last '.' in the file