Bram Moolenaar | e518052 | 2005-12-10 20:19:46 +0000 | [diff] [blame] | 1 | *change.txt* For Vim version 7.0aa. Last change: 2005 Dec 10 |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 2 | |
| 3 | |
| 4 | VIM REFERENCE MANUAL by Bram Moolenaar |
| 5 | |
| 6 | |
| 7 | This file describes commands that delete or change text. In this context, |
| 8 | changing text means deleting the text and replacing it with other text using |
| 9 | one command. You can undo all of these commands. You can repeat the non-Ex |
| 10 | commands with the "." command. |
| 11 | |
| 12 | 1. Deleting text |deleting| |
| 13 | 2. Delete and insert |delete-insert| |
| 14 | 3. Simple changes |simple-change| *changing* |
| 15 | 4. Complex changes |complex-change| |
Bram Moolenaar | 47136d7 | 2004-10-12 20:02:24 +0000 | [diff] [blame] | 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| |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 20 | 5. Copying and moving text |copy-move| |
| 21 | 6. Formatting text |formatting| |
Bram Moolenaar | 2389c3c | 2005-05-22 22:07:59 +0000 | [diff] [blame] | 22 | 7. Sorting text |sorting| |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 23 | |
| 24 | For inserting text see |insert.txt|. |
| 25 | |
| 26 | ============================================================================== |
| 27 | 1. 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). {Vi does not support <Del>} |
| 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|) |
Bram Moolenaar | 4399ef4 | 2005-02-12 14:29:27 +0000 | [diff] [blame] | 56 | When the '#' flag is in 'cpoptions' the count is |
| 57 | ignored. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 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|). {not in Vi} |
| 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. {not in Vi} |
| 73 | |
| 74 | *:d* *:de* *:del* *:delete* |
| 75 | :[range]d[elete] [x] Delete [range] lines (default: current line) [into |
| 76 | register x]. |
| 77 | |
| 78 | :[range]d[elete] [x] {count} |
| 79 | Delete {count} lines, starting with [range] |
| 80 | (default: current line |cmdline-ranges|) [into |
| 81 | register x]. |
| 82 | |
| 83 | These commands delete text. You can repeat them with the "." command |
| 84 | (except ":d") and undo them. Use Visual mode to delete blocks of text. See |
| 85 | |registers| for an explanation of registers. |
| 86 | |
| 87 | An exception for the d{motion} command: If the motion is not linewise, the |
| 88 | start and end of the motion are not in the same line, and there are only |
| 89 | blanks before the start and after the end of the motion, the delete becomes |
| 90 | linewise. This means that the delete also removes the line of blanks that you |
| 91 | might expect to remain. |
| 92 | |
| 93 | Trying to delete an empty region of text (e.g., "d0" in the first column) |
| 94 | is an error when 'cpoptions' includes the 'E' flag. |
| 95 | |
| 96 | *J* |
| 97 | J Join [count] lines, with a minimum of two lines. |
| 98 | Remove the indent and insert up to two spaces (see |
| 99 | below). |
| 100 | |
| 101 | *v_J* |
| 102 | {Visual}J Join the highlighted lines, with a minimum of two |
| 103 | lines. Remove the indent and insert up to two spaces |
| 104 | (see below). {not in Vi} |
| 105 | |
| 106 | *gJ* |
| 107 | gJ Join [count] lines, with a minimum of two lines. |
| 108 | Don't insert or remove any spaces. {not in Vi} |
| 109 | |
| 110 | *v_gJ* |
| 111 | {Visual}gJ Join the highlighted lines, with a minimum of two |
| 112 | lines. Don't insert or remove any spaces. {not in |
| 113 | Vi} |
| 114 | |
| 115 | *:j* *:join* |
Bram Moolenaar | 26a60b4 | 2005-02-22 08:49:11 +0000 | [diff] [blame] | 116 | :[range]j[oin][!] [flags] |
| 117 | Join [range] lines. Same as "J", except with [!] |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 118 | the join does not insert or delete any spaces. |
| 119 | If a [range] has equal start and end values, this |
| 120 | command does nothing. The default behavior is to |
| 121 | join the current line with the line below it. |
| 122 | {not in Vi: !} |
Bram Moolenaar | 26a60b4 | 2005-02-22 08:49:11 +0000 | [diff] [blame] | 123 | See |ex-flags| for [flags]. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 124 | |
Bram Moolenaar | 26a60b4 | 2005-02-22 08:49:11 +0000 | [diff] [blame] | 125 | :[range]j[oin][!] {count} [flags] |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 126 | Join {count} lines, starting with [range] (default: |
| 127 | current line |cmdline-ranges|). Same as "J", except |
| 128 | with [!] the join does not insert or delete any |
| 129 | spaces. |
| 130 | {not in Vi: !} |
Bram Moolenaar | 26a60b4 | 2005-02-22 08:49:11 +0000 | [diff] [blame] | 131 | See |ex-flags| for [flags]. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 132 | |
| 133 | These commands delete the <EOL> between lines. This has the effect of joining |
| 134 | multiple lines into one line. You can repeat these commands (except ":j") and |
| 135 | undo them. |
| 136 | |
| 137 | These commands, except "gJ", insert one space in place of the <EOL> unless |
| 138 | there is trailing white space or the next line starts with a ')'. These |
| 139 | commands, except "gJ", delete any leading white space on the next line. If |
| 140 | the 'joinspaces' option is on, these commands insert two spaces after a '.', |
| 141 | '!' or '?' (but if 'cpoptions' includes the 'j' flag, they insert two spaces |
| 142 | only after a '.'). |
| 143 | The 'B' and 'M' flags in 'formatoptions' change the behavior for inserting |
| 144 | spaces before and after a multi-byte character |fo-table|. |
| 145 | |
| 146 | |
| 147 | ============================================================================== |
| 148 | 2. Delete and insert *delete-insert* *replacing* |
| 149 | |
| 150 | *R* |
| 151 | R Enter Replace mode: Each character you type replaces |
| 152 | an existing character, starting with the character |
| 153 | under the cursor. Repeat the entered text [count]-1 |
| 154 | times. See |Replace-mode| for more details. |
| 155 | |
| 156 | *gR* |
| 157 | gR Enter Virtual Replace mode: Each character you type |
| 158 | replaces existing characters in screen space. So a |
| 159 | <Tab> may replace several characters at once. |
| 160 | Repeat the entered text [count]-1 times. See |
| 161 | |Virtual-Replace-mode| for more details. |
| 162 | {not available when compiled without the +vreplace |
| 163 | feature} |
| 164 | |
| 165 | *c* |
| 166 | ["x]c{motion} Delete {motion} text [into register x] and start |
| 167 | insert. When 'cpoptions' includes the 'E' flag and |
| 168 | there is no text to delete (e.g., with "cTx" when the |
| 169 | cursor is just after an 'x'), an error occurs and |
| 170 | insert mode does not start (this is Vi compatible). |
| 171 | When 'cpoptions' does not include the 'E' flag, the |
| 172 | "c" command always starts insert mode, even if there |
| 173 | is no text to delete. |
| 174 | |
| 175 | *cc* |
| 176 | ["x]cc Delete [count] lines [into register x] and start |
| 177 | insert |linewise|. If 'autoindent' is on, preserve |
| 178 | the indent of the first line. |
| 179 | |
| 180 | *C* |
| 181 | ["x]C Delete from the cursor position to the end of the |
| 182 | line and [count]-1 more lines [into register x], and |
| 183 | start insert. Synonym for c$ (not |linewise|). |
| 184 | |
| 185 | *s* |
| 186 | ["x]s Delete [count] characters [into register x] and start |
| 187 | insert (s stands for Substitute). Synonym for "cl" |
| 188 | (not |linewise|). |
| 189 | |
| 190 | *S* |
| 191 | ["x]S Delete [count] lines [into register x] and start |
| 192 | insert. Synonym for "cc" |linewise|. |
| 193 | |
| 194 | {Visual}["x]c or *v_c* *v_s* |
| 195 | {Visual}["x]s Delete the highlighted text [into register x] and |
| 196 | start insert (for {Visual} see |Visual-mode|). {not |
| 197 | in Vi} |
| 198 | |
| 199 | *v_r* |
| 200 | {Visual}["x]r{char} Replace all selected characters by {char}. |
| 201 | |
| 202 | *v_C* |
| 203 | {Visual}["x]C Delete the highlighted lines [into register x] and |
| 204 | start insert. In Visual block mode it works |
| 205 | differently |v_b_C|. {not in Vi} |
| 206 | *v_S* |
| 207 | {Visual}["x]S Delete the highlighted lines [into register x] and |
| 208 | start insert (for {Visual} see |Visual-mode|). {not |
| 209 | in Vi} |
| 210 | *v_R* |
| 211 | {Visual}["x]R Currently just like {Visual}["x]S. In a next version |
| 212 | it might work differently. {not in Vi} |
| 213 | |
| 214 | Notes: |
| 215 | - You can end Insert and Replace mode with <Esc>. |
| 216 | - See the section "Insert and Replace mode" |mode-ins-repl| for the other |
| 217 | special characters in these modes. |
| 218 | - The effect of [count] takes place after Vim exits Insert or Replace mode. |
| 219 | - When the 'cpoptions' option contains '$' and the change is within one line, |
| 220 | Vim continues to show the text to be deleted and puts a '$' at the last |
| 221 | deleted character. |
| 222 | |
| 223 | See |registers| for an explanation of registers. |
| 224 | |
| 225 | Replace mode is just like Insert mode, except that every character you enter |
| 226 | deletes one character. If you reach the end of a line, Vim appends any |
| 227 | further characters (just like Insert mode). In Replace mode, the backspace |
| 228 | key restores the original text (if there was any). (See section "Insert and |
| 229 | Replace mode" |mode-ins-repl|). |
| 230 | |
| 231 | *cw* *cW* |
| 232 | Special case: "cw" and "cW" work the same as "ce" and "cE" if the cursor is |
| 233 | on a non-blank. This is because Vim interprets "cw" as change-word, and a |
| 234 | word does not include the following white space. {Vi: "cw" when on a blank |
| 235 | followed by other blanks changes only the first blank; this is probably a |
| 236 | bug, because "dw" deletes all the blanks; use the 'w' flag in 'cpoptions' to |
| 237 | make it work like Vi anyway} |
| 238 | |
| 239 | If you prefer "cw" to include the space after a word, use this mapping: > |
| 240 | :map cw dwi |
| 241 | < |
| 242 | *:c* *:ch* *:change* |
Bram Moolenaar | 26a60b4 | 2005-02-22 08:49:11 +0000 | [diff] [blame] | 243 | :{range}c[hange][!] Replace lines of text with some different text. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 244 | Type a line containing only "." to stop replacing. |
| 245 | Without {range}, this command changes only the current |
| 246 | line. |
Bram Moolenaar | 26a60b4 | 2005-02-22 08:49:11 +0000 | [diff] [blame] | 247 | Adding [!] toggles 'autoindent' for the time this |
| 248 | command is executed. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 249 | |
| 250 | ============================================================================== |
| 251 | 3. Simple changes *simple-change* |
| 252 | |
| 253 | *r* |
| 254 | r{char} Replace the character under the cursor with {char}. |
| 255 | If {char} is a <CR> or <NL>, a line break replaces the |
| 256 | character. To replace with a real <CR>, use CTRL-V |
| 257 | <CR>. CTRL-V <NL> replaces with a <Nul>. |
| 258 | {Vi: CTRL-V <CR> still replaces with a line break, |
| 259 | cannot replace something with a <CR>} |
| 260 | If you give a [count], Vim replaces [count] characters |
| 261 | with [count] {char}s. When {char} is a <CR> or <NL>, |
| 262 | however, Vim inserts only one <CR>: "5r<CR>" replaces |
| 263 | five characters with a single line break. |
| 264 | When {char} is a <CR> or <NL>, Vim performs |
| 265 | autoindenting. This works just like deleting the |
| 266 | characters that are replaced and then doing |
| 267 | "i<CR><Esc>". |
| 268 | {char} can be entered as a digraph |digraph-arg|. |
| 269 | |:lmap| mappings apply to {char}. The CTRL-^ command |
| 270 | in Insert mode can be used to switch this on/off |
| 271 | |i_CTRL-^|. See |utf-8-char-arg| about using |
| 272 | composing characters when 'encoding' is Unicode. |
| 273 | |
| 274 | *gr* |
| 275 | gr{char} Replace the virtual characters under the cursor with |
| 276 | {char}. This replaces in screen space, not file |
| 277 | space. See |gR| and |Virtual-Replace-mode| for more |
| 278 | details. As with |r| a count may be given. |
| 279 | {char} can be entered like with |r|. |
| 280 | {not available when compiled without the +vreplace |
| 281 | feature} |
| 282 | |
| 283 | *digraph-arg* |
| 284 | The argument for Normal mode commands like |r| and |t| is a single character. |
| 285 | When 'cpo' doesn't contain the 'D' flag, this character can also be entered |
| 286 | like |digraphs|. First type CTRL-K and then the two digraph characters. |
| 287 | {not available when compiled without the |+digraphs| feature} |
| 288 | |
| 289 | *case* |
| 290 | The following commands change the case of letters. The currently active |
| 291 | |locale| is used. See |:language|. The LC_CTYPE value matters here. |
| 292 | |
| 293 | *~* |
| 294 | ~ 'notildeop' option: Switch case of the character |
| 295 | under the cursor and move the cursor to the right. |
| 296 | If a [count] is given, do that many characters. {Vi: |
| 297 | no count} |
| 298 | |
| 299 | ~{motion} 'tildeop' option: switch case of {motion} text. {Vi: |
| 300 | tilde cannot be used as an operator} |
| 301 | |
| 302 | *g~* |
| 303 | g~{motion} Switch case of {motion} text. {not in Vi} |
| 304 | |
| 305 | g~g~ *g~g~* *g~~* |
| 306 | g~~ Switch case of current line. {not in Vi}. |
| 307 | |
| 308 | *v_~* |
| 309 | {Visual}~ Switch case of highlighted text (for {Visual} see |
| 310 | |Visual-mode|). {not in Vi} |
| 311 | |
| 312 | *v_U* |
| 313 | {Visual}U Make highlighted text uppercase (for {Visual} see |
| 314 | |Visual-mode|). {not in Vi} |
| 315 | |
| 316 | *gU* *uppercase* |
| 317 | gU{motion} Make {motion} text uppercase. {not in Vi} |
| 318 | Example: > |
| 319 | :map! <C-F> <Esc>gUiw`]a |
| 320 | < This works in Insert mode: press CTRL-F to make the |
| 321 | word before the cursor uppercase. Handy to type |
| 322 | words in lowercase and then make them uppercase. |
| 323 | |
| 324 | |
| 325 | gUgU *gUgU* *gUU* |
| 326 | gUU Make current line uppercase. {not in Vi}. |
| 327 | |
| 328 | *v_u* |
| 329 | {Visual}u Make highlighted text lowercase (for {Visual} see |
| 330 | |Visual-mode|). {not in Vi} |
| 331 | |
| 332 | *gu* *lowercase* |
| 333 | gu{motion} Make {motion} text lowercase. {not in Vi} |
| 334 | |
| 335 | gugu *gugu* *guu* |
| 336 | guu Make current line lowercase. {not in Vi}. |
| 337 | |
| 338 | *g?* *rot13* |
| 339 | g?{motion} Rot13 encode {motion} text. {not in Vi} |
| 340 | |
| 341 | *v_g?* |
| 342 | {Visual}g? Rot13 encode the highlighted text (for {Visual} see |
| 343 | |Visual-mode|). {not in Vi} |
| 344 | |
| 345 | g?g? *g?g?* *g??* |
| 346 | g?? Rot13 encode current line. {not in Vi}. |
| 347 | |
| 348 | |
| 349 | Adding and subtracting ~ |
| 350 | *CTRL-A* |
| 351 | CTRL-A Add [count] to the number or alphabetic character at |
| 352 | or after the cursor. {not in Vi} |
| 353 | |
| 354 | *CTRL-X* |
| 355 | CTRL-X Subtract [count] from the number or alphabetic |
| 356 | character at or after the cursor. {not in Vi} |
| 357 | |
| 358 | The CTRL-A and CTRL-X commands work for (signed) decimal numbers, unsigned |
| 359 | octal and hexadecimal numbers and alphabetic characters. This depends on the |
| 360 | 'nrformats' option. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 361 | - When 'nrformats' includes "octal", Vim considers numbers starting with a '0' |
Bram Moolenaar | 1cd871b | 2004-12-19 22:46:22 +0000 | [diff] [blame] | 362 | to be octal, unless the number includes a '8' or '9'. Other numbers are |
| 363 | decimal and may have a preceding minus sign. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 364 | If the cursor is on a number, the commands apply to that number; otherwise |
| 365 | Vim uses the number to the right of the cursor. |
Bram Moolenaar | 293ee4d | 2004-12-09 21:34:53 +0000 | [diff] [blame] | 366 | - When 'nrformats' includes "hex", Vim assumes numbers starting with '0x' or |
| 367 | '0X' are hexadecimal. The case of the rightmost letter in the number |
| 368 | determines the case of the resulting hexadecimal number. If there is no |
| 369 | letter in the current number, Vim uses the previously detected case. |
| 370 | - When 'nrformats' includes "alpha", Vim will change the alphabetic character |
| 371 | under or after the cursor. This is useful to make lists with an alphabetic |
| 372 | index. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 373 | |
| 374 | For numbers with leading zeros (including all octal and hexadecimal numbers), |
| 375 | Vim preserves the number of characters in the number when possible. CTRL-A on |
Bram Moolenaar | 293ee4d | 2004-12-09 21:34:53 +0000 | [diff] [blame] | 376 | "0077" results in "0100", CTRL-X on "0x100" results in "0x0ff". |
Bram Moolenaar | 1cd871b | 2004-12-19 22:46:22 +0000 | [diff] [blame] | 377 | There is one exception: When a number that starts with a zero is found not to |
| 378 | be octal (it contains a '8' or '9'), but 'nrformats' does include "octal", |
| 379 | leading zeros are removed to avoid that the result may be recognized as an |
| 380 | octal number. |
Bram Moolenaar | 293ee4d | 2004-12-09 21:34:53 +0000 | [diff] [blame] | 381 | |
| 382 | Note that when 'nrformats' includes "octal", decimal numbers with leading |
Bram Moolenaar | 1cd871b | 2004-12-19 22:46:22 +0000 | [diff] [blame] | 383 | zeros cause mistakes, because they can be confused with octal numbers. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 384 | |
| 385 | The CTRL-A command is very useful in a macro. Example: Use the following |
| 386 | steps to make a numbered list. |
| 387 | |
| 388 | 1. Create the first list entry, make sure it starts with a number. |
Bram Moolenaar | d8b0273 | 2005-01-14 21:48:43 +0000 | [diff] [blame] | 389 | 2. qa - start recording into register 'a' |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 390 | 3. Y - yank the entry |
| 391 | 4. p - put a copy of the entry below the first one |
| 392 | 5. CTRL-A - increment the number |
| 393 | 6. q - stop recording |
| 394 | 7. <count>@a - repeat the yank, put and increment <count> times |
| 395 | |
| 396 | |
| 397 | SHIFTING LINES LEFT OR RIGHT *shift-left-right* |
| 398 | |
| 399 | *<* |
| 400 | <{motion} Shift {motion} lines one 'shiftwidth' leftwards. |
| 401 | |
| 402 | *<<* |
| 403 | << Shift [count] lines one 'shiftwidth' leftwards. |
| 404 | |
| 405 | *v_<* |
| 406 | {Visual}[count]< Shift the highlighted lines [count] 'shiftwidth' |
| 407 | leftwards (for {Visual} see |Visual-mode|). {not in |
| 408 | Vi} |
| 409 | |
| 410 | *>* |
| 411 | >{motion} Shift {motion} lines one 'shiftwidth' rightwards. |
| 412 | |
| 413 | *>>* |
| 414 | >> Shift [count] lines one 'shiftwidth' rightwards. |
| 415 | |
| 416 | *v_>* |
| 417 | {Visual}[count]> Shift the highlighted lines [count] 'shiftwidth' |
| 418 | rightwards (for {Visual} see |Visual-mode|). {not in |
| 419 | Vi} |
| 420 | |
| 421 | *:<* |
| 422 | :[range]< Shift [range] lines one 'shiftwidth' left. Repeat '<' |
| 423 | for shifting multiple 'shiftwidth's. |
| 424 | |
| 425 | :[range]< {count} Shift {count} lines one 'shiftwidth' left, starting |
| 426 | with [range] (default current line |cmdline-ranges|). |
| 427 | Repeat '<' for shifting multiple 'shiftwidth's. |
| 428 | |
| 429 | :[range]le[ft] [indent] left align lines in [range]. Sets the indent in the |
| 430 | lines to [indent] (default 0). {not in Vi} |
| 431 | |
| 432 | *:>* |
Bram Moolenaar | 26a60b4 | 2005-02-22 08:49:11 +0000 | [diff] [blame] | 433 | :[range]> [flags] Shift {count} [range] lines one 'shiftwidth' right. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 434 | Repeat '>' for shifting multiple 'shiftwidth's. |
Bram Moolenaar | 26a60b4 | 2005-02-22 08:49:11 +0000 | [diff] [blame] | 435 | See |ex-flags| for [flags]. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 436 | |
Bram Moolenaar | 26a60b4 | 2005-02-22 08:49:11 +0000 | [diff] [blame] | 437 | :[range]> {count} [flags] |
| 438 | Shift {count} lines one 'shiftwidth' right, starting |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 439 | with [range] (default current line |cmdline-ranges|). |
| 440 | Repeat '>' for shifting multiple 'shiftwidth's. |
Bram Moolenaar | 26a60b4 | 2005-02-22 08:49:11 +0000 | [diff] [blame] | 441 | See |ex-flags| for [flags]. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 442 | |
| 443 | The ">" and "<" commands are handy for changing the indentation within |
| 444 | programs. Use the 'shiftwidth' option to set the size of the white space |
| 445 | which these commands insert or delete. Normally the 'shiftwidth' option is 8, |
| 446 | but you can set it to, say, 3 to make smaller indents. The shift leftwards |
| 447 | stops when there is no indent. The shift right does not affect empty lines. |
| 448 | |
| 449 | If the 'shiftround' option is on, the indent is rounded to a multiple of |
| 450 | 'shiftwidth'. |
| 451 | |
| 452 | If the 'smartindent' option is on, or 'cindent' is on and 'cinkeys' contains |
| 453 | '#', shift right does not affect lines starting with '#' (these are supposed |
| 454 | to be C preprocessor lines that must stay in column 1). |
| 455 | |
| 456 | When the 'expandtab' option is off (this is the default) Vim uses <Tab>s as |
| 457 | much as possible to make the indent. You can use ">><<" to replace an indent |
| 458 | made out of spaces with the same indent made out of <Tab>s (and a few spaces |
| 459 | if necessary). If the 'expandtab' option is on, Vim uses only spaces. Then |
| 460 | you can use ">><<" to replace <Tab>s in the indent by spaces (or use |
| 461 | ":retab!"). |
| 462 | |
| 463 | To move a line several 'shiftwidth's, use Visual mode or the ":" commands. |
| 464 | For example: > |
| 465 | Vjj4> move three lines 4 indents to the right |
| 466 | :<<< move current line 3 indents to the left |
| 467 | :>> 5 move 5 lines 2 indents to the right |
| 468 | :5>> move line 5 2 indents to the right |
| 469 | |
| 470 | ============================================================================== |
| 471 | 4. Complex changes *complex-change* |
| 472 | |
Bram Moolenaar | 47136d7 | 2004-10-12 20:02:24 +0000 | [diff] [blame] | 473 | 4.1 Filter commands *filter* |
| 474 | |
| 475 | A filter is a program that accepts text at standard input, changes it in some |
| 476 | way, and sends it to standard output. You can use the commands below to send |
| 477 | some text through a filter, so that it is replace by the filter output. |
| 478 | Examples of filters are "sort", which sorts lines alphabetically, and |
| 479 | "indent", which formats C program files (you need a version of indent that |
| 480 | works like a filter; not all versions do). The 'shell' option specifies the |
| 481 | shell Vim uses to execute the filter command (See also the 'shelltype' |
| 482 | option). You can repeat filter commands with ".". Vim does not recognize a |
| 483 | comment (starting with '"') after the ":!" command. |
| 484 | |
| 485 | *!* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 486 | !{motion}{filter} Filter {motion} text lines through the external |
| 487 | program {filter}. |
| 488 | |
| 489 | *!!* |
| 490 | !!{filter} Filter [count] lines through the external program |
| 491 | {filter}. |
| 492 | |
| 493 | *v_!* |
| 494 | {Visual}!{filter} Filter the highlighted lines through the external |
| 495 | program {filter} (for {Visual} see |Visual-mode|). |
| 496 | {not in Vi} |
| 497 | |
| 498 | :{range}![!]{filter} [!][arg] *:range!* |
| 499 | Filter {range} lines through the external program |
| 500 | {filter}. Vim replaces the optional bangs with the |
| 501 | latest given command and appends the optional [arg]. |
| 502 | Vim saves the output of the filter command in a |
| 503 | temporary file and then reads the file into the |
| 504 | buffer. Vim uses the 'shellredir' option to redirect |
| 505 | the filter output to the temporary file. |
| 506 | When the 'R' flag is included in 'cpoptions' marks in |
| 507 | the filtered lines are deleted, unless the |
| 508 | |:keepmarks| command is used. Example: > |
| 509 | :keepmarks '<,'>!sort |
| 510 | < When the number of lines after filtering is less than |
| 511 | before, marks in the missing lines are deleted anyway. |
| 512 | |
| 513 | *=* |
| 514 | ={motion} Filter {motion} lines through the external program |
| 515 | given with the 'equalprg' option. When the 'equalprg' |
| 516 | option is empty (this is the default), use the |
| 517 | internal formatting function |C-indenting|. But when |
| 518 | 'indentexpr' is not empty, it will be used instead |
| 519 | |indent-expression|. |
| 520 | |
| 521 | *==* |
| 522 | == Filter [count] lines like with ={motion}. |
| 523 | |
| 524 | *v_=* |
| 525 | {Visual}= Filter the highlighted lines like with ={motion}. |
| 526 | {not in Vi} |
| 527 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 528 | |
Bram Moolenaar | 47136d7 | 2004-10-12 20:02:24 +0000 | [diff] [blame] | 529 | 4.2 Substitute *:substitute* |
| 530 | *:s* *:su* |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 531 | :[range]s[ubstitute]/{pattern}/{string}/[flags] [count] |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 532 | For each line in [range] replace a match of {pattern} |
| 533 | with {string}. |
| 534 | For the {pattern} see |pattern|. |
| 535 | {string} can be a literal string, or something |
| 536 | special; see |sub-replace-special|. |
| 537 | When [range] and [count] are omitted, replace in the |
| 538 | current line only. |
| 539 | When [count] is given, replace in [count] lines, |
| 540 | starting with the last line in [range]. When [range] |
| 541 | is omitted start in the current line. |
| 542 | Also see |cmdline-ranges|. |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 543 | See |:s_flags| for [flags]. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 544 | |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 545 | :[range]s[ubstitute] [flags] [count] |
| 546 | :[range]&[&][flags] [count] *:&* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 547 | Repeat last :substitute with same search pattern and |
| 548 | substitute string, but without the same flags. You |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 549 | may add [flags], see |:s_flags|. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 550 | Note that after ":substitute" the '&' flag can't be |
| 551 | used, it's recognized as a pattern separator. |
| 552 | The space between ":substitute" and the 'c', 'g' and |
| 553 | 'r' flags isn't required, but in scripts it's a good |
| 554 | idea to keep it to avoid confusion. |
| 555 | |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 556 | :[range]~[&][flags] [count] *:~* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 557 | Repeat last substitute with same substitute string |
| 558 | but with last used search pattern. This is like |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 559 | ":&r". See |:s_flags| for [flags]. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 560 | |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 561 | *&* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 562 | & Synonym for ":s//~/" (repeat last substitute). Note |
| 563 | that the flags are not remembered, thus it might |
| 564 | actually work differently. You can use ":&&" to keep |
| 565 | the flags. |
| 566 | |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 567 | *g&* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 568 | g& Synonym for ":%s//~/&" (repeat last substitute on all |
| 569 | lines with the same flags). |
| 570 | Mnemonic: global substitute. {not in Vi} |
| 571 | |
| 572 | *:snomagic* *:sno* |
| 573 | :[range]sno[magic] ... Same as ":substitute", but always use 'nomagic'. |
| 574 | {not in Vi} |
| 575 | |
| 576 | *:smagic* *:sm* |
| 577 | :[range]sm[agic] ... Same as ":substitute", but always use 'magic'. |
| 578 | {not in Vi} |
| 579 | |
| 580 | *:s_flags* |
| 581 | The flags that you can use for the substitute commands: |
| 582 | |
| 583 | [&] Must be the first one: Keep the flags from the previous substitute |
| 584 | command. Examples: > |
| 585 | :&& |
| 586 | :s/this/that/& |
| 587 | < Note that ":s" and ":&" don't keep the flags. |
| 588 | {not in Vi} |
| 589 | |
| 590 | [c] Confirm each substitution. Vim highlights the matching string (with |
| 591 | |hl-IncSearch|). You can type: *:s_c* |
| 592 | 'y' to substitute this match |
| 593 | 'l' to substitute this match and then quit ("last") |
| 594 | 'n' to skip this match |
| 595 | <Esc> to quit substituting |
| 596 | 'a' to substitute this and all remaining matches {not in Vi} |
| 597 | 'q' to quit substituting {not in Vi} |
| 598 | CTRL-E to scroll the screen up {not in Vi, not available when |
| 599 | compiled without the +insert_expand feature} |
| 600 | CTRL-Y to scroll the screen down {not in Vi, not available when |
| 601 | compiled without the +insert_expand feature} |
| 602 | If the 'edcompatible' option is on, Vim remembers the [c] flag and |
| 603 | toggles it each time you use it, but resets it when you give a new |
| 604 | search pattern. |
| 605 | {not in Vi: highlighting of the match, other responses than 'y' or 'n'} |
| 606 | |
| 607 | [e] When the search pattern fails, do not issue an error message and, in |
| 608 | particular, continue in maps as if no error occurred. This is most |
| 609 | useful to prevent the "No match" error from breaking a mapping. Vim |
| 610 | does not suppress the following error messages, however: |
| 611 | Regular expressions can't be delimited by letters |
| 612 | \ should be followed by /, ? or & |
| 613 | No previous substitute regular expression |
| 614 | Trailing characters |
| 615 | Interrupted |
| 616 | {not in Vi} |
| 617 | |
| 618 | [g] Replace all occurrences in the line. Without this argument, |
| 619 | replacement occurs only for the first occurrence in each line. If |
| 620 | the 'edcompatible' option is on, Vim remembers this flag and toggles |
| 621 | it each time you use it, but resets it when you give a new search |
| 622 | pattern. If the 'gdefault' option is on, this flag is on by default |
| 623 | and the [g] argument switches it off. |
| 624 | |
| 625 | [i] Ignore case for the pattern. The 'ignorecase' and 'smartcase' options |
| 626 | are not used. |
| 627 | {not in Vi} |
| 628 | |
| 629 | [I] Don't ignore case for the pattern. The 'ignorecase' and 'smartcase' |
| 630 | options are not used. |
| 631 | {not in Vi} |
| 632 | |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 633 | [n] Report the number of matches, do not actually substitute. The [c] |
| 634 | flag is ignored. The matches are reported as if 'report' is zero. |
| 635 | Useful to |count-items|. |
| 636 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 637 | [p] Print the line containing the last substitute. |
Bram Moolenaar | 26a60b4 | 2005-02-22 08:49:11 +0000 | [diff] [blame] | 638 | |
| 639 | [#] Like [p] and prepend the line number. |
| 640 | |
| 641 | [l] Like [l] but print the text like |:list|. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 642 | |
| 643 | [r] Only useful in combination with ":&" or ":s" without arguments. ":&r" |
| 644 | works the same way as ":~": When the search pattern is empty, use the |
| 645 | previously used search pattern instead of the search pattern from the |
| 646 | last substitute or ":global". If the last command that did a search |
| 647 | was a substitute or ":global", there is no effect. If the last |
| 648 | command was a search command such as "/", use the pattern from that |
| 649 | command. |
| 650 | For ":s" with an argument this already happens: > |
| 651 | :s/blue/red/ |
| 652 | /green |
| 653 | :s//red/ or :~ or :&r |
| 654 | < The last commands will replace "green" with "red". > |
| 655 | :s/blue/red/ |
| 656 | /green |
| 657 | :& |
| 658 | < The last command will replace "blue" with "red". |
| 659 | {not in Vi} |
| 660 | |
| 661 | Note that there is no flag to change the "magicness" of the pattern. A |
| 662 | different command is used instead. The reason is that the flags can only be |
| 663 | found by skipping the pattern, and in order to skip the pattern the |
| 664 | "magicness" must be known. Catch 22! |
| 665 | |
| 666 | If the {pattern} for the substitute command is empty, the command uses the |
| 667 | pattern from the last substitute or ":global" command. With the [r] flag, the |
| 668 | command uses the pattern from the last substitute, ":global", or search |
| 669 | command. |
| 670 | |
| 671 | For compatibility with Vi these two exceptions are allowed: |
| 672 | "\/{string}/" and "\?{string}?" do the same as "//{string}/r". |
| 673 | "\&{string}&" does the same as "//{string}/". |
| 674 | *E146* |
| 675 | Instead of the '/' which surrounds the pattern and replacement string, you |
| 676 | can use any other character, but not an alphanumeric character, '\', '"' or |
| 677 | '|'. This is useful if you want to include a '/' in the search pattern or |
| 678 | replacement string. Example: > |
| 679 | :s+/+//+ |
| 680 | |
| 681 | For the definition of a pattern, see |pattern|. |
| 682 | |
| 683 | *sub-replace-special* *:s\=* |
| 684 | When the {string} starts with "\=" it is evaluated as an expression, see |
Bram Moolenaar | 5a8684e | 2005-07-30 22:43:24 +0000 | [diff] [blame] | 685 | |sub-replace-expression|. You can use that for any special characters. |
| 686 | Otherwise these characters in {string} have a special meaning: |
Bram Moolenaar | 26a60b4 | 2005-02-22 08:49:11 +0000 | [diff] [blame] | 687 | *:s%* |
| 688 | When {string} is equal to "%" and '/' is included with the 'cpotions' option, |
| 689 | then the {string} of the previous substitute command is used. |cpo-/| |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 690 | |
| 691 | magic nomagic action ~ |
| 692 | & \& replaced with the whole matched pattern *s/\&* |
| 693 | \& & replaced with & |
| 694 | \0 replaced with the whole matched pattern *\0* *s/\0* |
| 695 | \1 replaced with the matched pattern in the first |
| 696 | pair of () *s/\1* |
Bram Moolenaar | 3fdfa4a | 2004-10-07 21:02:47 +0000 | [diff] [blame] | 697 | \2 replaced with the matched pattern in the second |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 698 | pair of () *s/\2* |
| 699 | .. .. *s/\3* |
| 700 | \9 replaced with the matched pattern in the ninth |
| 701 | pair of () *s/\9* |
| 702 | ~ \~ replaced with the {string} of the previous |
| 703 | substitute *s~* |
| 704 | \~ ~ replaced with ~ *s/\~* |
| 705 | \u next character made uppercase *s/\u* |
| 706 | \U following characters made uppercase, until \E *s/\U* |
| 707 | \l next character made lowercase *s/\l* |
| 708 | \L following characters made lowercase, until \E *s/\L* |
| 709 | \e end of \u, \U, \l and \L (NOTE: not <Esc>!) *s/\e* |
| 710 | \E end of \u, \U, \l and \L *s/\E* |
| 711 | <CR> split line in two at this point |
| 712 | (Type the <CR> as CTRL-V <Enter>) *s<CR>* |
| 713 | \r idem *s/\r* |
| 714 | \<CR> insert a carriage-return (CTRL-M) |
| 715 | (Type the <CR> as CTRL-V <Enter>) *s/\<CR>* |
| 716 | \n insert a <NL> (<NUL> in the file) |
| 717 | (does NOT break the line) *s/\n* |
| 718 | \b insert a <BS> *s/\b* |
| 719 | \t insert a <Tab> *s/\t* |
| 720 | \\ insert a single backslash *s/\\* |
| 721 | \x where x is any character not mentioned above: |
| 722 | Reserved for future expansion |
| 723 | |
| 724 | Examples: > |
| 725 | :s/a\|b/xxx\0xxx/g modifies "a b" to "xxxaxxx xxxbxxx" |
| 726 | :s/\([abc]\)\([efg]\)/\2\1/g modifies "af fa bg" to "fa fa gb" |
| 727 | :s/abcde/abc^Mde/ modifies "abcde" to "abc", "de" (two lines) |
| 728 | :s/$/\^M/ modifies "abcde" to "abcde^M" |
| 729 | |
| 730 | Note: In previous versions CTRL-V was handled in a special way. Since this is |
| 731 | not Vi compatible, this was removed. Use a backslash instead. |
| 732 | |
| 733 | command text result ~ |
| 734 | :s/aa/a^Ma/ aa a<line-break>a |
| 735 | :s/aa/a\^Ma/ aa a^Ma |
| 736 | :s/aa/a\\^Ma/ aa a\<line-break>a |
| 737 | |
| 738 | (you need to type CTRL-V <CR> to get a ^M here) |
| 739 | |
| 740 | The numbering of "\1", "\2" etc. is done based on which "\(" comes first in |
| 741 | the pattern (going left to right). When a parentheses group matches several |
| 742 | times, the last one will be used for "\1", "\2", etc. Example: > |
| 743 | :s/\(\(a[a-d] \)*\)/\2/ modifies "aa ab x" to "ab x" |
| 744 | |
| 745 | When using parentheses in combination with '|', like in \([ab]\)\|\([cd]\), |
| 746 | either the first or second pattern in parentheses did not match, so either |
| 747 | \1 or \2 is empty. Example: > |
| 748 | :s/\([ab]\)\|\([cd]\)/\1x/g modifies "a b c d" to "ax bx x x" |
| 749 | < |
| 750 | |
| 751 | Substitute with an expression *sub-replace-expression* |
Bram Moolenaar | a7fc010 | 2005-05-18 22:17:12 +0000 | [diff] [blame] | 752 | *sub-replace-\=* |
| 753 | When the substitute string starts with "\=" the remainder is interpreted as an |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 754 | expression. This does not work recursively: a substitute() function inside |
| 755 | the expression cannot use "\=" for the substitute string. |
| 756 | |
| 757 | The special meaning for characters as mentioned at |sub-replace-special| does |
| 758 | not apply except "<CR>", "\<CR>" and "\\". Thus in the result of the |
| 759 | expression you need to use two backslashes get one, put a backslash before a |
| 760 | <CR> you want to insert and use a <CR> without a backslash where you want to |
| 761 | break the line. |
| 762 | |
| 763 | For convenience a <NL> character is also used as a line break. Prepend a |
| 764 | backslash to get a real <NL> character (which will be a NUL in the file). |
| 765 | |
| 766 | The whole matched text can be accessed with "submatch(0)". The text matched |
| 767 | with the first pair of () with "submatch(1)". Likewise for further |
| 768 | sub-matches in (). |
| 769 | |
| 770 | Be careful: The separation character must not appear in the expression! |
| 771 | Consider using a character like "@" or ":". There is no problem if the result |
| 772 | of the expression contains the separation character. |
| 773 | |
Bram Moolenaar | 5a8684e | 2005-07-30 22:43:24 +0000 | [diff] [blame] | 774 | Examples: > |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 775 | :s@\n@\="\r" . expand("$HOME") . "\r"@ |
Bram Moolenaar | 5a8684e | 2005-07-30 22:43:24 +0000 | [diff] [blame] | 776 | This replaces an end-of-line with a new line containing the value of $HOME. > |
| 777 | |
| 778 | s/E/\="\<Char-0x20ac>"/g |
| 779 | This replaces 'E' characters with an euro sign. Read more in |<Char->|. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 780 | |
| 781 | |
Bram Moolenaar | 47136d7 | 2004-10-12 20:02:24 +0000 | [diff] [blame] | 782 | 4.3 Search and replace *search-replace* |
| 783 | |
| 784 | *:pro* *:promptfind* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 785 | :promptf[ind] [string] |
| 786 | Put up a Search dialog. When [string] is given, it is |
| 787 | used as the initial search string. |
| 788 | {only for Win32, Motif and GTK GUI} |
| 789 | |
| 790 | *:promptr* *:promptrepl* |
| 791 | :promptr[epl] [string] |
| 792 | Put up a Search/Replace dialog. When [string] is |
| 793 | given, it is used as the initial search string. |
| 794 | {only for Win32, Motif and GTK GUI} |
| 795 | |
Bram Moolenaar | 47136d7 | 2004-10-12 20:02:24 +0000 | [diff] [blame] | 796 | |
| 797 | 4.4 Changing tabs *change-tabs* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 798 | *:ret* *:retab* |
| 799 | :[range]ret[ab][!] [new_tabstop] |
| 800 | Replace all sequences of white-space containing a |
| 801 | <Tab> with new strings of white-space using the new |
| 802 | tabstop value given. If you do not specify a new |
| 803 | tabstop size or it is zero, Vim uses the current value |
| 804 | of 'tabstop'. |
| 805 | The current value of 'tabstop' is always used to |
| 806 | compute the width of existing tabs. |
| 807 | With !, Vim also replaces strings of only normal |
| 808 | spaces with tabs where appropriate. |
| 809 | With 'expandtab' on, Vim replaces all tabs with the |
| 810 | appropriate number of spaces. |
| 811 | This command sets 'tabstop' to the new value given, |
| 812 | and if performed on the whole file, which is default, |
| 813 | should not make any visible change. |
| 814 | Careful: This command modifies any <Tab> characters |
| 815 | inside of strings in a C program. Use "\t" to avoid |
| 816 | this (that's a good habit anyway). |
| 817 | ":retab!" may also change a sequence of spaces by |
| 818 | <Tab> characters, which can mess up a printf(). |
| 819 | {not in Vi} |
| 820 | Not available when |+ex_extra| feature was disabled at |
| 821 | compile time. |
| 822 | |
| 823 | *retab-example* |
| 824 | Example for using autocommands and ":retab" to edit a file which is stored |
| 825 | with tabstops at 8 but edited with tabstops set at 4. Warning: white space |
| 826 | inside of strings can change! Also see 'softtabstop' option. > |
| 827 | |
| 828 | :auto BufReadPost *.xx retab! 4 |
| 829 | :auto BufWritePre *.xx retab! 8 |
| 830 | :auto BufWritePost *.xx retab! 4 |
| 831 | :auto BufNewFile *.xx set ts=4 |
| 832 | |
| 833 | ============================================================================== |
| 834 | 5. Copying and moving text *copy-move* |
| 835 | |
| 836 | *quote* |
| 837 | "{a-zA-Z0-9.%#:-"} Use register {a-zA-Z0-9.%#:-"} for next delete, yank |
| 838 | or put (use uppercase character to append with |
| 839 | delete and yank) ({.%#:} only work with put). |
| 840 | |
| 841 | *:reg* *:registers* |
| 842 | :reg[isters] Display the contents of all numbered and named |
| 843 | registers. {not in Vi} |
| 844 | |
| 845 | :reg[isters] {arg} Display the contents of the numbered and named |
| 846 | registers that are mentioned in {arg}. For example: > |
| 847 | :dis 1a |
| 848 | < to display registers '1' and 'a'. Spaces are allowed |
| 849 | in {arg}. {not in Vi} |
| 850 | |
| 851 | *:di* *:display* |
| 852 | :di[splay] [arg] Same as :registers. {not in Vi} |
| 853 | |
| 854 | *y* *yank* |
| 855 | ["x]y{motion} Yank {motion} text [into register x]. When no |
| 856 | characters are to be yanked (e.g., "y0" in column 1), |
| 857 | this is an error when 'cpoptions' includes the 'E' |
| 858 | flag. |
| 859 | |
| 860 | *yy* |
| 861 | ["x]yy Yank [count] lines [into register x] |linewise|. |
| 862 | |
| 863 | *Y* |
| 864 | ["x]Y yank [count] lines [into register x] (synonym for |
| 865 | yy, |linewise|). If you like "Y" to work from the |
| 866 | cursor to the end of line (which is more logical, |
| 867 | but not Vi-compatible) use ":map Y y$". |
| 868 | |
| 869 | *v_y* |
| 870 | {Visual}["x]y Yank the highlighted text [into register x] (for |
| 871 | {Visual} see |Visual-mode|). {not in Vi} |
| 872 | |
| 873 | *v_Y* |
| 874 | {Visual}["x]Y Yank the highlighted lines [into register x] (for |
| 875 | {Visual} see |Visual-mode|). {not in Vi} |
| 876 | |
| 877 | *:y* *:yank* |
| 878 | :[range]y[ank] [x] Yank [range] lines [into register x]. |
| 879 | |
| 880 | :[range]y[ank] [x] {count} |
| 881 | Yank {count} lines, starting with last line number |
| 882 | in [range] (default: current line |cmdline-ranges|), |
| 883 | [into register x]. |
| 884 | |
| 885 | *p* *put* *E353* |
| 886 | ["x]p Put the text [from register x] after the cursor |
| 887 | [count] times. {Vi: no count} |
| 888 | |
| 889 | *P* |
| 890 | ["x]P Put the text [from register x] before the cursor |
| 891 | [count] times. {Vi: no count} |
| 892 | |
| 893 | *<MiddleMouse>* |
| 894 | ["x]<MiddleMouse> Put the text from a register before the cursor [count] |
| 895 | times. Uses the "* register, unless another is |
Bram Moolenaar | 293ee4d | 2004-12-09 21:34:53 +0000 | [diff] [blame] | 896 | specified. |
| 897 | Leaves the cursor at the end of the new text. |
| 898 | Using the mouse only works when 'mouse' contains 'n' |
| 899 | or 'a'. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 900 | {not in Vi} |
| 901 | If you have a scrollwheel and often accidentally paste |
| 902 | text, you can use these mappings to disable the |
| 903 | pasting with the middle mouse button: > |
| 904 | :map <MiddleMouse> <Nop> |
| 905 | :imap <MiddleMouse> <Nop> |
| 906 | < You might want to disable the multi-click versions |
| 907 | too, see |double-click|. |
| 908 | |
| 909 | *gp* |
| 910 | ["x]gp Just like "p", but leave the cursor just after the new |
| 911 | text. {not in Vi} |
| 912 | |
| 913 | *gP* |
| 914 | ["x]gP Just like "P", but leave the cursor just after the new |
| 915 | text. {not in Vi} |
| 916 | |
| 917 | *:pu* *:put* |
| 918 | :[line]pu[t] [x] Put the text [from register x] after [line] (default |
| 919 | current line). This always works |linewise|, thus |
| 920 | this command can be used to put a yanked block as new |
| 921 | lines. |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 922 | The cursor is left on the first non-blank in the last |
| 923 | new line. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 924 | The register can also be '=' followed by an optional |
| 925 | expression. The expression continues until the end of |
| 926 | the command. You need to escape the '|' and '"' |
| 927 | characters to prevent them from terminating the |
| 928 | command. Example: > |
| 929 | :put ='path' . \",/test\" |
| 930 | < If there is no expression after '=', Vim uses the |
| 931 | previous expression. You can see it with ":dis =". |
| 932 | |
| 933 | :[line]pu[t]! [x] Put the text [from register x] before [line] (default |
| 934 | current line). |
| 935 | |
| 936 | ["x]]p or *]p* *]<MiddleMouse>* |
| 937 | ["x]]<MiddleMouse> Like "p", but adjust the indent to the current line. |
| 938 | Using the mouse only works when 'mouse' contains 'n' |
| 939 | or 'a'. {not in Vi} |
| 940 | |
| 941 | ["x][P or *[P* |
| 942 | ["x]]P or *]P* |
| 943 | ["x][p or *[p* *[<MiddleMouse>* |
| 944 | ["x][<MiddleMouse> Like "P", but adjust the indent to the current line. |
| 945 | Using the mouse only works when 'mouse' contains 'n' |
| 946 | or 'a'. {not in Vi} |
| 947 | |
| 948 | You can use these commands to copy text from one place to another. Do this |
| 949 | by first getting the text into a register with a yank, delete or change |
| 950 | command, then inserting the register contents with a put command. You can |
| 951 | also use these commands to move text from one file to another, because Vim |
| 952 | preserves all registers when changing buffers (the CTRL-^ command is a quick |
| 953 | way to toggle between two files). |
| 954 | |
| 955 | *linewise-register* *characterwise-register* |
| 956 | You can repeat the put commands with "." (except for :put) and undo them. If |
| 957 | the command that was used to get the text into the register was |linewise|, |
| 958 | Vim inserts the text below ("p") or above ("P") the line where the cursor is. |
| 959 | Otherwise Vim inserts the text after ("p") or before ("P") the cursor. With |
| 960 | the ":put" command, Vim always inserts the text in the next line. You can |
| 961 | exchange two characters with the command sequence "xp". You can exchange two |
| 962 | lines with the command sequence "ddp". You can exchange two words with the |
| 963 | command sequence "deep" (start with the cursor in the blank space before the |
| 964 | first word). You can use the "']" or "`]" command after the put command to |
| 965 | move the cursor to the end of the inserted text, or use "'[" or "`[" to move |
| 966 | the cursor to the start. |
| 967 | |
| 968 | *put-Visual-mode* *v_p* *v_P* |
| 969 | When using a put command like |p| or |P| in Visual mode, Vim will try to |
| 970 | replace the selected text with the contents of the register. Whether this |
| 971 | works well depends on the type of selection and the type of the text in the |
| 972 | register. With blockwise selection it also depends on the size of the block |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 973 | and whether the corners are on an existing character. (Implementation detail: |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 974 | it actually works by first putting the register after the selection and then |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 975 | deleting the selection.) |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 976 | |
| 977 | *blockwise-register* |
| 978 | If you use a blockwise Visual mode command to get the text into the register, |
| 979 | the block of text will be inserted before ("P") or after ("p") the cursor |
| 980 | column in the current and next lines. Vim makes the whole block of text start |
| 981 | in the same column. Thus the inserted text looks the same as when it was |
| 982 | yanked or deleted. Vim may replace some <Tab> characters with spaces to make |
| 983 | this happen. However, if the width of the block is not a multiple of a <Tab> |
| 984 | width and the text after the inserted block contains <Tab>s, that text may be |
| 985 | misaligned. |
| 986 | |
| 987 | Note that after a characterwise yank command, Vim leaves the cursor on the |
| 988 | first yanked character that is closest to the start of the buffer. This means |
| 989 | that "yl" doesn't move the cursor, but "yh" moves the cursor one character |
| 990 | left. |
| 991 | Rationale: In Vi the "y" command followed by a backwards motion would |
| 992 | sometimes not move the cursor to the first yanked character, |
| 993 | because redisplaying was skipped. In Vim it always moves to |
| 994 | the first character, as specified by Posix. |
| 995 | With a linewise yank command the cursor is put in the first line, but the |
| 996 | column is unmodified, thus it may not be on the first yanked character. |
| 997 | |
| 998 | There are nine types of registers: *registers* *E354* |
| 999 | 1. The unnamed register "" |
| 1000 | 2. 10 numbered registers "0 to "9 |
| 1001 | 3. The small delete register "- |
| 1002 | 4. 26 named registers "a to "z or "A to "Z |
| 1003 | 5. four read-only registers ":, "., "% and "# |
| 1004 | 6. the expression register "= |
| 1005 | 7. The selection and drop registers "*, "+ and "~ |
| 1006 | 8. The black hole register "_ |
| 1007 | 9. Last search pattern register "/ |
| 1008 | |
| 1009 | 1. Unnamed register "" *quote_quote* *quotequote* |
| 1010 | Vim fills this register with text deleted with the "d", "c", "s", "x" commands |
| 1011 | or copied with the yank "y" command, regardless of whether or not a specific |
Bram Moolenaar | ed20346 | 2004-06-16 11:19:22 +0000 | [diff] [blame] | 1012 | register was used (e.g. "xdd). This is like the unnamed register is pointing |
| 1013 | to the last used register. An exception is the '_' register: "_dd does not |
Bram Moolenaar | 8169525 | 2004-12-29 20:58:21 +0000 | [diff] [blame] | 1014 | store the deleted text in any register. |
| 1015 | Vim uses the contents of the unnamed register for any put command (p or P) |
| 1016 | which does not specify a register. Additionally you can access it with the |
| 1017 | name '"'. This means you have to type two double quotes. Writing to the "" |
| 1018 | register writes to register "0. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1019 | {Vi: register contents are lost when changing files, no '"'} |
| 1020 | |
| 1021 | 2. Numbered registers "0 to "9 *quote_number* *quote0* *quote1* |
| 1022 | *quote2* *quote3* *quote4* *quote9* |
| 1023 | Vim fills these registers with text from yank and delete commands. |
| 1024 | Numbered register 0 contains the text from the most recent yank command, |
| 1025 | unless the command specified another register with ["x]. |
| 1026 | Numbered register 1 contains the text deleted by the most recent delete or |
| 1027 | change command, unless the command specified another register or the text is |
| 1028 | less than one line (the small delete register is used then). An exception is |
Bram Moolenaar | 8169525 | 2004-12-29 20:58:21 +0000 | [diff] [blame] | 1029 | made for the delete operator with these movement commands: |%|, |(|, |)|, |`|, |
| 1030 | |/|, |?|, |n|, |N|, |{| and |}|. Register "1 is always used then (this is Vi |
| 1031 | compatible). The "- register is used as well if the delete is within a line. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1032 | With each successive deletion or change, Vim shifts the previous contents |
| 1033 | of register 1 into register 2, 2 into 3, and so forth, losing the previous |
| 1034 | contents of register 9. |
| 1035 | {Vi: numbered register contents are lost when changing files; register 0 does |
| 1036 | not exist} |
| 1037 | |
| 1038 | 3. Small delete register "- *quote_-* *quote-* |
| 1039 | This register contains text from commands that delete less than one line, |
| 1040 | except when the command specifies a register with ["x]. |
| 1041 | {not in Vi} |
| 1042 | |
| 1043 | 4. Named registers "a to "z or "A to "Z *quote_alpha* *quotea* |
| 1044 | Vim fills these registers only when you say so. Specify them as lowercase |
| 1045 | letters to replace their previous contents or as uppercase letters to append |
Bram Moolenaar | 4399ef4 | 2005-02-12 14:29:27 +0000 | [diff] [blame] | 1046 | to their previous contents. When the '>' flag is present in 'cpoptions' then |
| 1047 | a line break is inserted before the appended text. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1048 | |
| 1049 | 5. Read-only registers ":, "., "% and "# |
| 1050 | These are '%', '#', ':' and '.'. You can use them only with the "p", "P", |
| 1051 | and ":put" commands and with CTRL-R. {not in Vi} |
| 1052 | *quote_.* *quote.* *E29* |
| 1053 | ". Contains the last inserted text (the same as what is inserted |
| 1054 | with the insert mode commands CTRL-A and CTRL-@). Note: this |
| 1055 | doesn't work with CTRL-R on the command-line. It works a bit |
| 1056 | differently, like inserting the text instead of putting it |
| 1057 | ('textwidth' and other options affect what is inserted). |
| 1058 | *quote_%* *quote%* |
| 1059 | "% Contains the name of the current file. |
| 1060 | *quote_#* *quote#* |
| 1061 | "# Contains the name of the alternate file. |
| 1062 | *quote_:* *quote:* *E30* |
| 1063 | ": Contains the most recent executed command-line. Example: Use |
| 1064 | "@:" to repeat the previous command-line command. |
| 1065 | The command-line is only stored in this register when at least |
| 1066 | one character of it was typed. Thus it remains unchanged if |
| 1067 | the command was completely from a mapping. |
| 1068 | {not available when compiled without the |+cmdline_hist| |
| 1069 | feature} |
| 1070 | |
| 1071 | 6. Expression register "= *quote_=* *quote=* |
| 1072 | This is not really a register that stores text, but is a way to use an |
| 1073 | expression in commands which use a register. The expression register is |
| 1074 | read-only; you cannot put text into it. After the '=', the cursor moves to |
| 1075 | the command-line, where you can enter any expression (see |expression|). All |
| 1076 | normal command-line editing commands are available, including a special |
| 1077 | history for expressions. When you end the command-line by typing <CR>, Vim |
| 1078 | computes the result of the expression. If you end it with <Esc>, Vim abandons |
| 1079 | the expression. If you do not enter an expression, Vim uses the previous |
Bram Moolenaar | 6bab4d1 | 2005-06-16 21:53:56 +0000 | [diff] [blame] | 1080 | expression (like with the "/" command). The expression must evaluate to a |
| 1081 | string. If the result is a number it's turned into a string. A List, |
| 1082 | Dictionary or FuncRef results in an error message (use string() to convert). |
| 1083 | If the "= register is used for the "p" command, the string is split up at <NL> |
| 1084 | characters. If the string ends in a <NL>, it is regarded as a linewise |
| 1085 | register. {not in Vi} |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1086 | |
| 1087 | 7. Selection and drop registers "*, "+ and "~ |
| 1088 | Use these register for storing and retrieving the selected text for the GUI. |
| 1089 | See |quotestar| and |quoteplus|. When the clipboard is not available or not |
Bram Moolenaar | f4d1145 | 2005-12-02 00:46:37 +0000 | [diff] [blame] | 1090 | working, the unnamed register is used instead. For Unix systems the clipboard |
| 1091 | is only available when the |+xterm_clipboard| feature is present. {not in Vi} |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1092 | |
| 1093 | Note that there is only a distinction between "* and "+ for X11 systems. For |
| 1094 | an explanation of the difference, see |x11-selection|. Under MS-Windows, use |
| 1095 | of "* and "+ is actually synonymous and refers to the |gui-clipboard|. |
| 1096 | |
| 1097 | *quote_~* *quote~* *<Drop>* |
| 1098 | The read-only "~ register stores the dropped text from the last drag'n'drop |
| 1099 | operation. When something has been dropped onto Vim, the "~ register is |
| 1100 | filled in and the <Drop> pseudo key is sent for notification. You can remap |
| 1101 | this key if you want; the default action (for all modes) is to insert the |
| 1102 | contents of the "~ register at the cursor position. {not in Vi} |
Bram Moolenaar | 69a7cb4 | 2004-06-20 12:51:53 +0000 | [diff] [blame] | 1103 | {only available when compiled with the |+dnd| feature, currently only with the |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1104 | GTK GUI} |
| 1105 | |
| 1106 | Note: The "~ register is only used when dropping plain text onto Vim. |
| 1107 | Drag'n'drop of URI lists is handled internally. |
| 1108 | |
| 1109 | 8. Black hole register "_ *quote_* |
| 1110 | When writing to this register, nothing happens. This can be used to delete |
| 1111 | text without affecting the normal registers. When reading from this register, |
| 1112 | nothing is returned. {not in Vi} |
| 1113 | |
| 1114 | 9. Last search pattern register "/ *quote_/* *quote/* |
| 1115 | Contains the most recent search-pattern. This is used for "n" and 'hlsearch'. |
| 1116 | It is writable with ":let", you can change it to have 'hlsearch' highlight |
| 1117 | other matches without actually searching. You can't yank or delete into this |
| 1118 | register. {not in Vi} |
| 1119 | |
| 1120 | *@/* |
| 1121 | You can write to a register with a ":let" command |:let-@|. Example: > |
| 1122 | :let @/ = "the" |
| 1123 | |
| 1124 | If you use a put command without specifying a register, Vim uses the register |
| 1125 | that was last filled (this is also the contents of the unnamed register). If |
| 1126 | you are confused, use the ":dis" command to find out what Vim will put (this |
| 1127 | command displays all named and numbered registers; the unnamed register is |
| 1128 | labelled '"'). |
| 1129 | |
| 1130 | The next three commands always work on whole lines. |
| 1131 | |
| 1132 | :[range]co[py] {address} *:co* *:copy* |
| 1133 | Copy the lines given by [range] to below the line |
| 1134 | given by {address}. |
| 1135 | |
| 1136 | *:t* |
| 1137 | :t Synonym for copy. |
| 1138 | |
| 1139 | :[range]m[ove] {address} *:m* *:mo* *:move* *E134* |
| 1140 | Move the lines given by [range] to below the line |
| 1141 | given by {address}. |
| 1142 | |
| 1143 | ============================================================================== |
| 1144 | 6. Formatting text *formatting* |
| 1145 | |
| 1146 | :[range]ce[nter] [width] *:ce* *:center* |
| 1147 | Center lines in [range] between [width] columns |
| 1148 | (default 'textwidth' or 80 when 'textwidth' is 0). |
| 1149 | {not in Vi} |
| 1150 | Not available when |+ex_extra| feature was disabled at |
| 1151 | compile time. |
| 1152 | |
| 1153 | :[range]ri[ght] [width] *:ri* *:right* |
| 1154 | Right-align lines in [range] at [width] columns |
| 1155 | (default 'textwidth' or 80 when 'textwidth' is 0). |
| 1156 | {not in Vi} |
| 1157 | Not available when |+ex_extra| feature was disabled at |
| 1158 | compile time. |
| 1159 | |
| 1160 | *:le* *:left* |
| 1161 | :[range]le[ft] [indent] |
| 1162 | Left-align lines in [range]. Sets the indent in the |
| 1163 | lines to [indent] (default 0). {not in Vi} |
| 1164 | Not available when |+ex_extra| feature was disabled at |
| 1165 | compile time. |
| 1166 | |
| 1167 | *gq* |
Bram Moolenaar | 4317d9b | 2005-03-18 20:25:31 +0000 | [diff] [blame] | 1168 | gq{motion} Format the lines that {motion} moves over. |
| 1169 | If 'formatprg' is empty formatting is done internally |
| 1170 | and the 'textwidth' option controls the length of each |
| 1171 | formatted line (see below). |
| 1172 | If the 'textwidth' option is 0, the formatted line |
| 1173 | length is the screen width (with a maximum width of |
| 1174 | 79). {not in Vi} |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1175 | The 'formatoptions' option controls the type of |
| 1176 | formatting |fo-table|. |
Bram Moolenaar | 4317d9b | 2005-03-18 20:25:31 +0000 | [diff] [blame] | 1177 | The cursor is left on the first non-blank of the last |
| 1178 | formatted line. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1179 | NOTE: The "Q" command formerly performed this |
| 1180 | function. If you still want to use "Q" for |
| 1181 | formatting, use this mapping: > |
| 1182 | :nnoremap Q gq |
| 1183 | |
| 1184 | gqgq *gqgq* *gqq* |
| 1185 | gqq Format the current line. {not in Vi} |
| 1186 | |
| 1187 | *v_gq* |
| 1188 | {Visual}gq Format the highlighted text. (for {Visual} see |
| 1189 | |Visual-mode|). {not in Vi} |
| 1190 | |
| 1191 | *gw* |
| 1192 | gw{motion} Format the lines that {motion} moves over. Similar to |
| 1193 | |gq| but puts the cursor back at the same position in |
| 1194 | the text. However, 'formatprg' is not used. |
| 1195 | {not in Vi} |
| 1196 | |
Bram Moolenaar | 69a7cb4 | 2004-06-20 12:51:53 +0000 | [diff] [blame] | 1197 | gwgw *gwgw* *gww* |
| 1198 | gww Format the current line as with "gw". {not in Vi} |
| 1199 | |
| 1200 | *v_gw* |
| 1201 | {Visual}gw Format the highlighted text as with "gw". (for |
| 1202 | {Visual} see |Visual-mode|). {not in Vi} |
| 1203 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1204 | Example: To format the current paragraph use: *gqap* > |
| 1205 | gqap |
| 1206 | |
| 1207 | The "gq" command leaves the cursor in the line where the motion command takes |
| 1208 | the cursor. This allows you to repeat formatting repeated with ".". This |
| 1209 | works well with "gqj" (format current and next line) and "gq}" (format until |
| 1210 | end of paragraph). Note: When 'formatprg' is set, "gq" leaves the cursor on |
| 1211 | the first formatted line (as with using a filter command). |
| 1212 | |
| 1213 | If you want to format the current paragraph and continue where you were, use: > |
| 1214 | gwap |
| 1215 | If you always want to keep paragraphs formatted you may want to add the 'a' |
| 1216 | flag to 'formatoptions'. See |auto-format|. |
| 1217 | |
| 1218 | If the 'autoindent' option is on, Vim uses the indent of the first line for |
| 1219 | the following lines. |
| 1220 | |
| 1221 | Formatting does not change empty lines (but it does change lines with only |
| 1222 | white space!). |
| 1223 | |
| 1224 | The 'joinspaces' option is used when lines are joined together. |
| 1225 | |
| 1226 | You can set the 'formatprg' option to the name of an external program for Vim |
| 1227 | to use for text formatting. The 'textwidth' and other options have no effect |
| 1228 | on formatting by an external program. |
| 1229 | |
| 1230 | *right-justify* |
| 1231 | There is no command in Vim to right justify text. You can do it with |
| 1232 | an external command, like "par" (e.g.: "!}par" to format until the end of the |
| 1233 | paragraph) or set 'formatprg' to "par". |
| 1234 | |
| 1235 | *format-comments* |
| 1236 | Vim can format comments in a special way. Vim recognizes a comment by a |
| 1237 | specific string at the start of the line (ignoring white space). Three types |
| 1238 | of comments can be used: |
| 1239 | |
| 1240 | - A comment string that repeats at the start of each line. An example is the |
| 1241 | type of comment used in shell scripts, starting with "#". |
| 1242 | - A comment string that occurs only in the first line, not in the following |
| 1243 | lines. An example is this list with dashes. |
| 1244 | - Three-piece comments that have a start string, an end string, and optional |
| 1245 | lines in between. The strings for the start, middle and end are different. |
| 1246 | An example is the C-style comment: |
| 1247 | /* |
| 1248 | * this is a C comment |
| 1249 | */ |
| 1250 | |
| 1251 | The 'comments' option is a comma-separated list of parts. Each part defines a |
| 1252 | type of comment string. A part consists of: |
| 1253 | {flags}:{string} |
| 1254 | |
| 1255 | {string} is the literal text that must appear. |
| 1256 | |
| 1257 | {flags}: |
| 1258 | n Nested comment. Nesting with mixed parts is allowed. If 'comments' |
| 1259 | is "n:),n:>" a line starting with "> ) >" is a comment. |
| 1260 | |
| 1261 | b Blank (<Space>, <Tab> or <EOL>) required after {string}. |
| 1262 | |
| 1263 | f Only the first line has the comment string. Do not repeat comment on |
| 1264 | the next line, but preserve indentation (e.g., a bullet-list). |
| 1265 | |
| 1266 | s Start of three-piece comment |
| 1267 | |
| 1268 | m Middle of a three-piece comment |
| 1269 | |
| 1270 | e End of a three-piece comment |
| 1271 | |
| 1272 | l Left adjust middle with start or end (default). Only recognized when |
| 1273 | used together with 's' or 'e'. |
| 1274 | |
| 1275 | r Right adjust middle with start or end. Only recognized when used |
| 1276 | together with 's' or 'e'. |
| 1277 | |
| 1278 | O Don't use this one for the "O" command. |
| 1279 | |
| 1280 | x Allows three-piece comments to be ended by just typing the last |
| 1281 | character of the end-comment string as the first character on a new |
| 1282 | line, when the middle-comment string has already been inserted |
| 1283 | automatically. See below for more details. |
| 1284 | |
| 1285 | {digits} |
| 1286 | When together with 's' or 'e': add extra indent for the middle part. |
| 1287 | This can be used to left-align the middle part with the start or end |
| 1288 | and then add an offset. |
| 1289 | |
| 1290 | -{digits} |
| 1291 | Like {digits} but reduce the indent. This only works when there is |
| 1292 | some indent for the start or end part that can be removed. |
| 1293 | |
| 1294 | When a string has none of the 'f', 's', 'm' or 'e' flags, Vim assumes the |
| 1295 | comment string repeats at the start of each line. The flags field may be |
| 1296 | empty. |
| 1297 | |
| 1298 | Any blank space in the text before and after the {string} is part of the |
| 1299 | {string}, so do not include leading or trailing blanks unless the blanks are a |
| 1300 | required part of the comment string. |
| 1301 | |
| 1302 | When one comment leader is part of another, specify the part after the whole. |
| 1303 | For example, to include both "-" and "->", use > |
| 1304 | :set comments=f:->,f:- |
| 1305 | |
| 1306 | A three-piece comment must always be given as start,middle,end, with no other |
| 1307 | parts in between. An example of a three-piece comment is > |
| 1308 | sr:/*,mb:*,ex:*/ |
| 1309 | for C-comments. To avoid recognizing "*ptr" as a comment, the middle string |
| 1310 | includes the 'b' flag. For three-piece comments, Vim checks the text after |
| 1311 | the start and middle strings for the end string. If Vim finds the end string, |
| 1312 | the comment does not continue on the next line. Three-piece comments must |
| 1313 | have a middle string because otherwise Vim can't recognize the middle lines. |
| 1314 | |
| 1315 | Notice the use of the "x" flag in the above three-piece comment definition. |
| 1316 | When you hit Return in a C-comment, Vim will insert the middle comment leader |
| 1317 | for the new line, e.g. " * ". To close this comment you just have to type "/" |
| 1318 | before typing anything else on the new line. This will replace the |
| 1319 | middle-comment leader with the end-comment leader, leaving just " */". There |
| 1320 | is no need to hit BackSpace first. |
| 1321 | |
| 1322 | Examples: > |
| 1323 | "b:*" Includes lines starting with "*", but not if the "*" is |
| 1324 | followed by a non-blank. This avoids a pointer dereference |
| 1325 | like "*str" to be recognized as a comment. |
| 1326 | "n:>" Includes a line starting with ">", ">>", ">>>", etc. |
| 1327 | "fb:-" Format a list that starts with "- ". |
| 1328 | |
| 1329 | By default, "b:#" is included. This means that a line that starts with |
| 1330 | "#include" is not recognized as a comment line. But a line that starts with |
| 1331 | "# define" is recognized. This is a compromise. |
| 1332 | |
| 1333 | Often the alignment can be changed from right alignment to a left alignment |
| 1334 | with an additional space. For example, for Javadoc comments, this can be |
| 1335 | used (insert a backslash before the space when using ":set"): > |
| 1336 | s1:/*,mb:*,ex:*/ |
| 1337 | Note that an offset is included with start, so that the middle part is left |
| 1338 | aligned with the start and then an offset of one character added. This makes |
| 1339 | it possible to left align the start and middle for this construction: > |
| 1340 | /** |
| 1341 | * comment |
| 1342 | */ |
| 1343 | |
| 1344 | {not available when compiled without the |+comments| feature} |
| 1345 | |
| 1346 | *fo-table* |
| 1347 | You can use the 'formatoptions' option to influence how Vim formats text. |
| 1348 | 'formatoptions' is a string that can contain any of the letters below. The |
| 1349 | default setting is "tcq". You can separate the option letters with commas for |
| 1350 | readability. |
| 1351 | |
| 1352 | letter meaning when present in 'formatoptions' ~ |
| 1353 | |
| 1354 | t Auto-wrap text using textwidth (does not apply to comments) |
| 1355 | c Auto-wrap comments using textwidth, inserting the current comment |
| 1356 | leader automatically. |
| 1357 | r Automatically insert the current comment leader after hitting |
| 1358 | <Enter> in Insert mode. |
| 1359 | o Automatically insert the current comment leader after hitting 'o' or |
| 1360 | 'O' in Normal mode. |
| 1361 | q Allow formatting of comments with "gq". |
| 1362 | Note that formatting will not change blank lines or lines containing |
| 1363 | only the comment leader. A new paragraph starts after such a line, |
| 1364 | or when the comment leader changes. |
| 1365 | w Trailing white space indicates a paragraph continues in the next line. |
| 1366 | A line that ends in a non-white character ends a paragraph. |
| 1367 | a Automatic formatting of paragraphs. Every time text is inserted or |
| 1368 | deleted the paragraph will be reformatted. See |auto-format|. |
| 1369 | When the 'c' flag is present this only happens for recognized |
| 1370 | comments. |
Bram Moolenaar | 86b6835 | 2004-12-27 21:59:20 +0000 | [diff] [blame] | 1371 | n When formatting text, recognize numbered lists. This actually uses |
| 1372 | the 'formatlistpat' option, thus any kind of list can be used. The |
| 1373 | indent of the text after the number is used for the next line. The |
| 1374 | default is to find a number, optionally be followed by '.', ':', ')', |
| 1375 | ']' or '}'. Note that 'autoindent' must be set too. Doesn't work |
| 1376 | well together with "2". |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1377 | Example: > |
| 1378 | 1. the first item |
| 1379 | wraps |
| 1380 | 2. the second item |
| 1381 | 2 When formatting text, use the indent of the second line of a paragraph |
| 1382 | for the rest of the paragraph, instead of the indent of the first |
| 1383 | line. This supports paragraphs in which the first line has a |
| 1384 | different indent than the rest. Note that 'autoindent' must be set |
| 1385 | too. Example: > |
| 1386 | first line of a paragraph |
| 1387 | second line of the same paragraph |
| 1388 | third line. |
| 1389 | v Vi-compatible auto-wrapping in insert mode: Only break a line at a |
| 1390 | blank that you have entered during the current insert command. (Note: |
| 1391 | this is not 100% Vi compatible. Vi has some "unexpected features" or |
| 1392 | bugs in this area. It uses the screen column instead of the line |
| 1393 | column.) |
| 1394 | b Like 'v', but only auto-wrap if you enter a blank at or before |
| 1395 | the wrap margin. If the line was longer than 'textwidth' when you |
| 1396 | started the insert, or you do not enter a blank in the insert before |
| 1397 | reaching 'textwidth', Vim does not perform auto-wrapping. |
| 1398 | l Long lines are not broken in insert mode: When a line was longer than |
| 1399 | 'textwidth' when the insert command started, Vim does not |
| 1400 | automatically format it. |
| 1401 | m Also break at a multi-byte character above 255. This is useful for |
| 1402 | Asian text where every character is a word on its own. |
| 1403 | M When joining lines, don't insert a space before or after a multi-byte |
| 1404 | character. Overrules the 'B' flag. |
| 1405 | B When joining lines, don't insert a space between two multi-byte |
| 1406 | characters. Overruled by the 'M' flag. |
| 1407 | 1 Don't break a line after a one-letter word. It's broken before it |
| 1408 | instead (if possible). |
| 1409 | |
| 1410 | |
| 1411 | With 't' and 'c' you can specify when Vim performs auto-wrapping: |
| 1412 | value action ~ |
| 1413 | "" no automatic formatting (you can use "gq" for manual formatting) |
| 1414 | "t" automatic formatting of text, but not comments |
| 1415 | "c" automatic formatting for comments, but not text (good for C code) |
| 1416 | "tc" automatic formatting for text and comments |
| 1417 | |
| 1418 | Note that when 'textwidth' is 0, Vim does no formatting anyway (but does |
| 1419 | insert comment leaders according to the 'comments' option). |
| 1420 | |
| 1421 | Note that when 'paste' is on, Vim does no formatting at all. |
| 1422 | |
| 1423 | Note that 'textwidth' can be non-zero even if Vim never performs auto-wrapping; |
| 1424 | 'textwidth' is still useful for formatting with "gq". |
| 1425 | |
| 1426 | If the 'comments' option includes "/*", "*" and/or "*/", then Vim has some |
| 1427 | built in stuff to treat these types of comments a bit more cleverly. |
| 1428 | Opening a new line before or after "/*" or "*/" (with 'r' or 'o' present in |
| 1429 | 'formatoptions') gives the correct start of the line automatically. The same |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 1430 | happens with formatting and auto-wrapping. Opening a line after a line |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1431 | starting with "/*" or "*" and containing "*/", will cause no comment leader to |
| 1432 | be inserted, and the indent of the new line is taken from the line containing |
| 1433 | the start of the comment. |
| 1434 | E.g.: |
| 1435 | /* ~ |
| 1436 | * Your typical comment. ~ |
| 1437 | */ ~ |
| 1438 | The indent on this line is the same as the start of the above |
| 1439 | comment. |
| 1440 | |
| 1441 | All of this should be really cool, especially in conjunction with the new |
| 1442 | :autocmd command to prepare different settings for different types of file. |
| 1443 | |
| 1444 | Some examples: |
| 1445 | for C code (only format comments): > |
| 1446 | :set fo=croq |
| 1447 | < for Mail/news (format all, don't start comment with "o" command): > |
| 1448 | :set fo=tcrq |
| 1449 | < |
| 1450 | |
| 1451 | Automatic formatting *auto-format* |
| 1452 | |
| 1453 | When the 'a' flag is present in 'formatoptions' text is formatted |
| 1454 | automatically when inserting text or deleting text. This works nice for |
| 1455 | editing text paragraphs. A few hints on how to use this: |
| 1456 | |
| 1457 | - You need to properly define paragraphs. The simplest is paragraphs that are |
| 1458 | separated by a blank line. When there is no separating blank line, consider |
| 1459 | using the 'w' flag and adding a space at the end of each line in the |
| 1460 | paragraphs except the last one. |
| 1461 | |
| 1462 | - You can set the 'formatoptions' based on the type of file |filetype| or |
| 1463 | specifically for one file with a |modeline|. |
| 1464 | |
| 1465 | - Set 'formatoptions' to "aw2tq" to make text with indents like this: |
| 1466 | |
| 1467 | bla bla foobar bla |
| 1468 | bla foobar bla foobar bla |
| 1469 | bla bla foobar bla |
| 1470 | bla foobar bla bla foobar |
| 1471 | |
| 1472 | - Add the 'c' flag to only auto-format comments. Useful in source code. |
| 1473 | |
| 1474 | And a few warnings: |
| 1475 | |
| 1476 | - When part of the text is not properly separated in paragraphs, making |
| 1477 | changes in this text will cause it to be formatted anyway. Consider doing > |
| 1478 | |
| 1479 | :set fo-=a |
| 1480 | |
| 1481 | - When using the 'w' flag (trailing space means paragraph continues) and |
| 1482 | deleting the last line of a paragraph with |dd|, the paragraph will be |
| 1483 | joined with the next one. |
| 1484 | |
| 1485 | - Changed text is saved for undo. Formatting is also a change. Thus each |
| 1486 | format action saves text for undo. This may consume quite a lot of memory. |
| 1487 | |
| 1488 | - Formatting a long paragraph and/or with complicated indenting may be slow. |
| 1489 | |
Bram Moolenaar | 2389c3c | 2005-05-22 22:07:59 +0000 | [diff] [blame] | 1490 | ============================================================================== |
| 1491 | 7. Sorting text *sorting* |
| 1492 | |
| 1493 | Vim has a sorting function and a sorting command. The sorting function can be |
| 1494 | found here: |sort()|. |
| 1495 | |
| 1496 | *:sor* *:sort* |
Bram Moolenaar | e518052 | 2005-12-10 20:19:46 +0000 | [diff] [blame] | 1497 | :[range]sor[t][!] [i][u][n][x][o] [/{pattern}/] |
| 1498 | Sort lines in [range]. When no range is given all |
| 1499 | lines are sorted. |
Bram Moolenaar | 2389c3c | 2005-05-22 22:07:59 +0000 | [diff] [blame] | 1500 | |
| 1501 | With [!] the order is reversed. |
| 1502 | |
| 1503 | With [i] case is ignored. |
| 1504 | |
Bram Moolenaar | 5c06f8b | 2005-05-31 22:14:58 +0000 | [diff] [blame] | 1505 | With [n] sorting is done on the first decimal number |
| 1506 | in the line (after a {pattern} match). |
| 1507 | |
| 1508 | With [x] sorting is done on the first hexadecimal |
| 1509 | number in the line (after a {pattern} match). A |
| 1510 | leading "0x" or "0X" is ignored. |
| 1511 | |
| 1512 | With [o] sorting is done on the first octal number in |
| 1513 | the line (after a {pattern} match). |
| 1514 | |
Bram Moolenaar | 2389c3c | 2005-05-22 22:07:59 +0000 | [diff] [blame] | 1515 | With [u] only keep the first of a sequence of |
| 1516 | identical lines (ignoring case when [i] is used). |
Bram Moolenaar | 5c06f8b | 2005-05-31 22:14:58 +0000 | [diff] [blame] | 1517 | Note that leading and trailing white space may cause |
| 1518 | lines to be different. |
Bram Moolenaar | 2389c3c | 2005-05-22 22:07:59 +0000 | [diff] [blame] | 1519 | |
| 1520 | When /{pattern}/ is specified the text matched with |
| 1521 | {pattern} is skipped, so that you sort on what comes |
| 1522 | after the match. For lines without a match sorting |
| 1523 | starts in the first column (e.g., for empty lines). |
| 1524 | Instead of the slash any non-letter can be used. |
| 1525 | For example, to sort on the second comma-separated |
| 1526 | field: > |
| 1527 | :sort /[^,]*,/ |
| 1528 | < To sort on the text at virtual column 10 (thus |
| 1529 | ignoring the difference between tabs and spaces): > |
| 1530 | :sort /.*\%10v/ |
| 1531 | < |
Bram Moolenaar | 5c06f8b | 2005-05-31 22:14:58 +0000 | [diff] [blame] | 1532 | Note that using ":sort" with ":global" doesn't sort the matching lines, it's |
| 1533 | quite useless. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1534 | |
Bram Moolenaar | f461c8e | 2005-06-25 23:04:51 +0000 | [diff] [blame] | 1535 | The details about sorting depend on the library function used. There is no |
| 1536 | guarantee that sorting is "stable" or obeys the current locale. You will have |
| 1537 | to try it out. |
| 1538 | |
Bram Moolenaar | ae5bce1 | 2005-08-15 21:41:48 +0000 | [diff] [blame] | 1539 | The sorting itself cannot be interrupted, because of using a system library |
| 1540 | function. You can interrupt the preparation (for undo) and putting the sorted |
| 1541 | lines into the buffer. In the last case you may end up with duplicated lines. |
| 1542 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1543 | vim:tw=78:ts=8:ft=help:norl: |