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