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