1*cmdline.txt* For Vim version 8.2. Last change: 2021 Aug 06 2 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| 205. Ex command-line flags |ex-flags| 216. Ex special characters |cmdline-special| 227. Command-line window |cmdline-window| 23 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 31Note that if your keyboard does not have working cursor keys or any of the 32other special keys, you can use ":cnoremap" to define another key for them. 33For example, to define tcsh style editing keys: *tcsh-style* > 34 :cnoremap <C-A> <Home> 35 :cnoremap <C-F> <Right> 36 :cnoremap <C-B> <Left> 37 :cnoremap <Esc>b <S-Left> 38 :cnoremap <Esc>f <S-Right> 39(<> notation |<>|; type all this literally) 40 41 *cmdline-too-long* 42When the command line is getting longer than what fits on the screen, only the 43part that fits will be shown. The cursor can only move in this visible part, 44thus you cannot edit beyond that. 45 46 *cmdline-history* *history* 47The command-lines that you enter are remembered in a history table. You can 48recall them with the up and down cursor keys. There are actually five 49history tables: 50- one for ':' commands 51- one for search strings 52- one for expressions 53- one for input lines, typed for the |input()| function. 54- one for debug mode commands 55These are completely separate. Each history can only be accessed when 56entering the same type of line. 57Use the 'history' option to set the number of lines that are remembered 58(default: 50). 59Notes: 60- When you enter a command-line that is exactly the same as an older one, the 61 old one is removed (to avoid repeated commands moving older commands out of 62 the history). 63- Only commands that are typed are remembered. Ones that completely come from 64 mappings are not put in the history. 65- All searches are put in the search history, including the ones that come 66 from commands like "*" and "#". But for a mapping, only the last search is 67 remembered (to avoid that long mappings trash the history). 68{not available when compiled without the |+cmdline_hist| feature} 69 70There is an automatic completion of names on the command-line; see 71|cmdline-completion|. 72 73 *c_CTRL-V* 74CTRL-V Insert next non-digit literally. Up to three digits form the 75 decimal value of a single byte. The non-digit and the three 76 digits are not considered for mapping. This works the same 77 way as in Insert mode (see above, |i_CTRL-V|). 78 Note: Under MS-Windows CTRL-V is often mapped to paste text. 79 Use CTRL-Q instead then. 80 When |modifyOtherKeys| is enabled then special Escape sequence 81 is converted back to what it was without |modifyOtherKeys|, 82 unless the Shift key is also pressed. 83 *c_CTRL-Q* 84CTRL-Q Same as CTRL-V. But with some terminals it is used for 85 control flow, it doesn't work then. 86 87CTRL-SHIFT-V *c_CTRL-SHIFT-V* *c_CTRL-SHIFT-Q* 88CTRL-SHIFT-Q Works just like CTRL-V, unless |modifyOtherKeys| is active, 89 then it inserts the Escape sequence for a key with modifiers. 90 91 *c_<Left>* *c_Left* 92<Left> cursor left 93 *c_<Right>* *c_Right* 94<Right> cursor right 95 *c_<S-Left>* 96<S-Left> or <C-Left> *c_<C-Left>* 97 cursor one WORD left 98 *c_<S-Right>* 99<S-Right> or <C-Right> *c_<C-Right>* 100 cursor one WORD right 101CTRL-B or <Home> *c_CTRL-B* *c_<Home>* *c_Home* 102 cursor to beginning of command-line 103CTRL-E or <End> *c_CTRL-E* *c_<End>* *c_End* 104 cursor to end of command-line 105 106 *c_<LeftMouse>* 107<LeftMouse> Move the cursor to the position of the mouse click. 108 109 *c_<MiddleMouse>* 110<MiddleMouse> Paste the contents of the clipboard (for X11 the primary 111 selection). This is similar to using CTRL-R *, but no CR 112 characters are inserted between lines. 113 114CTRL-H *c_<BS>* *c_CTRL-H* *c_BS* 115<BS> Delete the character in front of the cursor (see |:fixdel| if 116 your <BS> key does not do what you want). 117 *c_<Del>* *c_Del* 118<Del> Delete the character under the cursor (at end of line: 119 character before the cursor) (see |:fixdel| if your <Del> 120 key does not do what you want). 121 *c_CTRL-W* 122CTRL-W Delete the |word| before the cursor. This depends on the 123 'iskeyword' option. 124 *c_CTRL-U* 125CTRL-U Remove all characters between the cursor position and 126 the beginning of the line. Previous versions of vim 127 deleted all characters on the line. If that is the 128 preferred behavior, add the following to your .vimrc: > 129 :cnoremap <C-U> <C-E><C-U> 130< 131 *c_<Insert>* *c_Insert* 132<Insert> Toggle between insert and overstrike. 133 134{char1} <BS> {char2} or *c_digraph* 135CTRL-K {char1} {char2} *c_CTRL-K* 136 enter digraph (see |digraphs|). When {char1} is a special 137 key, the code for that key is inserted in <> form. 138 139CTRL-R {register} *c_CTRL-R* *c_<C-R>* 140 Insert the contents of a numbered or named register. Between 141 typing CTRL-R and the second character '"' will be displayed 142 to indicate that you are expected to enter the name of a 143 register. 144 The text is inserted as if you typed it, but mappings and 145 abbreviations are not used. Command-line completion through 146 'wildchar' is not triggered though. And characters that end 147 the command line are inserted literally (<Esc>, <CR>, <NL>, 148 <C-C>). A <BS> or CTRL-W could still end the command line 149 though, and remaining characters will then be interpreted in 150 another mode, which might not be what you intended. 151 Special registers: 152 '"' the unnamed register, containing the text of 153 the last delete or yank 154 '%' the current file name 155 '#' the alternate file name 156 '*' the clipboard contents (X11: primary selection) 157 '+' the clipboard contents 158 '/' the last search pattern 159 ':' the last command-line 160 '-' the last small (less than a line) delete 161 '.' the last inserted text 162 *c_CTRL-R_=* 163 '=' the expression register: you are prompted to 164 enter an expression (see |expression|) 165 (doesn't work at the expression prompt; some 166 things such as changing the buffer or current 167 window are not allowed to avoid side effects) 168 When the result is a |List| the items are used 169 as lines. They can have line breaks inside 170 too. 171 When the result is a Float it's automatically 172 converted to a String. 173 Note that when you only want to move the 174 cursor and not insert anything, you must make 175 sure the expression evaluates to an empty 176 string. E.g.: > 177 <C-R><C-R>=setcmdpos(2)[-1]<CR> 178< See |registers| about registers. 179 Implementation detail: When using the |expression| register 180 and invoking setcmdpos(), this sets the position before 181 inserting the resulting string. Use CTRL-R CTRL-R to set the 182 position afterwards. 183 184CTRL-R CTRL-F *c_CTRL-R_CTRL-F* *c_<C-R>_<C-F>* 185CTRL-R CTRL-P *c_CTRL-R_CTRL-P* *c_<C-R>_<C-P>* 186CTRL-R CTRL-W *c_CTRL-R_CTRL-W* *c_<C-R>_<C-W>* 187CTRL-R CTRL-A *c_CTRL-R_CTRL-A* *c_<C-R>_<C-A>* 188CTRL-R CTRL-L *c_CTRL-R_CTRL-L* *c_<C-R>_<C-L>* 189 Insert the object under the cursor: 190 CTRL-F the Filename under the cursor 191 CTRL-P the Filename under the cursor, expanded with 192 'path' as in |gf| 193 CTRL-W the Word under the cursor 194 CTRL-A the WORD under the cursor; see |WORD| 195 CTRL-L the line under the cursor 196 197 When 'incsearch' is set the cursor position at the end of the 198 currently displayed match is used. With CTRL-W the part of 199 the word that was already typed is not inserted again. 200 201 CTRL-F and CTRL-P: {only when |+file_in_path| feature is 202 included} 203 204 *c_CTRL-R_CTRL-R* *c_<C-R>_<C-R>* 205 *c_CTRL-R_CTRL-O* *c_<C-R>_<C-O>* 206CTRL-R CTRL-R {register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L} 207CTRL-R CTRL-O {register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L} 208 Insert register or object under the cursor. Works like 209 |c_CTRL-R| but inserts the text literally. For example, if 210 register a contains "xy^Hz" (where ^H is a backspace), 211 "CTRL-R a" will insert "xz" while "CTRL-R CTRL-R a" will 212 insert "xy^Hz". 213 214CTRL-\ e {expr} *c_CTRL-\_e* 215 Evaluate {expr} and replace the whole command line with the 216 result. You will be prompted for the expression, type <Enter> 217 to finish it. It's most useful in mappings though. See 218 |expression|. 219 See |c_CTRL-R_=| for inserting the result of an expression. 220 Useful functions are |getcmdtype()|, |getcmdline()| and 221 |getcmdpos()|. 222 The cursor position is unchanged, except when the cursor was 223 at the end of the line, then it stays at the end. 224 |setcmdpos()| can be used to set the cursor position. 225 The |sandbox| is used for evaluating the expression to avoid 226 nasty side effects. 227 Example: > 228 :cmap <F7> <C-\>eAppendSome()<CR> 229 :func AppendSome() 230 :let cmd = getcmdline() . " Some()" 231 :" place the cursor on the ) 232 :call setcmdpos(strlen(cmd)) 233 :return cmd 234 :endfunc 235< This doesn't work recursively, thus not when already editing 236 an expression. But it is possible to use in a mapping. 237 238 *c_CTRL-Y* 239CTRL-Y When there is a modeless selection, copy the selection into 240 the clipboard. |modeless-selection| 241 If there is no selection CTRL-Y is inserted as a character. 242 243CTRL-M or CTRL-J *c_CTRL-M* *c_CTRL-J* *c_<NL>* *c_<CR>* *c_CR* 244<CR> or <NL> start entered command 245 246CTRL-[ *c_CTRL-[* *c_<Esc>* *c_Esc* 247<Esc> When typed and 'x' not present in 'cpoptions', quit 248 Command-line mode without executing. In macros or when 'x' 249 present in 'cpoptions', start entered command. 250 Note: If your <Esc> key is hard to hit on your keyboard, train 251 yourself to use CTRL-[. 252 *c_CTRL-C* 253CTRL-C quit command-line without executing 254 255 *c_<Up>* *c_Up* 256<Up> recall older command-line from history, whose beginning 257 matches the current command-line (see below). 258 {not available when compiled without the |+cmdline_hist| 259 feature} 260 *c_<Down>* *c_Down* 261<Down> recall more recent command-line from history, whose beginning 262 matches the current command-line (see below). 263 {not available when compiled without the |+cmdline_hist| 264 feature} 265 266 *c_<S-Up>* *c_<PageUp>* 267<S-Up> or <PageUp> 268 recall older command-line from history 269 {not available when compiled without the |+cmdline_hist| 270 feature} 271 *c_<S-Down>* *c_<PageDown>* 272<S-Down> or <PageDown> 273 recall more recent command-line from history 274 {not available when compiled without the |+cmdline_hist| 275 feature} 276 277CTRL-D command-line completion (see |cmdline-completion|) 278'wildchar' option 279 command-line completion (see |cmdline-completion|) 280CTRL-N command-line completion (see |cmdline-completion|) 281CTRL-P command-line completion (see |cmdline-completion|) 282CTRL-A command-line completion (see |cmdline-completion|) 283CTRL-L command-line completion (see |cmdline-completion|) 284 285 *c_CTRL-_* 286CTRL-_ a - switch between Hebrew and English keyboard mode, which is 287 private to the command-line and not related to hkmap. 288 This is useful when Hebrew text entry is required in the 289 command-line, searches, abbreviations, etc. Applies only if 290 Vim is compiled with the |+rightleft| feature and the 291 'allowrevins' option is set. 292 See |rileft.txt|. 293 294 b - switch between Farsi and English keyboard mode, which is 295 private to the command-line and not related to fkmap. In 296 Farsi keyboard mode the characters are inserted in reverse 297 insert manner. This is useful when Farsi text entry is 298 required in the command-line, searches, abbreviations, etc. 299 Applies only if Vim is compiled with the |+farsi| feature. 300 See |farsi.txt|. 301 302 *c_CTRL-^* 303CTRL-^ Toggle the use of language |:lmap| mappings and/or Input 304 Method. 305 When typing a pattern for a search command and 'imsearch' is 306 not -1, VAL is the value of 'imsearch', otherwise VAL is the 307 value of 'iminsert'. 308 When language mappings are defined: 309 - If VAL is 1 (langmap mappings used) it becomes 0 (no langmap 310 mappings used). 311 - If VAL was not 1 it becomes 1, thus langmap mappings are 312 enabled. 313 When no language mappings are defined: 314 - If VAL is 2 (Input Method is used) it becomes 0 (no input 315 method used) 316 - If VAL has another value it becomes 2, thus the Input Method 317 is enabled. 318 These language mappings are normally used to type characters 319 that are different from what the keyboard produces. The 320 'keymap' option can be used to install a whole number of them. 321 When entering a command line, langmap mappings are switched 322 off, since you are expected to type a command. After 323 switching it on with CTRL-^, the new state is not used again 324 for the next command or Search pattern. 325 326 *c_CTRL-]* 327CTRL-] Trigger abbreviation, without inserting a character. 328 329For Emacs-style editing on the command-line see |emacs-keys|. 330 331The <Up> and <Down> keys take the current command-line as a search string. 332The beginning of the next/previous command-lines are compared with this 333string. The first line that matches is the new command-line. When typing 334these two keys repeatedly, the same string is used again. For example, this 335can be used to find the previous substitute command: Type ":s" and then <Up>. 336The same could be done by typing <S-Up> a number of times until the desired 337command-line is shown. (Note: the shifted arrow keys do not work on all 338terminals) 339 340 *:his* *:history* 341:his[tory] Print the history of last entered commands. 342 {not available when compiled without the |+cmdline_hist| 343 feature} 344 345:his[tory] [{name}] [{first}][, [{last}]] 346 List the contents of history {name} which can be: 347 c[md] or : command-line history 348 s[earch] or / or ? search string history 349 e[xpr] or = expression register history 350 i[nput] or @ input line history 351 d[ebug] or > debug command history 352 a[ll] all of the above 353 354 If the numbers {first} and/or {last} are given, the respective 355 range of entries from a history is listed. These numbers can 356 be specified in the following form: 357 *:history-indexing* 358 A positive number represents the absolute index of an entry 359 as it is given in the first column of a :history listing. 360 This number remains fixed even if other entries are deleted. 361 362 A negative number means the relative position of an entry, 363 counted from the newest entry (which has index -1) backwards. 364 365 Examples: 366 List entries 6 to 12 from the search history: > 367 :history / 6,12 368< 369 List the penultimate entry from all histories: > 370 :history all -2 371< 372 List the most recent two entries from all histories: > 373 :history all -2, 374 375:keepp[atterns] {command} *:keepp* *:keeppatterns* 376 Execute {command}, without adding anything to the search 377 history 378 379============================================================================== 3802. Command-line completion *cmdline-completion* 381 382When editing the command-line, a few commands can be used to complete the 383word before the cursor. This is available for: 384 385- Command names: At the start of the command-line. 386- Tags: Only after the ":tag" command. 387- File names: Only after a command that accepts a file name or a setting for 388 an option that can be set to a file name. This is called file name 389 completion. 390- Shell command names: After ":!cmd", ":r !cmd" and ":w !cmd". $PATH is used. 391- Options: Only after the ":set" command. 392- Mappings: Only after a ":map" or similar command. 393- Variable and function names: Only after a ":if", ":call" or similar command. 394 395The number of help item matches is limited (currently to 300) to avoid a long 396delay when there are very many matches. 397 398These are the commands that can be used: 399 400 *c_CTRL-D* 401CTRL-D List names that match the pattern in front of the cursor. 402 When showing file names, directories are highlighted (see 403 'highlight' option). Names where 'suffixes' matches are moved 404 to the end. 405 The 'wildoptions' option can be set to "tagfile" to list the 406 file of matching tags. 407 *c_CTRL-I* *c_wildchar* *c_<Tab>* 408'wildchar' option 409 A match is done on the pattern in front of the cursor. The 410 match (if there are several, the first match) is inserted 411 in place of the pattern. (Note: does not work inside a 412 macro, because <Tab> or <Esc> are mostly used as 'wildchar', 413 and these have a special meaning in some macros.) When typed 414 again and there were multiple matches, the next 415 match is inserted. After the last match, the first is used 416 again (wrap around). 417 The behavior can be changed with the 'wildmode' option. 418 *c_<S-Tab>* 419<S-Tab> Like 'wildchar' or <Tab>, but begin with the last match and 420 then go to the previous match. 421 <S-Tab> does not work everywhere. 422 *c_CTRL-N* 423CTRL-N After using 'wildchar' which got multiple matches, go to next 424 match. Otherwise recall more recent command-line from history. 425 *c_CTRL-P* 426CTRL-P After using 'wildchar' which got multiple matches, go to 427 previous match. Otherwise recall older command-line from 428 history. 429 *c_CTRL-A* 430CTRL-A All names that match the pattern in front of the cursor are 431 inserted. 432 *c_CTRL-L* 433CTRL-L A match is done on the pattern in front of the cursor. If 434 there is one match, it is inserted in place of the pattern. 435 If there are multiple matches the longest common part is 436 inserted in place of the pattern. If the result is shorter 437 than the pattern, no completion is done. 438 */_CTRL-L* 439 When 'incsearch' is set, entering a search pattern for "/" or 440 "?" and the current match is displayed then CTRL-L will add 441 one character from the end of the current match. If 442 'ignorecase' and 'smartcase' are set and the command line has 443 no uppercase characters, the added character is converted to 444 lowercase. 445 *c_CTRL-G* */_CTRL-G* 446CTRL-G When 'incsearch' is set, entering a search pattern for "/" or 447 "?" and the current match is displayed then CTRL-G will move 448 to the next match (does not take |search-offset| into account) 449 Use CTRL-T to move to the previous match. Hint: on a regular 450 keyboard T is above G. 451 *c_CTRL-T* */_CTRL-T* 452CTRL-T When 'incsearch' is set, entering a search pattern for "/" or 453 "?" and the current match is displayed then CTRL-T will move 454 to the previous match (does not take |search-offset| into 455 account). 456 Use CTRL-G to move to the next match. Hint: on a regular 457 keyboard T is above G. 458 459The 'wildchar' option defaults to <Tab> (CTRL-E when in Vi compatible mode; in 460a previous version <Esc> was used). In the pattern standard wildcards '*' and 461'?' are accepted when matching file names. '*' matches any string, '?' 462matches exactly one character. 463 464When repeating 'wildchar' or CTRL-N you cycle through the matches, eventually 465ending up back to what was typed. If the first match is not what you wanted, 466you can use <S-Tab> or CTRL-P to go straight back to what you typed. 467 468The 'wildignorecase' option can be set to ignore case in filenames. 469 470The 'wildmenu' option can be set to show the matches just above the command 471line. 472 473If you like tcsh's autolist completion, you can use this mapping: 474 :cnoremap X <C-L><C-D> 475(Where X is the command key to use, <C-L> is CTRL-L and <C-D> is CTRL-D) 476This will find the longest match and then list all matching files. 477 478If you like tcsh's autolist completion, you can use the 'wildmode' option to 479emulate it. For example, this mimics autolist=ambiguous: 480 :set wildmode=longest,list 481This will find the longest match with the first 'wildchar', then list all 482matching files with the next. 483 484 *complete-script-local-functions* 485When completing user function names, prepend "s:" to find script-local 486functions. 487 488 *suffixes* 489For file name completion you can use the 'suffixes' option to set a priority 490between files with almost the same name. If there are multiple matches, 491those files with an extension that is in the 'suffixes' option are ignored. 492The default is ".bak,~,.o,.h,.info,.swp,.obj", which means that files ending 493in ".bak", "~", ".o", ".h", ".info", ".swp" and ".obj" are sometimes ignored. 494 495An empty entry, two consecutive commas, match a file name that does not 496contain a ".", thus has no suffix. This is useful to ignore "prog" and prefer 497"prog.c". 498 499Examples: 500 501 pattern: files: match: ~ 502 test* test.c test.h test.o test.c 503 test* test.h test.o test.h and test.o 504 test* test.i test.h test.c test.i and test.c 505 506It is impossible to ignore suffixes with two dots. 507 508If there is more than one matching file (after ignoring the ones matching 509the 'suffixes' option) the first file name is inserted. You can see that 510there is only one match when you type 'wildchar' twice and the completed 511match stays the same. You can get to the other matches by entering 512'wildchar', CTRL-N or CTRL-P. All files are included, also the ones with 513extensions matching the 'suffixes' option. 514 515To completely ignore files with some extension use 'wildignore'. 516 517To match only files that end at the end of the typed text append a "$". For 518example, to match only files that end in ".c": > 519 :e *.c$ 520This will not match a file ending in ".cpp". Without the "$" it does match. 521 522The old value of an option can be obtained by hitting 'wildchar' just after 523the '='. For example, typing 'wildchar' after ":set dir=" will insert the 524current value of 'dir'. This overrules file name completion for the options 525that take a file name. 526 527If you would like using <S-Tab> for CTRL-P in an xterm, put this command in 528your .cshrc: > 529 xmodmap -e "keysym Tab = Tab Find" 530And this in your .vimrc: > 531 :cmap <Esc>[1~ <C-P> 532 533============================================================================== 5343. Ex command-lines *cmdline-lines* 535 536The Ex commands have a few specialties: 537 538 *:quote* *:comment* 539'"' at the start of a line causes the whole line to be ignored. '"' 540after a command causes the rest of the line to be ignored. This can be used 541to add comments. Example: > 542 :set ai "set 'autoindent' option 543It is not possible to add a comment to a shell command ":!cmd" or to the 544":map" command and a few others (mainly commands that expect expressions) 545that see the '"' as part of their argument: 546 547 :argdo 548 :autocmd 549 :bufdo 550 :cexpr (and the like) 551 :cdo (and the like) 552 :command 553 :cscope (and the like) 554 :debug 555 :display 556 :echo (and the like) 557 :elseif 558 :execute 559 :folddoopen 560 :folddoclosed 561 :for 562 :grep (and the like) 563 :help (and the like) 564 :if 565 :let 566 :make 567 :map (and the like including :abbrev commands) 568 :menu (and the like) 569 :mkspell 570 :normal 571 :ownsyntax 572 :popup 573 :promptfind (and the like) 574 :registers 575 :return 576 :sort 577 :syntax 578 :tabdo 579 :tearoff 580 :vimgrep (and the like) 581 :while 582 :windo 583 584 *:bar* *:\bar* 585'|' can be used to separate commands, so you can give multiple commands in one 586line. If you want to use '|' in an argument, precede it with '\'. 587 588These commands see the '|' as their argument, and can therefore not be 589followed by another Vim command: 590 :argdo 591 :autocmd 592 :bufdo 593 :cdo 594 :cfdo 595 :command 596 :cscope 597 :debug 598 :eval 599 :folddoopen 600 :folddoclosed 601 :function 602 :global 603 :help 604 :helpfind 605 :helpgrep 606 :lcscope 607 :ldo 608 :lfdo 609 :lhelpgrep 610 :make 611 :normal 612 :perl 613 :perldo 614 :promptfind 615 :promptrepl 616 :pyfile 617 :python 618 :registers 619 :read ! 620 :scscope 621 :sign 622 :tcl 623 :tcldo 624 :tclfile 625 :terminal 626 :vglobal 627 :windo 628 :write ! 629 :[range]! 630 a user defined command without the "-bar" argument |:command| 631 632Note that this is confusing (inherited from Vi): With ":g" the '|' is included 633in the command, with ":s" it is not. 634 635To be able to use another command anyway, use the ":execute" command. 636Example (append the output of "ls" and jump to the first line): > 637 :execute 'r !ls' | '[ 638 639There is one exception: When the 'b' flag is present in 'cpoptions', with the 640":map" and ":abbr" commands and friends CTRL-V needs to be used instead of 641'\'. You can also use "<Bar>" instead. See also |map_bar|. 642 643Examples: > 644 :!ls | wc view the output of two commands 645 :r !ls | wc insert the same output in the text 646 :%g/foo/p|> moves all matching lines one shiftwidth 647 :%s/foo/bar/|> moves one line one shiftwidth 648 :map q 10^V| map "q" to "10|" 649 :map q 10\| map \ l map "q" to "10\" and map "\" to "l" 650 (when 'b' is present in 'cpoptions') 651 652You can also use <NL> to separate commands in the same way as with '|'. To 653insert a <NL> use CTRL-V CTRL-J. "^@" will be shown. Using '|' is the 654preferred method. But for external commands a <NL> must be used, because a 655'|' is included in the external command. To avoid the special meaning of <NL> 656it must be preceded with a backslash. Example: > 657 :r !date<NL>-join 658This reads the current date into the file and joins it with the previous line. 659 660Note that when the command before the '|' generates an error, the following 661commands will not be executed. 662 663 664Because of Vi compatibility the following strange commands are supported: > 665 :| print current line (like ":p") 666 :3| print line 3 (like ":3p") 667 :3 goto line 3 668 669A colon is allowed between the range and the command name. It is ignored 670(this is Vi compatible). For example: > 671 :1,$:s/pat/string 672 673When the character '%' or '#' is used where a file name is expected, they are 674expanded to the current and alternate file name (see the chapter "editing 675files" |:_%| |:_#|). 676 677Embedded spaces in file names are allowed on the Amiga if one file name is 678expected as argument. Trailing spaces will be ignored, unless escaped with a 679backslash or CTRL-V. Note that the ":next" command uses spaces to separate 680file names. Escape the spaces to include them in a file name. Example: > 681 :next foo\ bar goes\ to school\ 682starts editing the three files "foo bar", "goes to" and "school ". 683 684When you want to use the special characters '"' or '|' in a command, or want 685to use '%' or '#' in a file name, precede them with a backslash. The 686backslash is not required in a range and in the ":substitute" command. 687See also |`=|. 688 689 *:_!* 690The '!' (bang) character after an Ex command makes the command behave in a 691different way. The '!' should be placed immediately after the command, without 692any blanks in between. If you insert blanks the '!' will be seen as an 693argument for the command, which has a different meaning. For example: 694 :w! name write the current buffer to file "name", overwriting 695 any existing file 696 :w !name send the current buffer as standard input to command 697 "name" 698 699============================================================================== 7004. Ex command-line ranges *cmdline-ranges* *[range]* *E16* 701 702Some Ex commands accept a line range in front of them. This is noted as 703[range]. It consists of one or more line specifiers, separated with ',' or 704';'. 705 706The basics are explained in section |10.3| of the user manual. 707 708 *:,* *:;* 709When separated with ';' the cursor position will be set to that line 710before interpreting the next line specifier. This doesn't happen for ','. 711Examples: > 712 4,/this line/ 713< from line 4 till match with "this line" after the cursor line. > 714 5;/that line/ 715< from line 5 till match with "that line" after line 5. 716 717The default line specifier for most commands is the cursor position, but the 718commands ":write" and ":global" have the whole file (1,$) as default. 719 720If more line specifiers are given than required for the command, the first 721one(s) will be ignored. 722 723Line numbers may be specified with: *:range* *{address}* 724 {number} an absolute line number 725 . the current line *:.* 726 $ the last line in the file *:$* 727 % equal to 1,$ (the entire file) *:%* 728 't position of mark t (lowercase) *:'* 729 'T position of mark T (uppercase); when the mark is in 730 another file it cannot be used in a range 731 /{pattern}[/] the next line where {pattern} matches *:/* 732 ?{pattern}[?] the previous line where {pattern} matches *:?* 733 \/ the next line where the previously used search 734 pattern matches 735 \? the previous line where the previously used search 736 pattern matches 737 \& the next line where the previously used substitute 738 pattern matches 739 740Each may be followed (several times) by '+' or '-' and an optional number. 741This number is added or subtracted from the preceding line number. If the 742number is omitted, 1 is used. 743 744The "/" and "?" after {pattern} are required to separate the pattern from 745anything that follows. 746 747The "/" and "?" may be preceded with another address. The search starts from 748there. The difference from using ';' is that the cursor isn't moved. 749Examples: > 750 /pat1//pat2/ Find line containing "pat2" after line containing 751 "pat1", without moving the cursor. 752 7;/pat2/ Find line containing "pat2", after line 7, leaving 753 the cursor in line 7. 754 755The {number} must be between 0 and the number of lines in the file. When 756using a 0 (zero) this is interpreted as a 1 by most commands. Commands that 757use it as a count do use it as a zero (|:tag|, |:pop|, etc). Some commands 758interpret the zero as "before the first line" (|:read|, search pattern, etc). 759 760Examples: > 761 .+3 three lines below the cursor 762 /that/+1 the line below the next line containing "that" 763 .,$ from current line until end of file 764 0;/that the first line containing "that", also matches in the 765 first line. 766 1;/that the first line after line 1 containing "that" 767 768Some commands allow for a count after the command. This count is used as the 769number of lines to be used, starting with the line given in the last line 770specifier (the default is the cursor line). The commands that accept a count 771are the ones that use a range but do not have a file name argument (because 772a file name can also be a number). 773 774Examples: > 775 :s/x/X/g 5 substitute 'x' by 'X' in the current line and four 776 following lines 777 :23d 4 delete lines 23, 24, 25 and 26 778 779 780Folds and Range 781 782When folds are active the line numbers are rounded off to include the whole 783closed fold. See |fold-behavior|. 784 785 786Reverse Range *E493* 787 788A range should have the lower line number first. If this is not the case, Vim 789will ask you if it should swap the line numbers. 790 Backwards range given, OK to swap ~ 791This is not done within the global command ":g". 792 793You can use ":silent" before a command to avoid the question, the range will 794always be swapped then. 795 796 797Count and Range *N:* 798 799When giving a count before entering ":", this is translated into: 800 :.,.+(count - 1) 801In words: The 'count' lines at and after the cursor. Example: To delete 802three lines: > 803 3:d<CR> is translated into: .,.+2d<CR> 804< 805 806Visual Mode and Range 807 *v_:* 808{Visual}: Starts a command-line with the Visual selected lines as a 809 range. The code `:'<,'>` is used for this range, which makes 810 it possible to select a similar line from the command-line 811 history for repeating a command on different Visually selected 812 lines. 813 814:* *:star* *:star-visual-range* 815 When Visual mode was already ended, a short way to use the 816 Visual area for a range is `:*`. This requires that "*" does 817 not appear in 'cpo', see |cpo-star|. Otherwise you will have 818 to type `:'<,'>` 819 For when "*" is in 'cpo' see |:star-compatible|. 820 821============================================================================== 8225. Ex command-line flags *ex-flags* 823 824These flags are supported by a selection of Ex commands. They print the line 825that the cursor ends up after executing the command: 826 827 l output like for |:list| 828 # add line number 829 p output like for |:print| 830 831The flags can be combined, thus "l#" uses both a line number and |:list| style 832output. 833 834============================================================================== 8356. Ex special characters *cmdline-special* 836 837Note: These are special characters in the executed command line. If you want 838to insert special things while typing you can use the CTRL-R command. For 839example, "%" stands for the current file name, while CTRL-R % inserts the 840current file name right away. See |c_CTRL-R|. 841 842Note: If you want to avoid the effects of special characters in a Vim script 843you may want to use |fnameescape()|. Also see |`=|. 844 845 846In Ex commands, at places where a file name can be used, the following 847characters have a special meaning. These can also be used in the expression 848function |expand()|. 849 % Is replaced with the current file name. *:_%* *c_%* 850 # Is replaced with the alternate file name. *:_#* *c_#* 851 This is remembered for every window. 852 #n (where n is a number) is replaced with *:_#0* *:_#n* 853 the file name of buffer n. "#0" is the same as "#". *c_#n* 854 ## Is replaced with all names in the argument list *:_##* *c_##* 855 concatenated, separated by spaces. Each space in a name 856 is preceded with a backslash. 857 #<n (where n is a number > 0) is replaced with old *:_#<* *c_#<* 858 file name n. See |:oldfiles| or |v:oldfiles| to get the 859 number. *E809* 860 {only when compiled with the |+eval| and |+viminfo| features} 861In |Vim9-script| # is used to start a comment, use %% for the alternate file 862name: 863 % Is replaced with the current file name. 864 %% Is replaced with the alternate file name. *:_%%* *c_%%* 865 %%n (where n is a number) is replaced with *:_%%0* *:_%%n* 866 the file name of buffer n. "%%0" is the same as "%%". *c_%%n* 867 %%% Is replaced with all names in the argument *:_%%%* *c_%%%#* 868 list concatenated, separated by spaces. 869 %%<n (where n is a number > 0) is replaced with old *:_%%<* *c_%%<* 870 file name n. 871 872Note that these, except "#<n", give the file name as it was typed. If an 873absolute path is needed (when using the file name from a different directory), 874you need to add ":p". See |filename-modifiers|. 875 876The "#<n" item returns an absolute path, but it will start with "~/" for files 877below your home directory. 878 879Note that backslashes are inserted before spaces, so that the command will 880correctly interpret the file name. But this doesn't happen for shell 881commands. For those you probably have to use quotes (this fails for files 882that contain a quote and wildcards): > 883 :!ls "%" 884 :r !spell "%" 885 886To avoid the special meaning of '%' and '#' insert a backslash before it. 887Detail: The special meaning is always escaped when there is a backslash before 888it, no matter how many backslashes. 889 you type: result ~ 890 # alternate.file 891 \# # 892 \\# \# 893Also see |`=|. 894 895 *E499* *E500* 896Note: these are typed literally, they are not special keys! 897 *:<cword>* *<cword>* 898 <cword> is replaced with the word under the cursor (like |star|) 899 *:<cWORD>* *<cWORD>* 900 <cWORD> is replaced with the WORD under the cursor (see |WORD|) 901 *:<cexpr>* *<cexpr>* 902 <cexpr> is replaced with the word under the cursor, including more 903 to form a C expression. E.g., when the cursor is on "arg" 904 of "ptr->arg" then the result is "ptr->arg"; when the 905 cursor is on "]" of "list[idx]" then the result is 906 "list[idx]". This is used for |v:beval_text|. 907 *:<cfile>* *<cfile>* 908 <cfile> is replaced with the path name under the cursor (like what 909 |gf| uses) 910 *:<afile>* *<afile>* 911 <afile> When executing autocommands, is replaced with the file name 912 of the buffer being manipulated, or the file for a read or 913 write. *E495* 914 *:<abuf>* *<abuf>* 915 <abuf> When executing autocommands, is replaced with the currently 916 effective buffer number (for ":r file" and ":so file" it is 917 the current buffer, the file being read/sourced is not in a 918 buffer). *E496* 919 *:<amatch>* *<amatch>* 920 <amatch> When executing autocommands, is replaced with the match for 921 which this autocommand was executed. *E497* 922 It differs from <afile> only when the file name isn't used 923 to match with (for FileType, Syntax and SpellFileMissing 924 events). 925 *:<sfile>* *<sfile>* 926 <sfile> When executing a ":source" command, is replaced with the 927 file name of the sourced file. *E498* 928 When executing a function, is replaced with the call stack, 929 as with <stack> (this is for backwards compatibility, using 930 <stack> is preferred). 931 Note that filename-modifiers are useless when <sfile> is 932 not used inside a script. 933 *:<stack>* *<stack>* 934 <stack> is replaced with the call stack, using 935 "function {function-name}[{lnum}]" for a function line 936 and "script {file-name}[{lnum}]" for a script line, and 937 ".." in between items. E.g.: 938 "function {function-name1}[{lnum}]..{function-name2}[{lnum}]" 939 *:<slnum>* *<slnum>* 940 <slnum> When executing a ":source" command, is replaced with the 941 line number. *E842* 942 When executing a function it's the line number relative to 943 the start of the function. 944 *:<sflnum>* *<sflnum>* 945 <sflnum> When executing a script, is replaced with the line number. 946 It differs from <slnum> in that <sflnum> is replaced with 947 the script line number in any situation. *E961* 948 *:<client>* *<client>* 949 <client> is replaced with the {clinetid} of the last received 950 message in |server2client()| 951 952 *filename-modifiers* 953*:_%:* *::8* *::p* *::.* *::~* *::h* *::t* *::r* *::e* *::s* *::gs* *::S* 954 *%:8* *%:p* *%:.* *%:~* *%:h* *%:t* *%:r* *%:e* *%:s* *%:gs* *%:S* 955The file name modifiers can be used after "%", "#", "#n", "<cfile>", "<sfile>", 956"<afile>" or "<abuf>". They are also used with the |fnamemodify()| function. 957 958These modifiers can be given, in this order: 959 :p Make file name a full path. Must be the first modifier. Also 960 changes "~/" (and "~user/" for Unix and VMS) to the path for 961 the home directory. If the name is a directory a path 962 separator is added at the end. For a file name that does not 963 exist and does not have an absolute path the result is 964 unpredictable. On MS-Windows an 8.3 filename is expanded to 965 the long name. 966 :8 Converts the path to 8.3 short format (currently only on 967 MS-Windows). Will act on as much of a path that is an 968 existing path. 969 :~ Reduce file name to be relative to the home directory, if 970 possible. File name is unmodified if it is not below the home 971 directory. 972 :. Reduce file name to be relative to current directory, if 973 possible. File name is unmodified if it is not below the 974 current directory. 975 For maximum shortness, use ":~:.". 976 :h Head of the file name (the last component and any separators 977 removed). Cannot be used with :e, :r or :t. 978 Can be repeated to remove several components at the end. 979 When the file name ends in a path separator, only the path 980 separator is removed. Thus ":p:h" on a directory name results 981 on the directory name itself (without trailing slash). 982 When the file name is an absolute path (starts with "/" for 983 Unix; "x:\" for Win32; "drive:" for Amiga), that part is not 984 removed. When there is no head (path is relative to current 985 directory) the result is empty. 986 :t Tail of the file name (last component of the name). Must 987 precede any :r or :e. 988 :r Root of the file name (the last extension removed). When 989 there is only an extension (file name that starts with '.', 990 e.g., ".vimrc"), it is not removed. Can be repeated to remove 991 several extensions (last one first). 992 :e Extension of the file name. Only makes sense when used alone. 993 When there is no extension the result is empty. 994 When there is only an extension (file name that starts with 995 '.'), the result is empty. Can be repeated to include more 996 extensions. If there are not enough extensions (but at least 997 one) as much as possible are included. 998 :s?pat?sub? 999 Substitute the first occurrence of "pat" with "sub". This 1000 works like the |:s| command. "pat" is a regular expression. 1001 Any character can be used for '?', but it must not occur in 1002 "pat" or "sub". 1003 After this, the previous modifiers can be used again. For 1004 example ":p", to make a full path after the substitution. 1005 :gs?pat?sub? 1006 Substitute all occurrences of "pat" with "sub". Otherwise 1007 this works like ":s". 1008 :S Escape special characters for use with a shell command (see 1009 |shellescape()|). Must be the last one. Examples: > 1010 :!dir <cfile>:S 1011 :call system('chmod +w -- ' . expand('%:S')) 1012 1013Examples, when the file name is "src/version.c", current dir 1014"/home/mool/vim": > 1015 :p /home/mool/vim/src/version.c 1016 :p:. src/version.c 1017 :p:~ ~/vim/src/version.c 1018 :h src 1019 :p:h /home/mool/vim/src 1020 :p:h:h /home/mool/vim 1021 :t version.c 1022 :p:t version.c 1023 :r src/version 1024 :p:r /home/mool/vim/src/version 1025 :t:r version 1026 :e c 1027 :s?version?main? src/main.c 1028 :s?version?main?:p /home/mool/vim/src/main.c 1029 :p:gs?/?\\? \home\mool\vim\src\version.c 1030 1031Examples, when the file name is "src/version.c.gz": > 1032 :p /home/mool/vim/src/version.c.gz 1033 :e gz 1034 :e:e c.gz 1035 :e:e:e c.gz 1036 :e:e:r c 1037 :r src/version.c 1038 :r:e c 1039 :r:r src/version 1040 :r:r:r src/version 1041< 1042 *extension-removal* *:_%<* 1043If a "<" is appended to "%", "#", "#n" or "CTRL-V p" the extension of the file 1044name is removed (everything after and including the last '.' in the file 1045name). This is included for backwards compatibility with version 3.0, the 1046":r" form is preferred. Examples: > 1047 1048 % current file name 1049 %< current file name without extension 1050 # alternate file name for current window 1051 #< idem, without extension 1052 #31 alternate file number 31 1053 #31< idem, without extension 1054 <cword> word under the cursor 1055 <cWORD> WORD under the cursor (see |WORD|) 1056 <cfile> path name under the cursor 1057 <cfile>< idem, without extension 1058 1059Note: Where a file name is expected wildcards expansion is done. On Unix the 1060shell is used for this, unless it can be done internally (for speed). 1061Unless in |restricted-mode|, backticks work also, like in > 1062 :n `echo *.c` 1063But expansion is only done if there are any wildcards before expanding the 1064'%', '#', etc.. This avoids expanding wildcards inside a file name. If you 1065want to expand the result of <cfile>, add a wildcard character to it. 1066Examples: (alternate file name is "?readme?") 1067 command expands to ~ 1068 :e # :e ?readme? 1069 :e `ls #` :e {files matching "?readme?"} 1070 :e #.* :e {files matching "?readme?.*"} 1071 :cd <cfile> :cd {file name under cursor} 1072 :cd <cfile>* :cd {file name under cursor plus "*" and then expanded} 1073Also see |`=|. 1074 1075When the expanded argument contains a "!" and it is used for a shell command 1076(":!cmd", ":r !cmd" or ":w !cmd"), the "!" is escaped with a backslash to 1077avoid it being expanded into a previously used command. When the 'shell' 1078option contains "sh", this is done twice, to avoid the shell trying to expand 1079the "!". 1080 1081 *filename-backslash* 1082For filesystems that use a backslash as directory separator (MS-Windows), it's 1083a bit difficult to recognize a backslash that is used to escape the special 1084meaning of the next character. The general rule is: If the backslash is 1085followed by a normal file name character, it does not have a special meaning. 1086Therefore "\file\foo" is a valid file name, you don't have to type the 1087backslash twice. 1088 1089An exception is the '$' sign. It is a valid character in a file name. But 1090to avoid a file name like "$home" to be interpreted as an environment variable, 1091it needs to be preceded by a backslash. Therefore you need to use "/\$home" 1092for the file "$home" in the root directory. A few examples: 1093 1094 FILE NAME INTERPRETED AS ~ 1095 $home expanded to value of environment var $home 1096 \$home file "$home" in current directory 1097 /\$home file "$home" in root directory 1098 \\$home file "\\", followed by expanded $home 1099 1100Also see |`=|. 1101 1102============================================================================== 11037. Command-line window *cmdline-window* *cmdwin* 1104 *command-line-window* 1105In the command-line window the command line can be edited just like editing 1106text in any window. It is a special kind of window, because you cannot leave 1107it in a normal way. 1108{not available when compiled without the |+cmdwin| feature} 1109 1110 1111OPEN *c_CTRL-F* *q:* *q/* *q?* 1112 1113There are two ways to open the command-line window: 11141. From Command-line mode, use the key specified with the 'cedit' option. 1115 The default is CTRL-F when 'compatible' is not set. 11162. From Normal mode, use the "q:", "q/" or "q?" command. 1117 This starts editing an Ex command-line ("q:") or search string ("q/" or 1118 "q?"). Note that this is not possible while recording is in progress (the 1119 "q" stops recording then). 1120 1121When the window opens it is filled with the command-line history. The last 1122line contains the command as typed so far. The left column will show a 1123character that indicates the type of command-line being edited, see 1124|cmdwin-char|. 1125 1126Vim will be in Normal mode when the editor is opened, except when 'insertmode' 1127is set. 1128 1129The height of the window is specified with 'cmdwinheight' (or smaller if there 1130is no room). The window is always full width and is positioned just above the 1131command-line. 1132 1133 1134EDIT 1135 1136You can now use commands to move around and edit the text in the window. Both 1137in Normal mode and Insert mode. 1138 1139It is possible to use ":", "/" and other commands that use the command-line, 1140but it's not possible to open another command-line window then. There is no 1141nesting. 1142 *E11* *E1188* 1143The command-line window is not a normal window. It is not possible to move to 1144another window or edit another buffer. All commands that would do this are 1145disabled in the command-line window. Of course it _is_ possible to execute 1146any command that you entered in the command-line window. Other text edits are 1147discarded when closing the window. 1148 1149 1150CLOSE *E199* 1151 1152There are several ways to leave the command-line window: 1153 1154<CR> Execute the command-line under the cursor. Works both in 1155 Insert and in Normal mode. 1156CTRL-C Continue in Command-line mode. The command-line under the 1157 cursor is used as the command-line. Works both in Insert and 1158 in Normal mode. There is no redraw, thus the window will 1159 remain visible. 1160:quit Discard the command line and go back to Normal mode. 1161 ":close", CTRL-W c, ":exit", ":xit" and CTRL-\ CTRL-N also 1162 work. 1163:qall Quit Vim, unless there are changes in some buffer. 1164:qall! Quit Vim, discarding changes to any buffer. 1165 1166Once the command-line window is closed the old window sizes are restored. The 1167executed command applies to the window and buffer where the command-line was 1168started from. This works as if the command-line window was not there, except 1169that there will be an extra screen redraw. 1170The buffer used for the command-line window is deleted. Any changes to lines 1171other than the one that is executed with <CR> are lost. 1172 1173If you would like to execute the command under the cursor and then have the 1174command-line window open again, you may find this mapping useful: > 1175 1176 :autocmd CmdwinEnter * map <buffer> <F5> <CR>q: 1177 1178 1179VARIOUS 1180 1181The command-line window cannot be used: 1182- when there already is a command-line window (no nesting) 1183- for entering an encryption key or when using inputsecret() 1184 1185Some options are set when the command-line window is opened: 1186'filetype' "vim", when editing an Ex command-line; this starts Vim syntax 1187 highlighting if it was enabled 1188'rightleft' off 1189'modifiable' on 1190'buftype' "nofile" 1191'swapfile' off 1192 1193It is allowed to write the buffer contents to a file. This is an easy way to 1194save the command-line history and read it back later. 1195 1196If the 'wildchar' option is set to <Tab>, and the command-line window is used 1197for an Ex command, then two mappings will be added to use <Tab> for completion 1198in the command-line window, like this: > 1199 :imap <buffer> <Tab> <C-X><C-V> 1200 :nmap <buffer> <Tab> a<C-X><C-V> 1201Note that hitting <Tab> in Normal mode will do completion on the next 1202character. That way it works at the end of the line. 1203If you don't want these mappings, disable them with: > 1204 au CmdwinEnter [:>] iunmap <Tab> 1205 au CmdwinEnter [:>] nunmap <Tab> 1206You could put these lines in your vimrc file. 1207 1208While in the command-line window you cannot use the mouse to put the cursor in 1209another window, or drag statuslines of other windows. You can drag the 1210statusline of the command-line window itself and the statusline above it. 1211Thus you can resize the command-line window, but not others. 1212 1213The |getcmdwintype()| function returns the type of the command-line being 1214edited as described in |cmdwin-char|. 1215 1216 1217AUTOCOMMANDS 1218 1219Two autocommand events are used: |CmdwinEnter| and |CmdwinLeave|. You can use 1220the Cmdwin events to do settings specifically for the command-line window. 1221Be careful not to cause side effects! 1222Example: > 1223 :au CmdwinEnter : let b:cpt_save = &cpt | set cpt=. 1224 :au CmdwinLeave : let &cpt = b:cpt_save 1225This sets 'complete' to use completion in the current window for |i_CTRL-N|. 1226Another example: > 1227 :au CmdwinEnter [/?] startinsert 1228This will make Vim start in Insert mode in the command-line window. 1229 1230 *cmdwin-char* 1231The character used for the pattern indicates the type of command-line: 1232 : normal Ex command 1233 > debug mode command |debug-mode| 1234 / forward search string 1235 ? backward search string 1236 = expression for "= |expr-register| 1237 @ string for |input()| 1238 - text for |:insert| or |:append| 1239 1240 vim:tw=78:ts=8:noet:ft=help:norl: 1241