vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

change.txt (83721B)


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