1*change.txt* For Vim version 8.2. Last change: 2021 Jun 23 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7This file describes commands that delete or change text. In this context, 8changing text means deleting the text and replacing it with other text using 9one command. You can undo all of these commands. You can repeat the non-Ex 10commands with the "." command. 11 121. Deleting text |deleting| 132. Delete and insert |delete-insert| 143. Simple changes |simple-change| *changing* 154. Complex changes |complex-change| 16 4.1 Filter commands |filter| 17 4.2 Substitute |:substitute| 18 4.3 Search and replace |search-replace| 19 4.4 Changing tabs |change-tabs| 205. Copying and moving text |copy-move| 216. Formatting text |formatting| 227. Sorting text |sorting| 23 24For inserting text see |insert.txt|. 25 26============================================================================== 271. Deleting text *deleting* *E470* 28 29["x]<Del> or *<Del>* *x* *dl* 30["x]x Delete [count] characters under and after the cursor 31 [into register x] (not |linewise|). Does the same as 32 "dl". 33 The <Del> key does not take a [count]. Instead, it 34 deletes the last character of the count. 35 See |:fixdel| if the <Del> key does not do what you 36 want. See |'whichwrap'| for deleting a line break 37 (join lines). 38 39 *X* *dh* 40["x]X Delete [count] characters before the cursor [into 41 register x] (not |linewise|). Does the same as "dh". 42 Also see |'whichwrap'|. 43 44 *d* 45["x]d{motion} Delete text that {motion} moves over [into register 46 x]. See below for exceptions. 47 48 *dd* 49["x]dd Delete [count] lines [into register x] |linewise|. 50 51 *D* 52["x]D Delete the characters under the cursor until the end 53 of the line and [count]-1 more lines [into register 54 x]; synonym for "d$". 55 (not |linewise|) 56 When the '#' flag is in 'cpoptions' the count is 57 ignored. 58 59{Visual}["x]x or *v_x* *v_d* *v_<Del>* 60{Visual}["x]d or 61{Visual}["x]<Del> Delete the highlighted text [into register x] (for 62 {Visual} see |Visual-mode|). 63 64{Visual}["x]CTRL-H or *v_CTRL-H* *v_<BS>* 65{Visual}["x]<BS> When in Select mode: Delete the highlighted text [into 66 register x]. 67 68{Visual}["x]X or *v_X* *v_D* *v_b_D* 69{Visual}["x]D Delete the highlighted lines [into register x] (for 70 {Visual} see |Visual-mode|). In Visual block mode, 71 "D" deletes the highlighted text plus all text until 72 the end of the line. 73 74 *:d* *:de* *:del* *:delete* *:dl* *:dp* 75:[range]d[elete] [x] Delete [range] lines (default: current line) [into 76 register x]. 77 Note these weird abbreviations: 78 :dl delete and list 79 :dell idem 80 :delel idem 81 :deletl idem 82 :deletel idem 83 :dp delete and print 84 :dep idem 85 :delp idem 86 :delep idem 87 :deletp idem 88 :deletep idem 89 90:[range]d[elete] [x] {count} 91 Delete {count} lines, starting with [range] 92 (default: current line |cmdline-ranges|) [into 93 register x]. 94 95These commands delete text. You can repeat them with the `.` command 96(except `:d`) and undo them. Use Visual mode to delete blocks of text. See 97|registers| for an explanation of registers. 98 99An exception for the d{motion} command: If the motion is not linewise, the 100start and end of the motion are not in the same line, and there are only 101blanks before the start and there are no non-blanks after the end of the 102motion, the delete becomes linewise. This means that the delete also removes 103the line of blanks that you might expect to remain. Use the |o_v| operator to 104force the motion to be characterwise. 105 106Trying to delete an empty region of text (e.g., "d0" in the first column) 107is an error when 'cpoptions' includes the 'E' flag. 108 109 *J* 110J Join [count] lines, with a minimum of two lines. 111 Remove the indent and insert up to two spaces (see 112 below). Fails when on the last line of the buffer. 113 If [count] is too big it is reduced to the number of 114 lines available. 115 116 *v_J* 117{Visual}J Join the highlighted lines, with a minimum of two 118 lines. Remove the indent and insert up to two spaces 119 (see below). 120 121 *gJ* 122gJ Join [count] lines, with a minimum of two lines. 123 Don't insert or remove any spaces. 124 125 *v_gJ* 126{Visual}gJ Join the highlighted lines, with a minimum of two 127 lines. Don't insert or remove any spaces. 128 129 *:j* *:join* 130:[range]j[oin][!] [flags] 131 Join [range] lines. Same as "J", except with [!] 132 the join does not insert or delete any spaces. 133 If a [range] has equal start and end values, this 134 command does nothing. The default behavior is to 135 join the current line with the line below it. 136 See |ex-flags| for [flags]. 137 138:[range]j[oin][!] {count} [flags] 139 Join {count} lines, starting with [range] (default: 140 current line |cmdline-ranges|). Same as "J", except 141 with [!] the join does not insert or delete any 142 spaces. 143 See |ex-flags| for [flags]. 144 145These commands delete the <EOL> between lines. This has the effect of joining 146multiple lines into one line. You can repeat these commands (except `:j`) and 147undo them. 148 149These commands, except "gJ", insert one space in place of the <EOL> unless 150there is trailing white space or the next line starts with a ')'. These 151commands, except "gJ", delete any leading white space on the next line. If 152the 'joinspaces' option is on, these commands insert two spaces after a '.', 153'!' or '?' (but if 'cpoptions' includes the 'j' flag, they insert two spaces 154only after a '.'). 155The 'B' and 'M' flags in 'formatoptions' change the behavior for inserting 156spaces before and after a multibyte character |fo-table|. 157 158The '[ mark is set at the end of the first line that was joined, '] at the end 159of the resulting line. 160 161 162============================================================================== 1632. Delete and insert *delete-insert* *replacing* 164 165 *R* 166R Enter Replace mode: Each character you type replaces 167 an existing character, starting with the character 168 under the cursor. Repeat the entered text [count]-1 169 times. See |Replace-mode| for more details. 170 171 *gR* 172gR Enter Virtual Replace mode: Each character you type 173 replaces existing characters in screen space. So a 174 <Tab> may replace several characters at once. 175 Repeat the entered text [count]-1 times. See 176 |Virtual-Replace-mode| for more details. 177 178 *c* 179["x]c{motion} Delete {motion} text [into register x] and start 180 insert. When 'cpoptions' includes the 'E' flag and 181 there is no text to delete (e.g., with "cTx" when the 182 cursor is just after an 'x'), an error occurs and 183 insert mode does not start (this is Vi compatible). 184 When 'cpoptions' does not include the 'E' flag, the 185 "c" command always starts insert mode, even if there 186 is no text to delete. 187 188 *cc* 189["x]cc Delete [count] lines [into register x] and start 190 insert |linewise|. If 'autoindent' is on, preserve 191 the indent of the first line. 192 193 *C* 194["x]C Delete from the cursor position to the end of the 195 line and [count]-1 more lines [into register x], and 196 start insert. Synonym for c$ (not |linewise|). 197 198 *s* 199["x]s Delete [count] characters [into register x] and start 200 insert (s stands for Substitute). Synonym for "cl" 201 (not |linewise|). 202 203 *S* 204["x]S Delete [count] lines [into register x] and start 205 insert. Synonym for "cc" |linewise|. 206 207{Visual}["x]c or *v_c* *v_s* 208{Visual}["x]s Delete the highlighted text [into register x] and 209 start insert (for {Visual} see |Visual-mode|). 210 211 *v_r* 212{Visual}r{char} Replace all selected characters by {char}. 213 214 *v_C* 215{Visual}["x]C Delete the highlighted lines [into register x] and 216 start insert. In Visual block mode it works 217 differently |v_b_C|. 218 *v_S* 219{Visual}["x]S Delete the highlighted lines [into register x] and 220 start insert (for {Visual} see |Visual-mode|). 221 *v_R* 222{Visual}["x]R Currently just like {Visual}["x]S. In a next version 223 it might work differently. 224 225Notes: 226- You can end Insert and Replace mode with <Esc>. 227- See the section "Insert and Replace mode" |mode-ins-repl| for the other 228 special characters in these modes. 229- The effect of [count] takes place after Vim exits Insert or Replace mode. 230- When the 'cpoptions' option contains '$' and the change is within one line, 231 Vim continues to show the text to be deleted and puts a '$' at the last 232 deleted character. 233 234See |registers| for an explanation of registers. 235 236Replace mode is just like Insert mode, except that every character you enter 237deletes one character. If you reach the end of a line, Vim appends any 238further characters (just like Insert mode). In Replace mode, the backspace 239key restores the original text (if there was any). (See section "Insert and 240Replace mode" |mode-ins-repl|). 241 242 *cw* *cW* 243Special case: When the cursor is in a word, "cw" and "cW" do not include the 244white space after a word, they only change up to the end of the word. This is 245because Vim interprets "cw" as change-word, and a word does not include the 246following white space. 247{Vi: "cw" when on a blank followed by other blanks changes only the first 248blank; this is probably a bug, because "dw" deletes all the blanks; use the 249'w' flag in 'cpoptions' to make it work like Vi anyway} 250 251If you prefer "cw" to include the space after a word, use this mapping: > 252 :map cw dwi 253Or use "caw" (see |aw|). 254 255 *:c* *:ch* *:change* 256:{range}c[hange][!] Replace lines of text with some different text. 257 Type a line containing only "." to stop replacing. 258 Without {range}, this command changes only the current 259 line. 260 Adding [!] toggles 'autoindent' for the time this 261 command is executed. 262 263============================================================================== 2643. Simple changes *simple-change* 265 266 *r* 267r{char} Replace the character under the cursor with {char}. 268 If {char} is a <CR> or <NL>, a line break replaces the 269 character. To replace with a real <CR>, use CTRL-V 270 <CR>. CTRL-V <NL> replaces with a <Nul>. 271 272 If {char} is CTRL-E or CTRL-Y the character from the 273 line below or above is used, just like with |i_CTRL-E| 274 and |i_CTRL-Y|. This also works with a count, thus 275 `10r<C-E>` copies 10 characters from the line below. 276 277 If you give a [count], Vim replaces [count] characters 278 with [count] {char}s. When {char} is a <CR> or <NL>, 279 however, Vim inserts only one <CR>: "5r<CR>" replaces 280 five characters with a single line break. 281 When {char} is a <CR> or <NL>, Vim performs 282 autoindenting. This works just like deleting the 283 characters that are replaced and then doing 284 "i<CR><Esc>". 285 {char} can be entered as a digraph |digraph-arg|. 286 |:lmap| mappings apply to {char}. The CTRL-^ command 287 in Insert mode can be used to switch this on/off 288 |i_CTRL-^|. See |utf-8-char-arg| about using 289 composing characters when 'encoding' is Unicode. 290 291 *gr* 292gr{char} Replace the virtual characters under the cursor with 293 {char}. This replaces in screen space, not file 294 space. See |gR| and |Virtual-Replace-mode| for more 295 details. As with |r| a count may be given. 296 {char} can be entered like with |r|. 297 298 *digraph-arg* 299The argument for Normal mode commands like |r| and |t| is a single character. 300When 'cpo' doesn't contain the 'D' flag, this character can also be entered 301like |digraphs|. First type CTRL-K and then the two digraph characters. 302{not available when compiled without the |+digraphs| feature} 303 304 *case* 305The following commands change the case of letters. The currently active 306|locale| is used. See |:language|. The LC_CTYPE value matters here. 307 308 *~* 309~ 'notildeop' option: Switch case of the character 310 under the cursor and move the cursor to the right. 311 If a [count] is given, do that many characters. 312 313~{motion} 'tildeop' option: switch case of {motion} text. 314 315 *g~* 316g~{motion} Switch case of {motion} text. 317 318g~g~ *g~g~* *g~~* 319g~~ Switch case of current line. 320 321 *v_~* 322{Visual}~ Switch case of highlighted text (for {Visual} see 323 |Visual-mode|). 324 325 *v_U* 326{Visual}U Make highlighted text uppercase (for {Visual} see 327 |Visual-mode|). 328 329 *gU* *uppercase* 330gU{motion} Make {motion} text uppercase. 331 Example: > 332 :map! <C-F> <Esc>gUiw`]a 333< This works in Insert mode: press CTRL-F to make the 334 word before the cursor uppercase. Handy to type 335 words in lowercase and then make them uppercase. 336 337 338gUgU *gUgU* *gUU* 339gUU Make current line uppercase. 340 341 *v_u* 342{Visual}u Make highlighted text lowercase (for {Visual} see 343 |Visual-mode|). 344 345 *gu* *lowercase* 346gu{motion} Make {motion} text lowercase. 347 348gugu *gugu* *guu* 349guu Make current line lowercase. 350 351 *g?* *rot13* 352g?{motion} Rot13 encode {motion} text. 353 354 *v_g?* 355{Visual}g? Rot13 encode the highlighted text (for {Visual} see 356 |Visual-mode|). 357 358g?g? *g?g?* *g??* 359g?? Rot13 encode current line. 360 361To turn one line into title caps, make every first letter of a word 362uppercase: > 363 :s/\v<(.)(\w*)/\u\1\L\2/g 364 365 366Adding and subtracting ~ 367 *CTRL-A* 368CTRL-A Add [count] to the number or alphabetic character at 369 or after the cursor. 370 371 *v_CTRL-A* 372{Visual}CTRL-A Add [count] to the number or alphabetic character in 373 the highlighted text. 374 375 *v_g_CTRL-A* 376{Visual}g CTRL-A Add [count] to the number or alphabetic character in 377 the highlighted text. If several lines are 378 highlighted, each one will be incremented by an 379 additional [count] (so effectively creating a 380 [count] incrementing sequence). 381 For Example, if you have this list of numbers: 382 1. ~ 383 1. ~ 384 1. ~ 385 1. ~ 386 Move to the second "1." and Visually select three 387 lines, pressing g CTRL-A results in: 388 1. ~ 389 2. ~ 390 3. ~ 391 4. ~ 392 393 *CTRL-X* 394CTRL-X Subtract [count] from the number or alphabetic 395 character at or after the cursor. 396 397 *v_CTRL-X* 398{Visual}CTRL-X Subtract [count] from the number or alphabetic 399 character in the highlighted text. 400 401 On MS-Windows, this is mapped to cut Visual text 402 |dos-standard-mappings|. If you want to disable the 403 mapping, use this: > 404 silent! vunmap <C-X> 405< 406 *v_g_CTRL-X* 407{Visual}g CTRL-X Subtract [count] from the number or alphabetic 408 character in the highlighted text. If several lines 409 are highlighted, each value will be decremented by an 410 additional [count] (so effectively creating a [count] 411 decrementing sequence). 412 413The CTRL-A and CTRL-X commands can work for: 414- signed and unsigned decimal numbers 415- unsigned binary, octal and hexadecimal numbers 416- alphabetic characters 417 418This depends on the 'nrformats' option: 419- When 'nrformats' includes "bin", Vim assumes numbers starting with '0b' or 420 '0B' are binary. 421- When 'nrformats' includes "octal", Vim considers numbers starting with a '0' 422 to be octal, unless the number includes a '8' or '9'. Other numbers are 423 decimal and may have a preceding minus sign. 424 If the cursor is on a number, the commands apply to that number; otherwise 425 Vim uses the number to the right of the cursor. 426- When 'nrformats' includes "hex", Vim assumes numbers starting with '0x' or 427 '0X' are hexadecimal. The case of the rightmost letter in the number 428 determines the case of the resulting hexadecimal number. If there is no 429 letter in the current number, Vim uses the previously detected case. 430- When 'nrformats' includes "alpha", Vim will change the alphabetic character 431 under or after the cursor. This is useful to make lists with an alphabetic 432 index. 433 434For decimals a leading negative sign is considered for incrementing/ 435decrementing, for binary, octal and hex values, it won't be considered. To 436ignore the sign Visually select the number before using CTRL-A or CTRL-X. 437 438For numbers with leading zeros (including all octal and hexadecimal numbers), 439Vim preserves the number of characters in the number when possible. CTRL-A on 440"0077" results in "0100", CTRL-X on "0x100" results in "0x0ff". 441There is one exception: When a number that starts with a zero is found not to 442be octal (it contains a '8' or '9'), but 'nrformats' does include "octal", 443leading zeros are removed to avoid that the result may be recognized as an 444octal number. 445 446Note that when 'nrformats' includes "octal", decimal numbers with leading 447zeros cause mistakes, because they can be confused with octal numbers. 448 449Note similarly, when 'nrformats' includes "bin", binary numbers with a leading 450'0x' or '0X' can be interpreted as hexadecimal rather than binary since '0b' 451are valid hexadecimal digits. 452 453The CTRL-A command is very useful in a macro. Example: Use the following 454steps to make a numbered list. 455 4561. Create the first list entry, make sure it starts with a number. 4572. qa - start recording into register 'a' 4583. Y - yank the entry 4594. p - put a copy of the entry below the first one 4605. CTRL-A - increment the number 4616. q - stop recording 4627. <count>@a - repeat the yank, put and increment <count> times 463 464 465SHIFTING LINES LEFT OR RIGHT *shift-left-right* 466 467 *<* 468<{motion} Shift {motion} lines one 'shiftwidth' leftwards. 469 470 If the 'vartabstop' feature is enabled, and the 471 'shiftwidth' option is set to zero, the amount of 472 indent is calculated at the first non-blank character 473 in the line. 474 *<<* 475<< Shift [count] lines one 'shiftwidth' leftwards. 476 477 *v_<* 478{Visual}[count]< Shift the highlighted lines [count] 'shiftwidth' 479 leftwards (for {Visual} see |Visual-mode|). 480 481 *>* 482 >{motion} Shift {motion} lines one 'shiftwidth' rightwards. 483 484 If the 'vartabstop' feature is enabled, and the 485 'shiftwidth' option is set to zero, the amount of 486 indent is calculated at the first non-blank character 487 in the line. 488 *>>* 489 >> Shift [count] lines one 'shiftwidth' rightwards. 490 491 *v_>* 492{Visual}[count]> Shift the highlighted lines [count] 'shiftwidth' 493 rightwards (for {Visual} see |Visual-mode|). 494 495 *:<* 496:[range]< Shift [range] lines one 'shiftwidth' left. Repeat '<' 497 for shifting multiple 'shiftwidth's. 498 499:[range]< {count} Shift {count} lines one 'shiftwidth' left, starting 500 with [range] (default current line |cmdline-ranges|). 501 Repeat '<' for shifting multiple 'shiftwidth's. 502 503:[range]le[ft] [indent] left align lines in [range]. Sets the indent in the 504 lines to [indent] (default 0). 505 506 *:>* 507:[range]> [flags] Shift {count} [range] lines one 'shiftwidth' right. 508 Repeat '>' for shifting multiple 'shiftwidth's. 509 See |ex-flags| for [flags]. 510 511:[range]> {count} [flags] 512 Shift {count} lines one 'shiftwidth' right, starting 513 with [range] (default current line |cmdline-ranges|). 514 Repeat '>' for shifting multiple 'shiftwidth's. 515 See |ex-flags| for [flags]. 516 517The ">" and "<" commands are handy for changing the indentation within 518programs. Use the 'shiftwidth' option to set the size of the white space 519which these commands insert or delete. Normally the 'shiftwidth' option is 8, 520but you can set it to, say, 3 to make smaller indents. The shift leftwards 521stops when there is no indent. The shift right does not affect empty lines. 522 523If the 'shiftround' option is on, the indent is rounded to a multiple of 524'shiftwidth'. 525 526If the 'smartindent' option is on, or 'cindent' is on and 'cinkeys' contains 527'#' with a zero value, shift right does not affect lines starting with '#' 528(these are supposed to be C preprocessor lines that must stay in column 1). 529This can be changed with the 'cino' option, see |cino-#|. 530 531When the 'expandtab' option is off (this is the default) Vim uses <Tab>s as 532much as possible to make the indent. You can use ">><<" to replace an indent 533made out of spaces with the same indent made out of <Tab>s (and a few spaces 534if necessary). If the 'expandtab' option is on, Vim uses only spaces. Then 535you can use ">><<" to replace <Tab>s in the indent by spaces (or use 536`:retab!`). 537 538To move a line several 'shiftwidth's, use Visual mode or the `:` commands. 539For example: > 540 Vjj4> move three lines 4 indents to the right 541 :<<< move current line 3 indents to the left 542 :>> 5 move 5 lines 2 indents to the right 543 :5>> move line 5 2 indents to the right 544 545============================================================================== 5464. Complex changes *complex-change* 547 5484.1 Filter commands *filter* 549 550A filter is a program that accepts text at standard input, changes it in some 551way, and sends it to standard output. You can use the commands below to send 552some text through a filter, so that it is replaced by the filter output. 553Examples of filters are "sort", which sorts lines alphabetically, and 554"indent", which formats C program files (you need a version of indent that 555works like a filter; not all versions do). The 'shell' option specifies the 556shell Vim uses to execute the filter command (See also the 'shelltype' 557option). You can repeat filter commands with ".". Vim does not recognize a 558comment (starting with '"') after the `:!` command. 559 560 *!* 561!{motion}{filter} Filter {motion} text lines through the external 562 program {filter}. 563 564 *!!* 565!!{filter} Filter [count] lines through the external program 566 {filter}. 567 568 *v_!* 569{Visual}!{filter} Filter the highlighted lines through the external 570 program {filter} (for {Visual} see |Visual-mode|). 571 572:{range}![!]{filter} [!][arg] *:range!* 573 Filter {range} lines through the external program 574 {filter}. Vim replaces the optional bangs with the 575 latest given command and appends the optional [arg]. 576 Vim saves the output of the filter command in a 577 temporary file and then reads the file into the buffer 578 |tempfile|. Vim uses the 'shellredir' option to 579 redirect the filter output to the temporary file. 580 However, if the 'shelltemp' option is off then pipes 581 are used when possible (on Unix). 582 When the 'R' flag is included in 'cpoptions' marks in 583 the filtered lines are deleted, unless the 584 |:keepmarks| command is used. Example: > 585 :keepmarks '<,'>!sort 586< When the number of lines after filtering is less than 587 before, marks in the missing lines are deleted anyway. 588 589 *=* 590={motion} Filter {motion} lines through the external program 591 given with the 'equalprg' option. When the 'equalprg' 592 option is empty (this is the default), use the 593 internal formatting function |C-indenting| and 594 |'lisp'|. But when 'indentexpr' is not empty, it will 595 be used instead |indent-expression|. When Vim was 596 compiled without internal formatting then the "indent" 597 program is used as a last resort. 598 599 *==* 600== Filter [count] lines like with ={motion}. 601 602 *v_=* 603{Visual}= Filter the highlighted lines like with ={motion}. 604 605 606 *tempfile* *setuid* 607Vim uses temporary files for filtering, generating diffs and also for 608tempname(). For Unix, the file will be in a private directory (only 609accessible by the current user) to avoid security problems (e.g., a symlink 610attack or other people reading your file). When Vim exits the directory and 611all files in it are deleted. When Vim has the setuid bit set this may cause 612problems, the temp file is owned by the setuid user but the filter command 613probably runs as the original user. 614On MS-Windows the first of these directories that works is used: $TMP, 615$TEMP, c:\TMP, c:\TEMP. 616For Unix the list of directories is: $TMPDIR, /tmp, current-dir, $HOME. 617For MS-Windows the GetTempFileName() system function is used. 618For other systems the tmpnam() library function is used. 619 620 621 6224.2 Substitute *:substitute* 623 *:s* *:su* 624:[range]s[ubstitute]/{pattern}/{string}/[flags] [count] 625 For each line in [range] replace a match of {pattern} 626 with {string}. 627 For the {pattern} see |pattern|. 628 {string} can be a literal string, or something 629 special; see |sub-replace-special|. 630 When [range] and [count] are omitted, replace in the 631 current line only. When [count] is given, replace in 632 [count] lines, starting with the last line in [range]. 633 When [range] is omitted start in the current line. 634 *E939* 635 [count] must be a positive number. Also see 636 |cmdline-ranges|. 637 638 See |:s_flags| for [flags]. 639 The delimiter doesn't need to be /, see 640 |pattern-delimiter|. 641 642:[range]s[ubstitute] [flags] [count] 643:[range]&[&][flags] [count] *:&* 644 Repeat last :substitute with same search pattern and 645 substitute string, but without the same flags. You 646 may add [flags], see |:s_flags|. 647 Note that after `:substitute` the '&' flag can't be 648 used, it's recognized as a pattern separator. 649 The space between `:substitute` and the 'c', 'g', 650 'i', 'I' and 'r' flags isn't required, but in scripts 651 it's a good idea to keep it to avoid confusion. 652 Also see the two and three letter commands to repeat 653 :substitute below |:substitute-repeat|. 654 655:[range]~[&][flags] [count] *:~* 656 Repeat last substitute with same substitute string 657 but with last used search pattern. This is like 658 `:&r`. See |:s_flags| for [flags]. 659 660 *&* 661& Synonym for `:s` (repeat last substitute). Note 662 that the flags are not remembered, thus it might 663 actually work differently. You can use `:&&` to keep 664 the flags. 665 666 *g&* 667g& Synonym for `:%s//~/&` (repeat last substitute with 668 last search pattern on all lines with the same flags). 669 For example, when you first do a substitution with 670 `:s/pattern/repl/flags` and then `/search` for 671 something else, `g&` will do `:%s/search/repl/flags`. 672 Mnemonic: global substitute. 673 674 *:snomagic* *:sno* 675:[range]sno[magic] ... Same as `:substitute`, but always use 'nomagic'. 676 677 *:smagic* *:sm* 678:[range]sm[agic] ... Same as `:substitute`, but always use 'magic'. 679 680 *:s_flags* 681The flags that you can use for the substitute commands: 682 683 *:&&* 684[&] Must be the first one: Keep the flags from the previous substitute 685 command. Examples: > 686 :&& 687 :s/this/that/& 688< Note that `:s` and `:&` don't keep the flags. 689 690[c] Confirm each substitution. Vim highlights the matching string (with 691 |hl-IncSearch|). You can type: *:s_c* 692 'y' to substitute this match 693 'l' to substitute this match and then quit ("last") 694 'n' to skip this match 695 <Esc> to quit substituting 696 'a' to substitute this and all remaining matches 697 'q' to quit substituting 698 CTRL-E to scroll the screen up 699 CTRL-Y to scroll the screen down 700 If the 'edcompatible' option is on, Vim remembers the [c] flag and 701 toggles it each time you use it, but resets it when you give a new 702 search pattern. 703 704 *:s_e* 705[e] When the search pattern fails, do not issue an error message and, in 706 particular, continue in maps as if no error occurred. This is most 707 useful to prevent the "No match" error from breaking a mapping. Vim 708 does not suppress the following error messages, however: 709 Regular expressions can't be delimited by letters 710 \ should be followed by /, ? or & 711 No previous substitute regular expression 712 Trailing characters 713 Interrupted 714 715 *:s_g* 716[g] Replace all occurrences in the line. Without this argument, 717 replacement occurs only for the first occurrence in each line. If 718 the 'edcompatible' option is on, Vim remembers this flag and toggles 719 it each time you use it, but resets it when you give a new search 720 pattern. If the 'gdefault' option is on, this flag is on by default 721 and the [g] argument switches it off. 722 723 *:s_i* 724[i] Ignore case for the pattern. The 'ignorecase' and 'smartcase' options 725 are not used. 726 727 *:s_I* 728[I] Don't ignore case for the pattern. The 'ignorecase' and 'smartcase' 729 options are not used. 730 731 *:s_n* 732[n] Report the number of matches, do not actually substitute. The [c] 733 flag is ignored. The matches are reported as if 'report' is zero. 734 Useful to |count-items|. 735 If \= |sub-replace-expression| is used, the expression will be 736 evaluated in the |sandbox| at every match. 737 738[p] Print the line containing the last substitute. *:s_p* 739 740[#] Like [p] and prepend the line number. *:s_#* 741 742[l] Like [p] but print the text like |:list|. *:s_l* 743 744 *:s_r* 745[r] Only useful in combination with `:&` or `:s` without arguments. `:&r` 746 works the same way as `:~`: When the search pattern is empty, use the 747 previously used search pattern instead of the search pattern from the 748 last substitute or `:global`. If the last command that did a search 749 was a substitute or `:global`, there is no effect. If the last 750 command was a search command such as "/", use the pattern from that 751 command. 752 For `:s` with an argument this already happens: > 753 :s/blue/red/ 754 /green 755 :s//red/ or :~ or :&r 756< The last commands will replace "green" with "red". > 757 :s/blue/red/ 758 /green 759 :& 760< The last command will replace "blue" with "red". 761 762Note that there is no flag to change the "magicness" of the pattern. A 763different command is used instead, or you can use |/\v| and friends. The 764reason is that the flags can only be found by skipping the pattern, and in 765order to skip the pattern the "magicness" must be known. Catch 22! 766 767If the {pattern} for the substitute command is empty, the command uses the 768pattern from the last substitute or `:global` command. If there is none, but 769there is a previous search pattern, that one is used. With the [r] flag, the 770command uses the pattern from the last substitute, `:global`, or search 771command. 772 773If the {string} is omitted the substitute is done as if it's empty. Thus the 774matched pattern is deleted. The separator after {pattern} can also be left 775out then. Example: > 776 :%s/TESTING 777This deletes "TESTING" from all lines, but only one per line. 778 779For compatibility with Vi these two exceptions are allowed: 780"\/{string}/" and "\?{string}?" do the same as "//{string}/r". 781"\&{string}&" does the same as "//{string}/". 782 *pattern-delimiter* *E146* 783Instead of the '/' which surrounds the pattern and replacement string, you can 784use another single-byte character. This is useful if you want to include a 785'/' in the search pattern or replacement string. Example: > 786 :s+/+//+ 787 788You can use most characters, but not an alphanumeric character, '\', '"' or 789'|'. In Vim9 script you should not use '#' because it may be recognized as 790the start of a comment. 791 792For the definition of a pattern, see |pattern|. In Visual block mode, use 793|/\%V| in the pattern to have the substitute work in the block only. 794Otherwise it works on whole lines anyway. 795 796 *sub-replace-special* *:s\=* 797When the {string} starts with "\=" it is evaluated as an expression, see 798|sub-replace-expression|. You can use that for complex replacement or special 799characters. 800 801Otherwise these characters in {string} have a special meaning: 802 *:s%* 803When {string} is equal to "%" and '/' is included with the 'cpoptions' option, 804then the {string} of the previous substitute command is used, see |cpo-/| 805 806magic nomagic action ~ 807 & \& replaced with the whole matched pattern *s/\&* 808 \& & replaced with & 809 \0 replaced with the whole matched pattern *\0* *s/\0* 810 \1 replaced with the matched pattern in the first 811 pair of () *s/\1* 812 \2 replaced with the matched pattern in the second 813 pair of () *s/\2* 814 .. .. *s/\3* 815 \9 replaced with the matched pattern in the ninth 816 pair of () *s/\9* 817 ~ \~ replaced with the {string} of the previous 818 substitute *s~* 819 \~ ~ replaced with ~ *s/\~* 820 \u next character made uppercase *s/\u* 821 \U following characters made uppercase, until \E *s/\U* 822 \l next character made lowercase *s/\l* 823 \L following characters made lowercase, until \E *s/\L* 824 \e end of \u, \U, \l and \L (NOTE: not <Esc>!) *s/\e* 825 \E end of \u, \U, \l and \L *s/\E* 826 <CR> split line in two at this point 827 (Type the <CR> as CTRL-V <Enter>) *s<CR>* 828 \r idem *s/\r* 829 \<CR> insert a carriage-return (CTRL-M) 830 (Type the <CR> as CTRL-V <Enter>) *s/\<CR>* 831 \n insert a <NL> (<NUL> in the file) 832 (does NOT break the line) *s/\n* 833 \b insert a <BS> *s/\b* 834 \t insert a <Tab> *s/\t* 835 \\ insert a single backslash *s/\\* 836 \x where x is any character not mentioned above: 837 Reserved for future expansion 838 839The special meaning is also used inside the third argument {sub} of 840the |substitute()| function with the following exceptions: 841 - A % inserts a percent literally without regard to 'cpoptions'. 842 - magic is always set without regard to 'magic'. 843 - A ~ inserts a tilde literally. 844 - <CR> and \r inserts a carriage-return (CTRL-M). 845 - \<CR> does not have a special meaning. It's just one of \x. 846 847Examples: > 848 :s/a\|b/xxx\0xxx/g modifies "a b" to "xxxaxxx xxxbxxx" 849 :s/\([abc]\)\([efg]\)/\2\1/g modifies "af fa bg" to "fa fa gb" 850 :s/abcde/abc^Mde/ modifies "abcde" to "abc", "de" (two lines) 851 :s/$/\^M/ modifies "abcde" to "abcde^M" 852 :s/\w\+/\u\0/g modifies "bla bla" to "Bla Bla" 853 :s/\w\+/\L\u\0/g modifies "BLA bla" to "Bla Bla" 854 855Note: "\L\u" can be used to capitalize the first letter of a word. This is 856not compatible with Vi and older versions of Vim, where the "\u" would cancel 857out the "\L". Same for "\U\l". 858 859Note: In previous versions CTRL-V was handled in a special way. Since this is 860not Vi compatible, this was removed. Use a backslash instead. 861 862command text result ~ 863:s/aa/a^Ma/ aa a<line-break>a 864:s/aa/a\^Ma/ aa a^Ma 865:s/aa/a\\^Ma/ aa a\<line-break>a 866 867(you need to type CTRL-V <CR> to get a ^M here) 868 869The numbering of "\1", "\2" etc. is done based on which "\(" comes first in 870the pattern (going left to right). When a parentheses group matches several 871times, the last one will be used for "\1", "\2", etc. Example: > 872 :s/\(\(a[a-d] \)*\)/\2/ modifies "aa ab x" to "ab x" 873The "\2" is for "\(a[a-d] \)". At first it matches "aa ", secondly "ab ". 874 875When using parentheses in combination with '|', like in \([ab]\)\|\([cd]\), 876either the first or second pattern in parentheses did not match, so either 877\1 or \2 is empty. Example: > 878 :s/\([ab]\)\|\([cd]\)/\1x/g modifies "a b c d" to "ax bx x x" 879< 880 881 *:sc* *:sce* *:scg* *:sci* *:scI* *:scl* *:scp* *:sg* *:sgc* 882 *:sge* *:sgi* *:sgI* *:sgl* *:sgn* *:sgp* *:sgr* *:sI* *:si* 883 *:sic* *:sIc* *:sie* *:sIe* *:sIg* *:sIl* *:sin* *:sIn* *:sIp* 884 *:sip* *:sIr* *:sir* *:sr* *:src* *:srg* *:sri* *:srI* *:srl* 885 *:srn* *:srp* *:substitute-repeat* 8862-letter and 3-letter :substitute commands ~ 887 888These commands repeat the previous `:substitute` command with the given flags. 889The first letter is always "s", followed by one or two of the possible flag 890characters. For example `:sce` works like `:s///ce`. The table lists the 891possible combinations, not all flags are possible, because the command is 892short for another command. 893 894 List of :substitute commands 895 | c e g i I n p l r 896 | c :sc :sce :scg :sci :scI :scn :scp :scl 897 | e 898 | g :sgc :sge :sg :sgi :sgI :sgn :sgp :sgl :sgr 899 | i :sic :sie :si :siI :sin :sip :sir 900 | I :sIc :sIe :sIg :sIi :sI :sIn :sIp :sIl :sIr 901 | n 902 | p 903 | l 904 | r :src :srg :sri :srI :srn :srp :srl :sr 905 906Exceptions: 907 :scr is `:scriptnames` 908 :se is `:set` 909 :sig is `:sign` 910 :sil is `:silent` 911 :sn is `:snext` 912 :sp is `:split` 913 :sl is `:sleep` 914 :sre is `:srewind` 915 916 917Substitute with an expression *sub-replace-expression* 918 *sub-replace-\=* *s/\=* 919When the substitute string starts with "\=" the remainder is interpreted as an 920expression. 921 922The special meaning for characters as mentioned at |sub-replace-special| does 923not apply except for "<CR>". A <NL> character is used as a line break, you 924can get one with a double-quote string: "\n". Prepend a backslash to get a 925real <NL> character (which will be a NUL in the file). 926 927The "\=" notation can also be used inside the third argument {sub} of 928|substitute()| function. In this case, the special meaning for characters as 929mentioned at |sub-replace-special| does not apply at all. Especially, <CR> and 930<NL> are interpreted not as a line break but as a carriage-return and a 931new-line respectively. 932 933When the result is a |List| then the items are joined with separating line 934breaks. Thus each item becomes a line, except that they can contain line 935breaks themselves. 936 937The |submatch()| function can be used to obtain matched text. The whole 938matched text can be accessed with "submatch(0)". The text matched with the 939first pair of () with "submatch(1)". Likewise for further sub-matches in (). 940 941Be careful: The separation character must not appear in the expression! 942Consider using a character like "@" or ":". There is no problem if the result 943of the expression contains the separation character. 944 945Examples: > 946 :s@\n@\="\r" . expand("$HOME") . "\r"@ 947This replaces an end-of-line with a new line containing the value of $HOME. > 948 949 s/E/\="\<Char-0x20ac>"/g 950This replaces each 'E' character with a euro sign. Read more in |<Char->|. 951 952 9534.3 Search and replace *search-replace* 954 955 *:pro* *:promptfind* 956:promptf[ind] [string] 957 Put up a Search dialog. When [string] is given, it is 958 used as the initial search string. 959 {only for Win32, Motif and GTK GUI} 960 961 *:promptr* *:promptrepl* 962:promptr[epl] [string] 963 Put up a Search/Replace dialog. When [string] is 964 given, it is used as the initial search string. 965 {only for Win32, Motif and GTK GUI} 966 967 9684.4 Changing tabs *change-tabs* 969 *:ret* *:retab* *:retab!* 970:[range]ret[ab][!] [new_tabstop] 971 Replace all sequences of white-space containing a 972 <Tab> with new strings of white-space using the new 973 tabstop value given. If you do not specify a new 974 tabstop size or it is zero, Vim uses the current value 975 of 'tabstop'. 976 The current value of 'tabstop' is always used to 977 compute the width of existing tabs. 978 With !, Vim also replaces strings of only normal 979 spaces with tabs where appropriate. 980 With 'expandtab' on, Vim replaces all tabs with the 981 appropriate number of spaces. 982 This command sets 'tabstop' to the new value given, 983 and if performed on the whole file, which is default, 984 should not make any visible change. 985 Careful: This command modifies any <Tab> characters 986 inside of strings in a C program. Use "\t" to avoid 987 this (that's a good habit anyway). 988 `:retab!` may also change a sequence of spaces by 989 <Tab> characters, which can mess up a printf(). 990 If the |+vartabs| feature is enabled then a list of 991 tab widths separated by commas may be used in place of 992 a single tabstop. Each value in the list represents 993 the width of one tabstop, except the final value which 994 applies to all following tabstops. 995 996 *retab-example* 997Example for using autocommands and ":retab" to edit a file which is stored 998with tabstops at 8 but edited with tabstops set at 4. Warning: white space 999inside of strings can change! Also see 'softtabstop' option. > 1000 1001 :auto BufReadPost *.xx retab! 4 1002 :auto BufWritePre *.xx retab! 8 1003 :auto BufWritePost *.xx retab! 4 1004 :auto BufNewFile *.xx set ts=4 1005 1006============================================================================== 10075. Copying and moving text *copy-move* 1008 1009 *quote* 1010"{register} Use {register} for next delete, yank or put. Use 1011 an uppercase character to append with delete and yank. 1012 Registers ".", "%", "#" and ":" only work with put. 1013 1014 *:reg* *:registers* 1015:reg[isters] Display the type and contents of all numbered and 1016 named registers. If a register is written to for 1017 |:redir| it will not be listed. 1018 Type can be one of: 1019 "c" for |characterwise| text 1020 "l" for |linewise| text 1021 "b" for |blockwise-visual| text 1022 1023 1024:reg[isters] {arg} Display the contents of the numbered and named 1025 registers that are mentioned in {arg}. For example: > 1026 :reg 1a 1027< to display registers '1' and 'a'. Spaces are allowed 1028 in {arg}. 1029 1030 *:di* *:display* 1031:di[splay] [arg] Same as :registers. 1032 1033 *y* *yank* 1034["x]y{motion} Yank {motion} text [into register x]. When no 1035 characters are to be yanked (e.g., "y0" in column 1), 1036 this is an error when 'cpoptions' includes the 'E' 1037 flag. 1038 1039 *yy* 1040["x]yy Yank [count] lines [into register x] |linewise|. 1041 1042 *Y* 1043["x]Y yank [count] lines [into register x] (synonym for 1044 yy, |linewise|). If you like "Y" to work from the 1045 cursor to the end of line (which is more logical, 1046 but not Vi-compatible) use ":map Y y$". 1047 1048 *zy* 1049["x]zy{motion} Yank {motion} text [into register x]. Only differs 1050 from `y` when selecting a block of text, see |v_zy|. 1051 1052 *v_y* 1053{Visual}["x]y Yank the highlighted text [into register x] (for 1054 {Visual} see |Visual-mode|). 1055 1056 *v_Y* 1057{Visual}["x]Y Yank the highlighted lines [into register x] (for 1058 {Visual} see |Visual-mode|). 1059 1060 *v_zy* 1061{Visual}["x]zy Yank the highlighted text [into register x]. Trailing 1062 whitespace at the end of each line of a selected block 1063 won't be yanked. Especially useful in combination 1064 with `zp`. (for {Visual} see |Visual-mode|) 1065 1066 *:y* *:yank* *E850* 1067:[range]y[ank] [x] Yank [range] lines [into register x]. Yanking to the 1068 "* or "+ registers is possible only when the 1069 |+clipboard| feature is included. 1070 1071:[range]y[ank] [x] {count} 1072 Yank {count} lines, starting with last line number 1073 in [range] (default: current line |cmdline-ranges|), 1074 [into register x]. 1075 1076 *p* *put* *E353* 1077["x]p Put the text [from register x] after the cursor 1078 [count] times. 1079 1080 *P* 1081["x]P Put the text [from register x] before the cursor 1082 [count] times. 1083 1084 *<MiddleMouse>* 1085["x]<MiddleMouse> Put the text from a register before the cursor [count] 1086 times. Uses the "* register, unless another is 1087 specified. 1088 Leaves the cursor at the end of the new text. 1089 Using the mouse only works when 'mouse' contains 'n' 1090 or 'a'. 1091 If you have a scrollwheel and often accidentally paste 1092 text, you can use these mappings to disable the 1093 pasting with the middle mouse button: > 1094 :map <MiddleMouse> <Nop> 1095 :imap <MiddleMouse> <Nop> 1096< You might want to disable the multi-click versions 1097 too, see |double-click|. 1098 1099 *gp* 1100["x]gp Just like "p", but leave the cursor just after the new 1101 text. 1102 1103 *gP* 1104["x]gP Just like "P", but leave the cursor just after the new 1105 text. 1106 1107 *:pu* *:put* 1108:[line]pu[t] [x] Put the text [from register x] after [line] (default 1109 current line). This always works |linewise|, thus 1110 this command can be used to put a yanked block as new 1111 lines. 1112 If no register is specified, it depends on the 'cb' 1113 option: If 'cb' contains "unnamedplus", paste from the 1114 + register |quoteplus|. Otherwise, if 'cb' contains 1115 "unnamed", paste from the * register |quotestar|. 1116 Otherwise, paste from the unnamed register 1117 |quote_quote|. 1118 The register can also be '=' followed by an optional 1119 expression. The expression continues until the end of 1120 the command. You need to escape the '|' and '"' 1121 characters to prevent them from terminating the 1122 command. Example: > 1123 :put ='path' . \",/test\" 1124< If there is no expression after '=', Vim uses the 1125 previous expression. You can see it with ":dis =". 1126 1127:[line]pu[t]! [x] Put the text [from register x] before [line] (default 1128 current line). 1129 1130["x]]p or *]p* *]<MiddleMouse>* 1131["x]]<MiddleMouse> Like "p", but adjust the indent to the current line. 1132 Using the mouse only works when 'mouse' contains 'n' 1133 or 'a'. 1134 1135["x][P or *[P* 1136["x]]P or *]P* 1137["x][p or *[p* *[<MiddleMouse>* 1138["x][<MiddleMouse> Like "P", but adjust the indent to the current line. 1139 Using the mouse only works when 'mouse' contains 'n' 1140 or 'a'. 1141 1142["x]zp or *zp* *zP* 1143["x]zP Like "p" and "P", except without adding trailing spaces 1144 when pasting a block. Thus the inserted text will not 1145 always be a rectangle. Especially useful in 1146 combination with |v_zy|. 1147 1148You can use these commands to copy text from one place to another. Do this 1149by first getting the text into a register with a yank, delete or change 1150command, then inserting the register contents with a put command. You can 1151also use these commands to move text from one file to another, because Vim 1152preserves all registers when changing buffers (the CTRL-^ command is a quick 1153way to toggle between two files). 1154 1155 *linewise-register* *characterwise-register* 1156You can repeat the put commands with "." (except for :put) and undo them. If 1157the command that was used to get the text into the register was |linewise|, 1158Vim inserts the text below ("p") or above ("P") the line where the cursor is. 1159Otherwise Vim inserts the text after ("p") or before ("P") the cursor. With 1160the ":put" command, Vim always inserts the text in the next line. You can 1161exchange two characters with the command sequence "xp". You can exchange two 1162lines with the command sequence "ddp". You can exchange two words with the 1163command sequence "deep" (start with the cursor in the blank space before the 1164first word). You can use the "']" or "`]" command after the put command to 1165move the cursor to the end of the inserted text, or use "'[" or "`[" to move 1166the cursor to the start. 1167 1168 *put-Visual-mode* *v_p* *v_P* 1169When using a put command like |p| or |P| in Visual mode, Vim will try to 1170replace the selected text with the contents of the register. Whether this 1171works well depends on the type of selection and the type of the text in the 1172register. With blockwise selection it also depends on the size of the block 1173and whether the corners are on an existing character. (Implementation detail: 1174it actually works by first putting the register after the selection and then 1175deleting the selection.) 1176The previously selected text is put in the unnamed register. If you want to 1177put the same text into a Visual selection several times you need to use 1178another register. E.g., yank the text to copy, Visually select the text to 1179replace and use "0p . You can repeat this as many times as you like, the 1180unnamed register will be changed each time. 1181 1182When you use a blockwise Visual mode command and yank only a single line into 1183a register, a paste on a visual selected area will paste that single line on 1184each of the selected lines (thus replacing the blockwise selected region by a 1185block of the pasted line). 1186 1187 *blockwise-register* 1188If you use a blockwise Visual mode command to get the text into the register, 1189the block of text will be inserted before ("P") or after ("p") the cursor 1190column in the current and next lines. Vim makes the whole block of text start 1191in the same column. Thus the inserted text looks the same as when it was 1192yanked or deleted. Vim may replace some <Tab> characters with spaces to make 1193this happen. However, if the width of the block is not a multiple of a <Tab> 1194width and the text after the inserted block contains <Tab>s, that text may be 1195misaligned. 1196 1197Use |zP|/|zp| to paste a blockwise yanked register without appending trailing 1198spaces. 1199 1200Note that after a characterwise yank command, Vim leaves the cursor on the 1201first yanked character that is closest to the start of the buffer. This means 1202that "yl" doesn't move the cursor, but "yh" moves the cursor one character 1203left. 1204Rationale: In Vi the "y" command followed by a backwards motion would 1205 sometimes not move the cursor to the first yanked character, 1206 because redisplaying was skipped. In Vim it always moves to 1207 the first character, as specified by Posix. 1208With a linewise yank command the cursor is put in the first line, but the 1209column is unmodified, thus it may not be on the first yanked character. 1210 1211There are ten types of registers: *registers* *{register}* *E354* 12121. The unnamed register "" 12132. 10 numbered registers "0 to "9 12143. The small delete register "- 12154. 26 named registers "a to "z or "A to "Z 12165. Three read-only registers ":, "., "% 12176. Alternate buffer register "# 12187. The expression register "= 12198. The selection and drop registers "*, "+ and "~ 12209. The black hole register "_ 122110. Last search pattern register "/ 1222 12231. Unnamed register "" *quote_quote* *quotequote* 1224Vim fills this register with text deleted with the "d", "c", "s", "x" commands 1225or copied with the yank "y" command, regardless of whether or not a specific 1226register was used (e.g. "xdd). This is like the unnamed register is pointing 1227to the last used register. Thus when appending using an uppercase register 1228name, the unnamed register contains the same text as the named register. 1229An exception is the '_' register: "_dd does not store the deleted text in any 1230register. 1231Vim uses the contents of the unnamed register for any put command (p or P) 1232which does not specify a register. Additionally you can access it with the 1233name '"'. This means you have to type two double quotes. Writing to the "" 1234register writes to register "0. 1235{Vi: register contents are lost when changing files, no '"'} 1236 12372. Numbered registers "0 to "9 *quote_number* *quote0* *quote1* 1238 *quote2* *quote3* *quote4* *quote9* 1239Vim fills these registers with text from yank and delete commands. 1240 Numbered register 0 contains the text from the most recent yank command, 1241unless the command specified another register with ["x]. 1242 Numbered register 1 contains the text deleted by the most recent delete or 1243change command, unless the command specified another register or the text is 1244less than one line (the small delete register is used then). An exception is 1245made for the delete operator with these movement commands: |%|, |(|, |)|, |`|, 1246|/|, |?|, |n|, |N|, |{| and |}|. Register "1 is always used then (this is Vi 1247compatible). The "- register is used as well if the delete is within a line. 1248Note that these characters may be mapped. E.g. |%| is mapped by the matchit 1249plugin. 1250 With each successive deletion or change, Vim shifts the previous contents 1251of register 1 into register 2, 2 into 3, and so forth, losing the previous 1252contents of register 9. 1253{Vi: numbered register contents are lost when changing files; register 0 does 1254not exist} 1255 12563. Small delete register "- *quote_-* *quote-* 1257This register contains text from commands that delete less than one line, 1258except when the command specifies a register with ["x]. 1259 12604. Named registers "a to "z or "A to "Z *quote_alpha* *quotea* 1261Vim fills these registers only when you say so. Specify them as lowercase 1262letters to replace their previous contents or as uppercase letters to append 1263to their previous contents. When the '>' flag is present in 'cpoptions' then 1264a line break is inserted before the appended text. 1265 12665. Read-only registers ":, ". and "% 1267These are '%', '#', ':' and '.'. You can use them only with the "p", "P", 1268and ":put" commands and with CTRL-R. 1269 *quote_.* *quote.* *E29* 1270 ". Contains the last inserted text (the same as what is inserted 1271 with the insert mode commands CTRL-A and CTRL-@). Note: this 1272 doesn't work with CTRL-R on the command-line. It works a bit 1273 differently, like inserting the text instead of putting it 1274 ('textwidth' and other options affect what is inserted). 1275 *quote_%* *quote%* 1276 "% Contains the name of the current file. 1277 *quote_:* *quote:* *E30* 1278 ": Contains the most recent executed command-line. Example: Use 1279 "@:" to repeat the previous command-line command. 1280 The command-line is only stored in this register when at least 1281 one character of it was typed. Thus it remains unchanged if 1282 the command was completely from a mapping. 1283 {not available when compiled without the |+cmdline_hist| 1284 feature} 1285 *quote_#* *quote#* 12866. Alternate file register "# 1287Contains the name of the alternate file for the current window. It will 1288change how the |CTRL-^| command works. 1289This register is writable, mainly to allow for restoring it after a plugin has 1290changed it. It accepts buffer number: > 1291 let altbuf = bufnr(@#) 1292 ... 1293 let @# = altbuf 1294It will give error |E86| if you pass buffer number and this buffer does not 1295exist. 1296It can also accept a match with an existing buffer name: > 1297 let @# = 'buffer_name' 1298Error |E93| if there is more than one buffer matching the given name or |E94| 1299if none of buffers matches the given name. 1300 13017. Expression register "= *quote_=* *quote=* *@=* 1302This is not really a register that stores text, but is a way to use an 1303expression in commands which use a register. The expression register is 1304read-write. 1305 1306When typing the '=' after " or CTRL-R the cursor moves to the command-line, 1307where you can enter any expression (see |expression|). All normal 1308command-line editing commands are available, including a special history for 1309expressions. When you end the command-line by typing <CR>, Vim computes the 1310result of the expression. If you end it with <Esc>, Vim abandons the 1311expression. If you do not enter an expression, Vim uses the previous 1312expression (like with the "/" command). 1313 1314The expression must evaluate to a String. A Number is always automatically 1315converted to a String. For the "p" and ":put" command, if the result is a 1316Float it's converted into a String. If the result is a List each element is 1317turned into a String and used as a line. A Dictionary or FuncRef results in 1318an error message (use string() to convert). 1319 1320If the "= register is used for the "p" command, the String is split up at <NL> 1321characters. If the String ends in a <NL>, it is regarded as a linewise 1322register. 1323 13248. Selection and drop registers "*, "+ and "~ 1325Use these registers for storing and retrieving the selected text for the GUI. 1326See |quotestar| and |quoteplus|. When the clipboard is not available or not 1327working, the unnamed register is used instead. For Unix systems the clipboard 1328is only available when the |+xterm_clipboard| feature is present. 1329 1330Note that there is only a distinction between "* and "+ for X11 systems. For 1331an explanation of the difference, see |x11-selection|. Under MS-Windows, use 1332of "* and "+ is actually synonymous and refers to the |gui-clipboard|. 1333 1334 *quote_~* *quote~* *<Drop>* 1335The read-only "~ register stores the dropped text from the last drag'n'drop 1336operation. When something has been dropped onto Vim, the "~ register is 1337filled in and the <Drop> pseudo key is sent for notification. You can remap 1338this key if you want; the default action (for all modes) is to insert the 1339contents of the "~ register at the cursor position. 1340{only available when compiled with the |+dnd| feature, currently only with the 1341GTK GUI} 1342 1343Note: The "~ register is only used when dropping plain text onto Vim. 1344Drag'n'drop of URI lists is handled internally. 1345 13469. Black hole register "_ *quote_* 1347When writing to this register, nothing happens. This can be used to delete 1348text without affecting the normal registers. When reading from this register, 1349nothing is returned. 1350 135110. Last search pattern register "/ *quote_/* *quote/* 1352Contains the most recent search-pattern. This is used for "n" and 'hlsearch'. 1353It is writable with `:let`, you can change it to have 'hlsearch' highlight 1354other matches without actually searching. You can't yank or delete into this 1355register. The search direction is available in |v:searchforward|. 1356Note that the value is restored when returning from a function 1357|function-search-undo|. 1358 1359 *@/* 1360You can write to a register with a `:let` command |:let-@|. Example: > 1361 :let @/ = "the" 1362 1363If you use a put command without specifying a register, Vim uses the register 1364that was last filled (this is also the contents of the unnamed register). If 1365you are confused, use the `:dis` command to find out what Vim will put (this 1366command displays all named and numbered registers; the unnamed register is 1367labelled '"'). 1368 1369The next three commands always work on whole lines. 1370 1371:[range]co[py] {address} *:co* *:copy* 1372 Copy the lines given by [range] to below the line 1373 given by {address}. 1374 1375 *:t* 1376:t Synonym for copy. 1377 1378:[range]m[ove] {address} *:m* *:mo* *:move* *E134* 1379 Move the lines given by [range] to below the line 1380 given by {address}. 1381 1382============================================================================== 13836. Formatting text *formatting* 1384 1385:[range]ce[nter] [width] *:ce* *:center* 1386 Center lines in [range] between [width] columns 1387 (default 'textwidth' or 80 when 'textwidth' is 0). 1388 1389:[range]ri[ght] [width] *:ri* *:right* 1390 Right-align lines in [range] at [width] columns 1391 (default 'textwidth' or 80 when 'textwidth' is 0). 1392 1393 *:le* *:left* 1394:[range]le[ft] [indent] 1395 Left-align lines in [range]. Sets the indent in the 1396 lines to [indent] (default 0). 1397 1398 *gq* 1399gq{motion} Format the lines that {motion} moves over. 1400 Formatting is done with one of three methods: 1401 1. If 'formatexpr' is not empty the expression is 1402 evaluated. This can differ for each buffer. 1403 2. If 'formatprg' is not empty an external program 1404 is used. 1405 3. Otherwise formatting is done internally. 1406 1407 In the third case the 'textwidth' option controls the 1408 length of each formatted line (see below). 1409 If the 'textwidth' option is 0, the formatted line 1410 length is the screen width (with a maximum width of 1411 79). 1412 The 'formatoptions' option controls the type of 1413 formatting |fo-table|. 1414 The cursor is left on the first non-blank of the last 1415 formatted line. 1416 NOTE: The "Q" command formerly performed this 1417 function. If you still want to use "Q" for 1418 formatting, use this mapping: > 1419 :nnoremap Q gq 1420 1421gqgq *gqgq* *gqq* 1422gqq Format the current line. With a count format that 1423 many lines. 1424 1425 *v_gq* 1426{Visual}gq Format the highlighted text. (for {Visual} see 1427 |Visual-mode|). 1428 1429 *gw* 1430gw{motion} Format the lines that {motion} moves over. Similar to 1431 |gq| but puts the cursor back at the same position in 1432 the text. However, 'formatprg' and 'formatexpr' are 1433 not used. 1434 1435gwgw *gwgw* *gww* 1436gww Format the current line as with "gw". 1437 1438 *v_gw* 1439{Visual}gw Format the highlighted text as with "gw". (for 1440 {Visual} see |Visual-mode|). 1441 1442Example: To format the current paragraph use: *gqap* > 1443 gqap 1444 1445The "gq" command leaves the cursor in the line where the motion command takes 1446the cursor. This allows you to repeat formatting repeated with ".". This 1447works well with "gqj" (format current and next line) and "gq}" (format until 1448end of paragraph). Note: When 'formatprg' is set, "gq" leaves the cursor on 1449the first formatted line (as with using a filter command). 1450 1451If you want to format the current paragraph and continue where you were, use: > 1452 gwap 1453If you always want to keep paragraphs formatted you may want to add the 'a' 1454flag to 'formatoptions'. See |auto-format|. 1455 1456If the 'autoindent' option is on, Vim uses the indent of the first line for 1457the following lines. 1458 1459Formatting does not change empty lines (but it does change lines with only 1460white space!). 1461 1462The 'joinspaces' option is used when lines are joined together. 1463 1464You can set the 'formatexpr' option to an expression or the 'formatprg' option 1465to the name of an external program for Vim to use for text formatting. The 1466'textwidth' and other options have no effect on formatting by an external 1467program. 1468 1469 *format-formatexpr* 1470The 'formatexpr' option can be set to a Vim script function that performs 1471reformatting of the buffer. This should usually happen in an |ftplugin|, 1472since formatting is highly dependent on the type of file. It makes 1473sense to use an |autoload| script, so the corresponding script is only loaded 1474when actually needed and the script should be called <filetype>format.vim. 1475 1476For example, the XML filetype plugin distributed with Vim in the $VIMRUNTIME 1477directory, sets the 'formatexpr' option to: > 1478 1479 setlocal formatexpr=xmlformat#Format() 1480 1481That means, you will find the corresponding script, defining the 1482xmlformat#Format() function, in the directory: 1483`$VIMRUNTIME/autoload/xmlformat.vim` 1484 1485Here is an example script that removes trailing whitespace from the selected 1486text. Put it in your autoload directory, e.g. ~/.vim/autoload/format.vim: > 1487 1488 func! format#Format() 1489 " only reformat on explicit gq command 1490 if mode() != 'n' 1491 " fall back to Vim's internal reformatting 1492 return 1 1493 endif 1494 let lines = getline(v:lnum, v:lnum + v:count - 1) 1495 call map(lines, {key, val -> substitute(val, '\s\+$', '', 'g')}) 1496 call setline('.', lines) 1497 1498 " do not run internal formatter! 1499 return 0 1500 endfunc 1501 1502You can then enable the formatting by executing: > 1503 setlocal formatexpr=format#Format() 1504 1505Note: this function explicitly returns non-zero when called from insert mode 1506(which basically means, text is inserted beyond the 'textwidth' limit). This 1507causes Vim to fall back to reformat the text by using the internal formatter. 1508 1509However, if the |gq| command is used to reformat the text, the function 1510will receive the selected lines, trim trailing whitespace from those lines and 1511put them back in place. If you are going to split single lines into multiple 1512lines, be careful not to overwrite anything. 1513 1514If you want to allow reformatting of text from insert or replace mode, one has 1515to be very careful, because the function might be called recursively. For 1516debugging it helps to set the 'debug' option. 1517 1518 *right-justify* 1519There is no command in Vim to right justify text. You can do it with 1520an external command, like "par" (e.g.: "!}par" to format until the end of the 1521paragraph) or set 'formatprg' to "par". 1522 1523 *format-comments* 1524An overview of comment formatting is in section |30.6| of the user manual. 1525 1526Vim can automatically insert and format comments in a special way. Vim 1527recognizes a comment by a specific string at the start of the line (ignoring 1528white space). Three types of comments can be used: 1529 1530- A comment string that repeats at the start of each line. An example is the 1531 type of comment used in shell scripts, starting with "#". 1532- A comment string that occurs only in the first line, not in the following 1533 lines. An example is this list with dashes. 1534- Three-piece comments that have a start string, an end string, and optional 1535 lines in between. The strings for the start, middle and end are different. 1536 An example is the C style comment: 1537 /* 1538 * this is a C comment 1539 */ 1540 1541The 'comments' option is a comma-separated list of parts. Each part defines a 1542type of comment string. A part consists of: 1543 {flags}:{string} 1544 1545{string} is the literal text that must appear. 1546 1547{flags}: 1548 n Nested comment. Nesting with mixed parts is allowed. If 'comments' 1549 is "n:),n:>" a line starting with "> ) >" is a comment. 1550 1551 b Blank (<Space>, <Tab> or <EOL>) required after {string}. 1552 1553 f Only the first line has the comment string. Do not repeat comment on 1554 the next line, but preserve indentation (e.g., a bullet-list). 1555 1556 s Start of three-piece comment 1557 1558 m Middle of a three-piece comment 1559 1560 e End of a three-piece comment 1561 1562 l Left align. Used together with 's' or 'e', the leftmost character of 1563 start or end will line up with the leftmost character from the middle. 1564 This is the default and can be omitted. See below for more details. 1565 1566 r Right align. Same as above but rightmost instead of leftmost. See 1567 below for more details. 1568 1569 O Don't consider this comment for the "O" command. 1570 1571 x Allows three-piece comments to be ended by just typing the last 1572 character of the end-comment string as the first action on a new 1573 line when the middle-comment string has been inserted automatically. 1574 See below for more details. 1575 1576 {digits} 1577 When together with 's' or 'e': add {digit} amount of offset to an 1578 automatically inserted middle or end comment leader. The offset begins 1579 from a left alignment. See below for more details. 1580 1581 -{digits} 1582 Like {digits} but reduce the indent. This only works when there is 1583 some indent for the start or end part that can be removed. 1584 1585When a string has none of the 'f', 's', 'm' or 'e' flags, Vim assumes the 1586comment string repeats at the start of each line. The flags field may be 1587empty. 1588 1589Any blank space in the text before and after the {string} is part of the 1590{string}, so do not include leading or trailing blanks unless the blanks are a 1591required part of the comment string. 1592 1593When one comment leader is part of another, specify the part after the whole. 1594For example, to include both "-" and "->", use > 1595 :set comments=f:->,f:- 1596 1597A three-piece comment must always be given as start,middle,end, with no other 1598parts in between. An example of a three-piece comment is > 1599 sr:/*,mb:*,ex:*/ 1600for C-comments. To avoid recognizing "*ptr" as a comment, the middle string 1601includes the 'b' flag. For three-piece comments, Vim checks the text after 1602the start and middle strings for the end string. If Vim finds the end string, 1603the comment does not continue on the next line. Three-piece comments must 1604have a middle string because otherwise Vim can't recognize the middle lines. 1605 1606Notice the use of the "x" flag in the above three-piece comment definition. 1607When you hit Return in a C-comment, Vim will insert the middle comment leader 1608for the new line: " * ". To close this comment you just have to type "/" 1609before typing anything else on the new line. This will replace the 1610middle-comment leader with the end-comment leader and apply any specified 1611alignment, leaving just " */". There is no need to hit Backspace first. 1612 1613When there is a match with a middle part, but there also is a matching end 1614part which is longer, the end part is used. This makes a C style comment work 1615without requiring the middle part to end with a space. 1616 1617Here is an example of alignment flags at work to make a comment stand out 1618(kind of looks like a 1 too). Consider comment string: > 1619 :set comments=sr:/***,m:**,ex-2:******/ 1620< 1621 /*** ~ 1622 **<--right aligned from "r" flag ~ 1623 ** ~ 1624offset 2 spaces for the "-2" flag--->** ~ 1625 ******/ ~ 1626In this case, the first comment was typed, then return was pressed 4 times, 1627then "/" was pressed to end the comment. 1628 1629Here are some finer points of three part comments. There are three times when 1630alignment and offset flags are taken into consideration: opening a new line 1631after a start-comment, opening a new line before an end-comment, and 1632automatically ending a three-piece comment. The end alignment flag has a 1633backwards perspective; the result is that the same alignment flag used with 1634"s" and "e" will result in the same indent for the starting and ending pieces. 1635Only one alignment per comment part is meant to be used, but an offset number 1636will override the "r" and "l" flag. 1637 1638Enabling 'cindent' will override the alignment flags in many cases. 1639Reindenting using a different method like |gq| or |=| will not consult 1640alignment flags either. The same behaviour can be defined in those other 1641formatting options. One consideration is that 'cindent' has additional options 1642for context based indenting of comments but cannot replicate many three piece 1643indent alignments. However, 'indentexpr' has the ability to work better with 1644three piece comments. 1645 1646Other examples: > 1647 "b:*" Includes lines starting with "*", but not if the "*" is 1648 followed by a non-blank. This avoids a pointer dereference 1649 like "*str" to be recognized as a comment. 1650 "n:>" Includes a line starting with ">", ">>", ">>>", etc. 1651 "fb:-" Format a list that starts with "- ". 1652 1653By default, "b:#" is included. This means that a line that starts with 1654"#include" is not recognized as a comment line. But a line that starts with 1655"# define" is recognized. This is a compromise. 1656 1657 *fo-table* 1658You can use the 'formatoptions' option to influence how Vim formats text. 1659'formatoptions' is a string that can contain any of the letters below. The 1660default setting is "tcq". You can separate the option letters with commas for 1661readability. 1662 1663letter meaning when present in 'formatoptions' ~ 1664 *fo-t* 1665t Auto-wrap text using textwidth 1666 *fo-c* 1667c Auto-wrap comments using textwidth, inserting the current comment 1668 leader automatically. 1669 *fo-r* 1670r Automatically insert the current comment leader after hitting 1671 <Enter> in Insert mode. 1672 *fo-o* 1673o Automatically insert the current comment leader after hitting 'o' or 1674 'O' in Normal mode. 1675 *fo-q* 1676q Allow formatting of comments with "gq". 1677 Note that formatting will not change blank lines or lines containing 1678 only the comment leader. A new paragraph starts after such a line, 1679 or when the comment leader changes. 1680 *fo-w* 1681w Trailing white space indicates a paragraph continues in the next line. 1682 A line that ends in a non-white character ends a paragraph. 1683 *fo-a* 1684a Automatic formatting of paragraphs. Every time text is inserted or 1685 deleted the paragraph will be reformatted. See |auto-format|. 1686 When the 'c' flag is present this only happens for recognized 1687 comments. 1688 *fo-n* 1689n When formatting text, recognize numbered lists. This actually uses 1690 the 'formatlistpat' option, thus any kind of list can be used. The 1691 indent of the text after the number is used for the next line. The 1692 default is to find a number, optionally followed by '.', ':', ')', 1693 ']' or '}'. Note that 'autoindent' must be set too. Doesn't work 1694 well together with "2". 1695 Example: > 1696 1. the first item 1697 wraps 1698 2. the second item 1699< *fo-2* 17002 When formatting text, use the indent of the second line of a paragraph 1701 for the rest of the paragraph, instead of the indent of the first 1702 line. This supports paragraphs in which the first line has a 1703 different indent than the rest. Note that 'autoindent' must be set 1704 too. Example: > 1705 first line of a paragraph 1706 second line of the same paragraph 1707 third line. 1708< This also works inside comments, ignoring the comment leader. 1709 *fo-v* 1710v Vi-compatible auto-wrapping in insert mode: Only break a line at a 1711 blank that you have entered during the current insert command. (Note: 1712 this is not 100% Vi compatible. Vi has some "unexpected features" or 1713 bugs in this area. It uses the screen column instead of the line 1714 column.) 1715 *fo-b* 1716b Like 'v', but only auto-wrap if you enter a blank at or before 1717 the wrap margin. If the line was longer than 'textwidth' when you 1718 started the insert, or you do not enter a blank in the insert before 1719 reaching 'textwidth', Vim does not perform auto-wrapping. 1720 *fo-l* 1721l Long lines are not broken in insert mode: When a line was longer than 1722 'textwidth' when the insert command started, Vim does not 1723 automatically format it. 1724 *fo-m* 1725m Also break at a multibyte character above 255. This is useful for 1726 Asian text where every character is a word on its own. 1727 *fo-M* 1728M When joining lines, don't insert a space before or after a multibyte 1729 character. Overrules the 'B' flag. 1730 *fo-B* 1731B When joining lines, don't insert a space between two multibyte 1732 characters. Overruled by the 'M' flag. 1733 *fo-1* 17341 Don't break a line after a one-letter word. It's broken before it 1735 instead (if possible). 1736 *fo-]* 1737] Respect textwidth rigorously. With this flag set, no line can be 1738 longer than textwidth, unless line-break-prohibition rules make this 1739 impossible. Mainly for CJK scripts and works only if 'encoding' is 1740 "utf-8". 1741 *fo-j* 1742j Where it makes sense, remove a comment leader when joining lines. For 1743 example, joining: 1744 int i; // the index ~ 1745 // in the list ~ 1746 Becomes: 1747 int i; // the index in the list ~ 1748 *fo-p* 1749p Don't break lines at single spaces that follow periods. This is 1750 intended to complement 'joinspaces' and |cpo-J|, for prose with 1751 sentences separated by two spaces. For example, with 'textwidth' set 1752 to 28: > 1753 Surely you're joking, Mr. Feynman! 1754< Becomes: > 1755 Surely you're joking, 1756 Mr. Feynman! 1757< Instead of: > 1758 Surely you're joking, Mr. 1759 Feynman! 1760 1761 1762With 't' and 'c' you can specify when Vim performs auto-wrapping: 1763value action ~ 1764"" no automatic formatting (you can use "gq" for manual formatting) 1765"t" automatic formatting of text, but not comments 1766"c" automatic formatting for comments, but not text (good for C code) 1767"tc" automatic formatting for text and comments 1768 1769Note that when 'textwidth' is 0, Vim does no automatic formatting anyway (but 1770does insert comment leaders according to the 'comments' option). An exception 1771is when the 'a' flag is present. |auto-format| 1772 1773Note that when 'paste' is on, Vim does no formatting at all. 1774 1775Note that 'textwidth' can be non-zero even if Vim never performs auto-wrapping; 1776'textwidth' is still useful for formatting with "gq". 1777 1778If the 'comments' option includes "/*", "*" and/or "*/", then Vim has some 1779built in stuff to treat these types of comments a bit more cleverly. 1780Opening a new line before or after "/*" or "*/" (with 'r' or 'o' present in 1781'formatoptions') gives the correct start of the line automatically. The same 1782happens with formatting and auto-wrapping. Opening a line after a line 1783starting with "/*" or "*" and containing "*/", will cause no comment leader to 1784be inserted, and the indent of the new line is taken from the line containing 1785the start of the comment. 1786E.g.: 1787 /* ~ 1788 * Your typical comment. ~ 1789 */ ~ 1790 The indent on this line is the same as the start of the above 1791 comment. 1792 1793All of this should be really cool, especially in conjunction with the new 1794:autocmd command to prepare different settings for different types of file. 1795 1796Some examples: 1797 for C code (only format comments): > 1798 :set fo=croq 1799< for Mail/news (format all, don't start comment with "o" command): > 1800 :set fo=tcrq 1801< 1802 1803Automatic formatting *auto-format* *autoformat* 1804 1805When the 'a' flag is present in 'formatoptions' text is formatted 1806automatically when inserting text or deleting text. This works nicely for 1807editing text paragraphs. A few hints on how to use this: 1808 1809- You need to properly define paragraphs. The simplest is paragraphs that are 1810 separated by a blank line. When there is no separating blank line, consider 1811 using the 'w' flag and adding a space at the end of each line in the 1812 paragraphs except the last one. 1813 1814- You can set the 'formatoptions' based on the type of file |filetype| or 1815 specifically for one file with a |modeline|. 1816 1817- Set 'formatoptions' to "aw2tq" to make text with indents like this: 1818 1819 bla bla foobar bla 1820 bla foobar bla foobar bla 1821 bla bla foobar bla 1822 bla foobar bla bla foobar 1823 1824- Add the 'c' flag to only auto-format comments. Useful in source code. 1825 1826- Set 'textwidth' to the desired width. If it is zero then 79 is used, or the 1827 width of the screen if this is smaller. 1828 1829And a few warnings: 1830 1831- When part of the text is not properly separated in paragraphs, making 1832 changes in this text will cause it to be formatted anyway. Consider doing > 1833 1834 :set fo-=a 1835 1836- When using the 'w' flag (trailing space means paragraph continues) and 1837 deleting the last line of a paragraph with |dd|, the paragraph will be 1838 joined with the next one. 1839 1840- Changed text is saved for undo. Formatting is also a change. Thus each 1841 format action saves text for undo. This may consume quite a lot of memory. 1842 1843- Formatting a long paragraph and/or with complicated indenting may be slow. 1844 1845============================================================================== 18467. Sorting text *sorting* 1847 1848Vim has a sorting function and a sorting command. The sorting function can be 1849found here: |sort()|, |uniq()|. 1850 1851 *:sor* *:sort* 1852:[range]sor[t][!] [b][f][i][l][n][o][r][u][x] [/{pattern}/] 1853 Sort lines in [range]. When no range is given all 1854 lines are sorted. 1855 1856 With [!] the order is reversed. 1857 1858 With [i] case is ignored. 1859 1860 With [l] sort uses the current collation locale. 1861 Implementation details: strcoll() is used to compare 1862 strings. See |:language| to check or set the collation 1863 locale. Example: > 1864 :language collate en_US.UTF-8 1865 :%sort l 1866< |v:collate| can also used to check the current locale. 1867 Sorting using the locale typically ignores case. 1868 This does not work properly on Mac. 1869 1870 Options [n][f][x][o][b] are mutually exclusive. 1871 1872 With [n] sorting is done on the first decimal number 1873 in the line (after or inside a {pattern} match). 1874 One leading '-' is included in the number. 1875 1876 With [f] sorting is done on the Float in the line. 1877 The value of Float is determined similar to passing 1878 the text (after or inside a {pattern} match) to 1879 str2float() function. This option is available only 1880 if Vim was compiled with Floating point support. 1881 1882 With [x] sorting is done on the first hexadecimal 1883 number in the line (after or inside a {pattern} 1884 match). A leading "0x" or "0X" is ignored. 1885 One leading '-' is included in the number. 1886 1887 With [o] sorting is done on the first octal number in 1888 the line (after or inside a {pattern} match). 1889 1890 With [b] sorting is done on the first binary number in 1891 the line (after or inside a {pattern} match). 1892 1893 With [u] (u stands for unique) only keep the first of 1894 a sequence of identical lines (ignoring case when [i] 1895 is used). Without this flag, a sequence of identical 1896 lines will be kept in their original order. 1897 Note that leading and trailing white space may cause 1898 lines to be different. 1899 1900 When /{pattern}/ is specified and there is no [r] flag 1901 the text matched with {pattern} is skipped, so that 1902 you sort on what comes after the match. 1903 'ignorecase' applies to the pattern, but 'smartcase' 1904 is not used. 1905 Instead of the slash any non-letter can be used. 1906 For example, to sort on the second comma-separated 1907 field: > 1908 :sort /[^,]*,/ 1909< To sort on the text at virtual column 10 (thus 1910 ignoring the difference between tabs and spaces): > 1911 :sort /.*\%10v/ 1912< To sort on the first number in the line, no matter 1913 what is in front of it: > 1914 :sort /.\{-}\ze\d/ 1915< (Explanation: ".\{-}" matches any text, "\ze" sets the 1916 end of the match and \d matches a digit.) 1917 With [r] sorting is done on the matching {pattern} 1918 instead of skipping past it as described above. 1919 For example, to sort on only the first three letters 1920 of each line: > 1921 :sort /\a\a\a/ r 1922 1923< If a {pattern} is used, any lines which don't have a 1924 match for {pattern} are kept in their current order, 1925 but separate from the lines which do match {pattern}. 1926 If you sorted in reverse, they will be in reverse 1927 order after the sorted lines, otherwise they will be 1928 in their original order, right before the sorted 1929 lines. 1930 1931 If {pattern} is empty (e.g. // is specified), the 1932 last search pattern is used. This allows trying out 1933 a pattern first. 1934 1935Note that using `:sort` with `:global` doesn't sort the matching lines, it's 1936quite useless. 1937 1938`:sort` does not use the current locale unless the l flag is used. 1939Vim does do a "stable" sort. 1940 1941The sorting can be interrupted, but if you interrupt it too late in the 1942process you may end up with duplicated lines. This also depends on the system 1943library function used. 1944 1945 vim:tw=78:ts=8:noet:ft=help:norl: 1946