__
  _____/ /_  ____ _____  ____ ____
 / ___/ __ \/ __ `/ __ \/ __ `/ _ \
/ /__/ / / / /_/ / / / / /_/ /  __/
\___/_/ /_/\__,_/_/ /_/\__, /\___/
                      /____/
change.txt    For Vim version 9.0.  Last change: 2022 Nov 20


                  VIM REFERENCE MANUAL    by Bram Moolenaar


This file describes commands that delete or change text.  In this context,
changing text means deleting the text and replacing it with other text using
one command.  You can undo all of these commands.  You can repeat the non-Ex
commands with the "." command.

1. Deleting text                deleting
2. Delete and insert            delete-insert

3. Simple changes               simple-change         changing
4. Complex changes              complex-change
   4.1 Filter commands             filter
   4.2 Substitute                  :substitute
   4.3 Search and replace          search-replace
   4.4 Changing tabs               change-tabs
5. Copying and moving text      copy-move
6. Formatting text              formatting
7. Sorting text                 sorting

For inserting text see insert.txt.

==============================================================================

1. Deleting text                                        deleting E470


["x]<Del>       or                                      <Del> x dl
["x]x                   Delete [count] characters under and after the cursor
                        [into register x] (not linewise).  Does the same as
                        "dl".
                        The <Del> key does not take a [count].  Instead, it
                        deletes the last character of the count.
                        See :fixdel if the <Del> key does not do what you
                        want.  See 'whichwrap' for deleting a line break
                        (join lines).


                                                        X dh
["x]X                   Delete [count] characters before the cursor [into
                        register x] (not linewise).  Does the same as "dh".
                        Also see 'whichwrap'.


                                                        d
["x]d{motion}           Delete text that {motion} moves over [into register
                        x].  See below for exceptions.


                                                        dd
["x]dd                  Delete [count] lines [into register x] linewise.


                                                        D
["x]D                   Delete the characters under the cursor until the end
                        of the line and [count]-1 more lines [into register
                        x]; synonym for "d$".
                        (not linewise)
                        When the '#' flag is in 'cpoptions' the count is
                        ignored.


{Visual}["x]x   or                                      v_x v_d v_<Del>
{Visual}["x]d   or
{Visual}["x]<Del>       Delete the highlighted text [into register x] (for
                        {Visual} see Visual-mode).


{Visual}["x]CTRL-H   or                                 v_CTRL-H v_<BS>
{Visual}["x]<BS>        When in Select mode: Delete the highlighted text [into
                        register x].


{Visual}["x]X   or                                      v_X v_D v_b_D
{Visual}["x]D           Delete the highlighted lines [into register x] (for
                        {Visual} see Visual-mode).  In Visual block mode,
                        "D" deletes the highlighted text plus all text until
                        the end of the line.


                                        :d :de :del :delete :dl :dp
:[range]d[elete] [x]    Delete [range] lines (default: current line) [into
                        register x].
                        Note these weird abbreviations:
                           :dl          delete and list
                           :dell        idem
                           :delel       idem
                           :deletl      idem
                           :deletel     idem
                           :dp          delete and print
                           :dep         idem
                           :delp        idem
                           :delep       idem
                           :deletp      idem
                           :deletep     idem

:[range]d[elete] [x] {count}
                        Delete {count} lines, starting with [range]
                        (default: current line cmdline-ranges) [into
                        register x].

These commands delete text.  You can repeat them with the `.` command
(except `:d`) and undo them.  Use Visual mode to delete blocks of text.  See
registers   for an explanation of registers.

An exception for the d{motion} command: If the motion is not linewise, the
start and end of the motion are not in the same line, and there are only
blanks before the start and there are no non-blanks after the end of the
motion, the delete becomes linewise.  This means that the delete also removes
the line of blanks that you might expect to remain. Use the o_v operator to
force the motion to be characterwise.

Trying to delete an empty region of text (e.g., "d0" in the first column)
is an error when 'cpoptions' includes the 'E' flag.


                                                        J
J                       Join [count] lines, with a minimum of two lines.
                        Remove the indent and insert up to two spaces (see
                        below).  Fails when on the last line of the buffer.
                        If [count] is too big it is reduced to the number of
                        lines available.


                                                        v_J
{Visual}J               Join the highlighted lines, with a minimum of two
                        lines.  Remove the indent and insert up to two spaces
                        (see below).


                                                        gJ
gJ                      Join [count] lines, with a minimum of two lines.
                        Don't insert or remove any spaces.


                                                        v_gJ
{Visual}gJ              Join the highlighted lines, with a minimum of two
                        lines.  Don't insert or remove any spaces.


                                                        :j :join
:[range]j[oin][!] [flags]
                        Join [range] lines.  Same as "J", except with [!]
                        the join does not insert or delete any spaces.
                        If a [range] has equal start and end values, this
                        command does nothing.  The default behavior is to
                        join the current line with the line below it.
                        See ex-flags for [flags].

:[range]j[oin][!] {count} [flags]
                        Join {count} lines, starting with [range] (default:
                        current line cmdline-ranges).  Same as "J", except
                        with [!] the join does not insert or delete any
                        spaces.
                        See ex-flags for [flags].

These commands delete the <EOL> between lines.  This has the effect of joining
multiple lines into one line.  You can repeat these commands (except `:j`) and
undo them.

These commands, except "gJ", insert one space in place of the <EOL> unless
there is trailing white space or the next line starts with a ')'.  These
commands, except "gJ", delete any leading white space on the next line.  If
the 'joinspaces' option is on, these commands insert two spaces after a '.',
'!' or '?' (but if 'cpoptions' includes the 'j' flag, they insert two spaces
only after a '.').
The 'B' and 'M' flags in 'formatoptions' change the behavior for inserting
spaces before and after a multibyte character fo-table.

The '[ mark is set at the end of the first line that was joined, '] at the end
of the resulting line.


==============================================================================

2. Delete and insert                            delete-insert replacing


                                                        R
R                       Enter Replace mode: Each character you type replaces
                        an existing character, starting with the character
                        under the cursor.  Repeat the entered text [count]-1
                        times.  See Replace-mode for more details.


                                                        gR
gR                      Enter Virtual Replace mode: Each character you type
                        replaces existing characters in screen space.  So a
                        <Tab> may replace several characters at once.
                        Repeat the entered text [count]-1 times.  See
                        Virtual-Replace-mode for more details.


                                                        c
["x]c{motion}           Delete {motion} text [into register x] and start
                        insert.  When  'cpoptions' includes the 'E' flag and
                        there is no text to delete (e.g., with "cTx" when the
                        cursor is just after an 'x'), an error occurs and
                        insert mode does not start (this is Vi compatible).
                        When  'cpoptions' does not include the 'E' flag, the
                        "c" command always starts insert mode, even if there
                        is no text to delete.


                                                        cc
["x]cc                  Delete [count] lines [into register x] and start
                        insert linewise.  If 'autoindent' is on, preserve
                        the indent of the first line.


                                                        C
["x]C                   Delete from the cursor position to the end of the
                        line and [count]-1 more lines [into register x], and
                        start insert.  Synonym for c$ (not linewise).


                                                        s
["x]s                   Delete [count] characters [into register x] and start
                        insert (s stands for Substitute).  Synonym for "cl"
                        (not linewise).


                                                        S
["x]S                   Delete [count] lines [into register x] and start
                        insert.  Synonym for "cc" linewise.


{Visual}["x]c   or                                      v_c v_s
{Visual}["x]s           Delete the highlighted text [into register x] and
                        start insert (for {Visual} see Visual-mode).


                                                        v_r
{Visual}r{char}         Replace all selected characters by {char}.


                                                        v_C
{Visual}["x]C           Delete the highlighted lines [into register x] and
                        start insert.  In Visual block mode it works
                        differently v_b_C.

                                                        v_S
{Visual}["x]S           Delete the highlighted lines [into register x] and
                        start insert (for {Visual} see Visual-mode).

                                                        v_R
{Visual}["x]R           Currently just like {Visual}["x]S.  In a next version
                        it might work differently.

Notes:
- You can end Insert and Replace mode with <Esc>.
- See the section "Insert and Replace mode" mode-ins-repl for the other
  special characters in these modes.
- The effect of [count] takes place after Vim exits Insert or Replace mode.
- When the 'cpoptions' option contains '$' and the change is within one line,
  Vim continues to show the text to be deleted and puts a '$' at the last
  deleted character.

See registers for an explanation of registers.

Replace mode is just like Insert mode, except that every character you enter
deletes one character.  If you reach the end of a line, Vim appends any
further characters (just like Insert mode).  In Replace mode, the backspace
key restores the original text (if there was any).  (See section "Insert and
Replace mode" mode-ins-repl).


                                                cw cW
Special case: When the cursor is in a word, "cw" and "cW" do not include the
white space after a word, they only change up to the end of the word.  This is
because Vim interprets "cw" as change-word, and a word does not include the
following white space.
{Vi: "cw" when on a blank followed by other blanks changes only the first
blank; this is probably a bug, because "dw" deletes all the blanks; use the
'w' flag in 'cpoptions' to make it work like Vi anyway}

If you prefer "cw" to include the space after a word, use this mapping:
        :map cw dwi
Or use "caw" (see aw).


                                                        :c :ch :change
:{range}c[hange][!]     Replace lines of text with some different text.
                        Type a line containing only "." to stop replacing.
                        Without {range}, this command changes only the current
                        line.
                        Adding [!] toggles 'autoindent' for the time this
                        command is executed.
                        This command is not supported in Vim9 script,
                        because it is too easily confused with a variable
                        name.

==============================================================================

3. Simple changes                                       simple-change


                                                        r
r{char}                 Replace the character under the cursor with {char}.
                        If {char} is a <CR> or <NL>, a line break replaces the
                        character.  To replace with a real <CR>, use CTRL-V
                        <CR>.  CTRL-V <NL> replaces with a <Nul>.

                        If {char} is CTRL-E or CTRL-Y the character from the
                        line below or above is used, just like with i_CTRL-E
                        and i_CTRL-Y.  This also works with a count, thus
                        `10r<C-E>` copies 10 characters from the line below.

                        If you give a [count], Vim replaces [count] characters
                        with [count] {char}s.  When {char} is a <CR> or <NL>,
                        however, Vim inserts only one <CR>: "5r<CR>" replaces
                        five characters with a single line break.
                        When {char} is a <CR> or <NL>, Vim performs
                        autoindenting.  This works just like deleting the
                        characters that are replaced and then doing
                        "i<CR><Esc>".
                        {char} can be entered as a digraph digraph-arg.
                        :lmap mappings apply to {char}.  The CTRL-^ command
                        in Insert mode can be used to switch this on/off
                        i_CTRL-^.  See utf-8-char-arg about using
                        composing characters when 'encoding' is Unicode.


                                                        gr
gr{char}                Replace the virtual characters under the cursor with
                        {char}.  This replaces in screen space, not file
                        space.  See gR and Virtual-Replace-mode for more
                        details.  As with r a count may be given.
                        {char} can be entered like with r.


                                                digraph-arg
The argument for Normal mode commands like r and t is a single character.
When 'cpo' doesn't contain the 'D' flag, this character can also be entered
like digraphs.  First type CTRL-K and then the two digraph characters.
{not available when compiled without the +digraphs feature}


                                                case
The following commands change the case of letters.  The currently active
locale   is used.  See :language.  The LC_CTYPE value matters here.


                                                        ~
~                       'notildeop' option: Switch case of the character
                        under the cursor and move the cursor to the right.
                        If a [count] is given, do that many characters.

~{motion}               'tildeop' option: switch case of {motion} text.


                                                        g~
g~{motion}              Switch case of {motion} text.


g~g~                                                    g~g~ g~~
g~~                     Switch case of current line.


                                                        v_~
{Visual}~               Switch case of highlighted text (for {Visual} see
                        Visual-mode).


                                                        v_U
{Visual}U               Make highlighted text uppercase (for {Visual} see
                        Visual-mode).


                                                        gU uppercase
gU{motion}              Make {motion} text uppercase.
                        Example:
                                :map! <C-F> <Esc>gUiw`]a
                        This works in Insert mode: press CTRL-F to make the
                        word before the cursor uppercase.  Handy to type
                        words in lowercase and then make them uppercase.



gUgU                                                    gUgU gUU
gUU                     Make current line uppercase.


                                                        v_u
{Visual}u               Make highlighted text lowercase (for {Visual} see
                        Visual-mode).


                                                        gu lowercase
gu{motion}              Make {motion} text lowercase.


gugu                                                    gugu guu
guu                     Make current line lowercase.


                                                        g? rot13
g?{motion}              Rot13 encode {motion} text.


                                                        v_g?
{Visual}g?              Rot13 encode the highlighted text (for {Visual} see
                        Visual-mode).


g?g?                                                    g?g? g??
g??                     Rot13 encode current line.

To turn one line into title caps, make every first letter of a word
uppercase:
        :s/\v<(.)(\w*)/\u\1\L\2/g


Adding and subtracting 

                                                        CTRL-A
CTRL-A                  Add [count] to the number or alphabetic character at
                        or after the cursor.


                                                        v_CTRL-A
{Visual}CTRL-A          Add [count] to the number or alphabetic character in
                        the highlighted text.


                                                        v_g_CTRL-A
{Visual}g CTRL-A        Add [count] to the number or alphabetic character in
                        the highlighted text. If several lines are
                        highlighted, each one will be incremented by an
                        additional [count] (so effectively creating a
                        [count] incrementing sequence).
                        For Example, if you have this list of numbers:
                                1. 
                                1. 
                                1. 
                                1. 
                        Move to the second "1." and Visually select three
                        lines, pressing g CTRL-A results in:
                                1. 
                                2. 
                                3. 
                                4. 


                                                        CTRL-X
CTRL-X                  Subtract [count] from the number or alphabetic
                        character at or after the cursor.


                                                        v_CTRL-X
{Visual}CTRL-X          Subtract [count] from the number or alphabetic
                        character in the highlighted text.

                        On MS-Windows, this is mapped to cut Visual text
                        dos-standard-mappings.  If you want to disable the
                        mapping, use this:
                                silent! vunmap <C-X>
 

                                                        v_g_CTRL-X
{Visual}g CTRL-X        Subtract [count] from the number or alphabetic
                        character in the highlighted text. If several lines
                        are highlighted, each value will be decremented by an
                        additional [count] (so effectively creating a [count]
                        decrementing sequence).

The CTRL-A and CTRL-X commands can work for:
- signed and unsigned decimal numbers
- unsigned binary, octal and hexadecimal numbers
- alphabetic characters

This depends on the 'nrformats' option:
- When 'nrformats' includes "bin", Vim assumes numbers starting with '0b' or
  '0B' are binary.
- When 'nrformats' includes "octal", Vim considers numbers starting with a '0'
  to be octal, unless the number includes a '8' or '9'.  Other numbers are
  decimal and may have a preceding minus sign.
  If the cursor is on a number, the commands apply to that number; otherwise
  Vim uses the number to the right of the cursor.
- When 'nrformats' includes "hex", Vim assumes numbers starting with '0x' or
  '0X' are hexadecimal.  The case of the rightmost letter in the number
  determines the case of the resulting hexadecimal number.  If there is no
  letter in the current number, Vim uses the previously detected case.
- When 'nrformats' includes "alpha", Vim will change the alphabetic character
  under or after the cursor.  This is useful to make lists with an alphabetic
  index.

For decimals a leading negative sign is considered for incrementing/
decrementing, for binary, octal and hex values, it won't be considered.  To
ignore the sign Visually select the number before using CTRL-A or CTRL-X.

For numbers with leading zeros (including all octal and hexadecimal numbers),
Vim preserves the number of characters in the number when possible.  CTRL-A on
"0077" results in "0100", CTRL-X on "0x100" results in "0x0ff".
There is one exception: When a number that starts with a zero is found not to
be octal (it contains a '8' or '9'), but 'nrformats' does include "octal",
leading zeros are removed to avoid that the result may be recognized as an
octal number.

Note that when 'nrformats' includes "octal", decimal numbers with leading
zeros cause mistakes, because they can be confused with octal numbers.

Note similarly, when 'nrformats' includes "bin", binary numbers with a leading
'0x' or '0X' can be interpreted as hexadecimal rather than binary since '0b'
are valid hexadecimal digits.

The CTRL-A command is very useful in a macro.  Example: Use the following
steps to make a numbered list.

1. Create the first list entry, make sure it starts with a number.
2. qa        - start recording into register 'a'
3. Y         - yank the entry
4. p         - put a copy of the entry below the first one
5. CTRL-A    - increment the number
6. q         - stop recording
7. <count>@a - repeat the yank, put and increment <count> times



SHIFTING LINES LEFT OR RIGHT                            shift-left-right


                                                        <
<{motion}               Shift {motion} lines one 'shiftwidth' leftwards.

                        If the 'vartabstop' feature is enabled, and the
                        'shiftwidth' option is set to zero, the amount of
                        indent is calculated at the first non-blank character
                        in the line.

                                                        <<
<<                      Shift [count] lines one 'shiftwidth' leftwards.


                                                        v_<
{Visual}[count]<        Shift the highlighted lines [count] 'shiftwidth'
                        leftwards (for {Visual} see Visual-mode).


                                                        >
 >{motion}              Shift {motion} lines one 'shiftwidth' rightwards.

                        If the 'vartabstop' feature is enabled, and the
                        'shiftwidth' option is set to zero, the amount of
                        indent is calculated at the first non-blank character
                        in the line.

                                                        >>
 >>                     Shift [count] lines one 'shiftwidth' rightwards.


                                                        v_>
{Visual}[count]>        Shift the highlighted lines [count] 'shiftwidth'
                        rightwards (for {Visual} see Visual-mode).


                                                        :<
:[range]<               Shift [range] lines one 'shiftwidth' left.  Repeat '<'
                        for shifting multiple 'shiftwidth's.

:[range]< {count}       Shift {count} lines one 'shiftwidth' left, starting
                        with [range] (default current line cmdline-ranges).
                        Repeat '<' for shifting multiple 'shiftwidth's.

:[range]le[ft] [indent] left align lines in [range].  Sets the indent in the
                        lines to [indent] (default 0).


                                                        :>
:[range]> [flags]       Shift {count} [range] lines one 'shiftwidth' right.
                        Repeat '>' for shifting multiple 'shiftwidth's.
                        See ex-flags for [flags].

:[range]> {count} [flags]
                        Shift {count} lines one 'shiftwidth' right, starting
                        with [range] (default current line cmdline-ranges).
                        Repeat '>' for shifting multiple 'shiftwidth's.
                        See ex-flags for [flags].

The ">" and "<" commands are handy for changing the indentation within
programs.  Use the 'shiftwidth' option to set the size of the white space
which these commands insert or delete.  Normally the 'shiftwidth' option is 8,
but you can set it to, say, 3 to make smaller indents.  The shift leftwards
stops when there is no indent.  The shift right does not affect empty lines.

If the 'shiftround' option is on, the indent is rounded to a multiple of
'shiftwidth'.

If the 'smartindent' option is on, or 'cindent' is on and 'cinkeys' contains
'#' with a zero value, shift right does not affect lines starting with '#'
(these are supposed to be C preprocessor lines that must stay in column 1).
This can be changed with the 'cino' option, see cino-#.

When the 'expandtab' option is off (this is the default) Vim uses <Tab>s as
much as possible to make the indent.  You can use ">><<" to replace an indent
made out of spaces with the same indent made out of <Tab>s (and a few spaces
if necessary).  If the 'expandtab' option is on, Vim uses only spaces.  Then
you can use ">><<" to replace <Tab>s in the indent by spaces (or use
`:retab!`).

To move a line several 'shiftwidth's, use Visual mode or the `:` commands.
For example:
        Vjj4>           move three lines 4 indents to the right
        :<<<            move current line 3 indents to the left
        :>> 5           move 5 lines 2 indents to the right
        :5>>            move line 5 2 indents to the right

==============================================================================

4. Complex changes                                      complex-change


4.1 Filter commands                                     filter

A filter is a program that accepts text at standard input, changes it in some
way, and sends it to standard output.  You can use the commands below to send
some text through a filter, so that it is replaced by the filter output.
Examples of filters are "sort", which sorts lines alphabetically, and
"indent", which formats C program files (you need a version of indent that
works like a filter; not all versions do).  The 'shell' option specifies the
shell Vim uses to execute the filter command (See also the 'shelltype'
option).  You can repeat filter commands with ".".  Vim does not recognize a
comment (starting with '"'') after the `:!` command.


                                                        !
!{motion}{filter}       Filter {motion} text lines through the external
                        program {filter}.


                                                        !!
!!{filter}              Filter [count] lines through the external program
                        {filter}.


                                                        v_!
{Visual}!{filter}       Filter the highlighted lines through the external
                        program {filter} (for {Visual} see Visual-mode).


:{range}![!]{filter} [!][arg]                           :range!
                        Filter {range} lines through the external program
                        {filter}.  Vim replaces the optional bangs with the
                        latest given command and appends the optional [arg].
                        Vim saves the output of the filter command in a
                        temporary file and then reads the file into the buffer
                        tempfile.  Vim uses the 'shellredir' option to
                        redirect the filter output to the temporary file.
                        However, if the 'shelltemp' option is off then pipes
                        are used when possible (on Unix).
                        When the 'R' flag is included in 'cpoptions' marks in
                        the filtered lines are deleted, unless the
                        :keepmarks command is used.  Example:
                                :keepmarks '<,'>!sort
                        When the number of lines after filtering is less than
                        before, marks in the missing lines are deleted anyway.


                                                        =
={motion}               Filter {motion} lines through the external program
                        given with the 'equalprg' option.  When the 'equalprg'
                        option is empty (this is the default), use the
                        internal formatting function C-indenting and
                        'lisp'.  But when 'indentexpr' is not empty, it will
                        be used instead indent-expression.  When Vim was
                        compiled without internal formatting then the "indent"
                        program is used as a last resort.


                                                        ==
==                      Filter [count] lines like with ={motion}.


                                                        v_=
{Visual}=               Filter the highlighted lines like with ={motion}.



                                                tempfile setuid
Vim uses temporary files for filtering, generating diffs and also for
tempname().  For Unix, the file will be in a private directory (only
accessible by the current user) to avoid security problems (e.g., a symlink
attack or other people reading your file).  When Vim exits the directory and
all files in it are deleted.  When Vim has the setuid bit set this may cause
problems, the temp file is owned by the setuid user but the filter command
probably runs as the original user.
Directory for temporary files is created in the first of these directories
that works:
        Unix:    $TMPDIR, /tmp, current-dir, $HOME.
        Windows: $TMP, $TEMP, c:\TMP, c:\TEMP
For MS-Windows the GetTempFileName() system function is used.
For other systems the tmpnam() library function is used.




4.2 Substitute                                          :substitute

                                                        :s :su
:[range]s[ubstitute]/{pattern}/{string}/[flags] [count]
                        For each line in [range] replace a match of {pattern}
                        with {string}.
                        For the {pattern} see pattern.
                        {string} can be a literal string, or something
                        special; see sub-replace-special.
                        When [range] and [count] are omitted, replace in the
                        current line only.  When [count] is given, replace in
                        [count] lines, starting with the last line in [range].
                        When [range] is omitted start in the current line.

                                                        E939
                        [count] must be a positive number.  Also see
                        cmdline-ranges.

                        See :s_flags for [flags].
                        The delimiter doesn't need to be /, see
                        pattern-delimiter.

:[range]s[ubstitute] [flags] [count]

:[range]&[&][flags] [count]                                     :&
                        Repeat last :substitute with same search pattern and
                        substitute string, but without the same flags.  You
                        may add [flags], see :s_flags.
                        Note that after `:substitute` the '&' flag can't be
                        used, it's recognized as a pattern separator.
                        The space between `:substitute` and the 'c', 'g',
                        'i', 'I' and 'r' flags isn't required, but in scripts
                        it's a good idea to keep it to avoid confusion.
                        Also see the two and three letter commands to repeat
                        :substitute below :substitute-repeat.


:[range]~[&][flags] [count]                                     :~
                        Repeat last substitute with same substitute string
                        but with last used search pattern.  This is like
                        `:&r`.  See :s_flags for [flags].


                                                                &
&                       Synonym for `:s` (repeat last substitute).  Note
                        that the flags are not remembered, thus it might
                        actually work differently.  You can use `:&&` to keep
                        the flags.


                                                                g&
g&                      Synonym for `:%s//~/&` (repeat last substitute with
                        last search pattern on all lines with the same flags).
                        For example, when you first do a substitution with
                        `:s/pattern/repl/flags` and then `/search` for
                        something else, `g&` will do `:%s/search/repl/flags`.
                        Mnemonic: global substitute.


                                                :snomagic :sno
:[range]sno[magic] ...  Same as `:substitute`, but always use 'nomagic'.


                                                :smagic :sm
:[range]sm[agic] ...    Same as `:substitute`, but always use 'magic'.


                                                        :s_flags
The flags that you can use for the substitute commands:


                                                        :&&
[&]     Must be the first one: Keep the flags from the previous substitute
        command.  Examples:
                :&&
                :s/this/that/&
        Note that `:s` and `:&` don't keep the flags.

[c]     Confirm each substitution.  Vim highlights the matching string (with

        hl-IncSearch).  You can type:                         :s_c
            'y'     to substitute this match
            'l'     to substitute this match and then quit ("last")
            'n'     to skip this match
            <Esc>   to quit substituting
            'a'     to substitute this and all remaining matches
            'q'     to quit substituting
            CTRL-E  to scroll the screen up
            CTRL-Y  to scroll the screen down
        If the 'edcompatible' option is on, Vim remembers the [c] flag and
        toggles it each time you use it, but resets it when you give a new
        search pattern.


                                                        :s_e
[e]     When the search pattern fails, do not issue an error message and, in
        particular, continue in maps as if no error occurred.  This is most
        useful to prevent the "No match" error from breaking a mapping.  Vim
        does not suppress the following error messages, however:
                Regular expressions can't be delimited by letters
                \ should be followed by /, ? or &
                No previous substitute regular expression
                Trailing characters
                Interrupted


                                                        :s_g
[g]     Replace all occurrences in the line.  Without this argument,
        replacement occurs only for the first occurrence in each line.  If
        the 'edcompatible' option is on, Vim remembers this flag and toggles
        it each time you use it, but resets it when you give a new search
        pattern.  If the 'gdefault' option is on, this flag is on by default
        and the [g] argument switches it off.


                                                        :s_i
[i]     Ignore case for the pattern.  The 'ignorecase' and 'smartcase' options
        are not used.


                                                        :s_I
[I]     Don't ignore case for the pattern.  The 'ignorecase' and 'smartcase'
        options are not used.


                                                        :s_n
[n]     Report the number of matches, do not actually substitute.  The [c]
        flag is ignored.  The matches are reported as if 'report' is zero.
        Useful to count-items.
        If \= sub-replace-expression is used, the expression will be
        evaluated in the sandbox at every match.


[p]     Print the line containing the last substitute.  :s_p


[#]     Like [p] and prepend the line number.  :s_#


[l]     Like [p] but print the text like :list.  :s_l


                                                        :s_r
[r]     Only useful in combination with `:&` or `:s` without arguments.  `:&r`
        works the same way as `:~`:  When the search pattern is empty, use the
        previously used search pattern instead of the search pattern from the
        last substitute or `:global`.  If the last command that did a search
        was a substitute or `:global`, there is no effect.  If the last
        command was a search command such as "/", use the pattern from that
        command.
        For `:s` with an argument this already happens:
                :s/blue/red/
                /green
                :s//red/   or  :~   or  :&r
        The last commands will replace "green" with "red".
                :s/blue/red/
                /green
                :&
        The last command will replace "blue" with "red".

Note that there is no flag to change the "magicness" of the pattern.  A
different command is used instead, or you can use /\v and friends.  The
reason is that the flags can only be found by skipping the pattern, and in
order to skip the pattern the "magicness" must be known.  Catch 22!

If the {pattern} for the substitute command is empty, the command uses the
pattern from the last substitute or `:global` command.  If there is none, but
there is a previous search pattern, that one is used.  With the [r] flag, the
command uses the pattern from the last substitute, `:global`, or search
command.

If the {string} is omitted the substitute is done as if it's empty.  Thus the
matched pattern is deleted.  The separator after {pattern} can also be left
out then.  Example:
        :%s/TESTING
This deletes "TESTING" from all lines, but only one per line.

                                                                E1270
For compatibility with Vi these two exceptions are allowed in legacy script:
"\/{string}/" and "\?{string}?" do the same as "//{string}/r".
"\&{string}&" does the same as "//{string}/".

                                pattern-delimiter E146 E1241 E1242
Instead of the '/' which surrounds the pattern and replacement string, you can
use another single-byte character.  This is useful if you want to include a
'/' in the search pattern or replacement string.  Example:
        :s+/+//+

You can use most characters, but not an alphanumeric character, '\', '"'' or
'|'.  In Vim9 script you should not use '#' because it may be recognized as
the start of a comment.

For the definition of a pattern, see pattern.  In Visual block mode, use
/\%V   in the pattern to have the substitute work in the block only.
Otherwise it works on whole lines anyway.


                                        sub-replace-special :s\=
When the {string} starts with "\=" it is evaluated as an expression, see
sub-replace-expression  .  You can use that for complex replacement or special
characters.


The substitution is limited in recursion to 4 levels. E1290

Otherwise these characters in {string} have a special meaning:

                                                                :s%
When {string} is equal to "%" and '/' is included with the 'cpoptions' option,
then the {string} of the previous substitute command is used, see cpo-/

magic   nomagic   action    

  &       \&      replaced with the whole matched pattern            s/\&
 \&        &      replaced with &

      \0          replaced with the whole matched pattern          \0 s/\0
      \1          replaced with the matched pattern in the first

                  pair of ()                                         s/\1
      \2          replaced with the matched pattern in the second

                  pair of ()                                         s/\2

      ..          ..                                                 s/\3
      \9          replaced with the matched pattern in the ninth

                  pair of ()                                         s/\9
  ~       \~      replaced with the {string} of the previous

                  substitute                                         s~

 \~        ~      replaced with ~                                    s/\~

      \u          next character made uppercase                      s/\u

      \U          following characters made uppercase, until \E      s/\U

      \l          next character made lowercase                      s/\l

      \L          following characters made lowercase, until \E      s/\L

      \e          end of \u, \U, \l and \L (NOTE: not <Esc>!)        s/\e

      \E          end of \u, \U, \l and \L                           s/\E
      <CR>        split line in two at this point

                  (Type the <CR> as CTRL-V <Enter>)                  s<CR>

      \r          idem                                               s/\r
      \<CR>       insert a carriage-return (CTRL-M)

                  (Type the <CR> as CTRL-V <Enter>)                  s/\<CR>
      \n          insert a <NL> (<NUL> in the file)

                  (does NOT break the line)                          s/\n

      \b          insert a <BS>                                      s/\b

      \t          insert a <Tab>                                     s/\t

      \\          insert a single backslash                          s/\\
      \x          where x is any character not mentioned above:
                  Reserved for future expansion

The special meaning is also used inside the third argument {sub} of
the substitute() function with the following exceptions:
  - A % inserts a percent literally without regard to 'cpoptions'.
  - magic is always set without regard to 'magic'.
  - A ~ inserts a tilde literally.
  - <CR> and \r inserts a carriage-return (CTRL-M).
  - \<CR> does not have a special meaning. It's just one of \x.

Examples:
  :s/a\|b/xxx\0xxx/g             modifies "a b"      to "xxxaxxx xxxbxxx"
  :s/\([abc]\)\([efg]\)/\2\1/g   modifies "af fa bg" to "fa fa gb"
  :s/abcde/abc^Mde/              modifies "abcde"    to "abc", "de" (two lines)
  :s/$/\^M/                      modifies "abcde"    to "abcde^M"
  :s/\w\+/\u\0/g                 modifies "bla bla"  to "Bla Bla"
  :s/\w\+/\L\u\0/g               modifies "BLA bla"  to "Bla Bla"

Note: "\L\u" can be used to capitalize the first letter of a word.  This is
not compatible with Vi and older versions of Vim, where the "\u" would cancel
out the "\L". Same for "\U\l".

Note: In previous versions CTRL-V was handled in a special way.  Since this is
not Vi compatible, this was removed.  Use a backslash instead.

command         text    result 
:s/aa/a^Ma/     aa      a<line-break>a
:s/aa/a\^Ma/    aa      a^Ma
:s/aa/a\\^Ma/   aa      a\<line-break>a

(you need to type CTRL-V <CR> to get a ^M here)

The numbering of "\1", "\2" etc. is done based on which "\(" comes first in
the pattern (going left to right).  When a parentheses group matches several
times, the last one will be used for "\1", "\2", etc.  Example:
  :s/\(\(a[a-d] \)*\)/\2/      modifies "aa ab x" to "ab x"
The "\2" is for "\(a[a-d] \)".  At first it matches "aa ", secondly "ab ".

When using parentheses in combination with '|', like in \([ab]\)\|\([cd]\),
either the first or second pattern in parentheses did not match, so either
\1 or \2 is empty.  Example:
  :s/\([ab]\)\|\([cd]\)/\1x/g   modifies "a b c d"  to "ax bx x x"
 


                :sc :sce :scg :sci :scI :scl :scp :sg :sgc

                :sge :sgi :sgI :sgl :sgn :sgp :sgr :sI :si

                :sic :sIc :sie :sIe :sIg :sIl :sin :sIn :sIp

                :sip :sIr :sir :sr :src :srg :sri :srI :srl

                :srn :srp :substitute-repeat
2-letter and 3-letter :substitute commands 

These commands repeat the previous `:substitute` command with the given flags.
The first letter is always "s", followed by one or two of the possible flag
characters.  For example `:sce` works like `:s///ce`.  The table lists the
possible combinations, not all flags are possible, because the command is
short for another command.

     List of :substitute commands
     |      c    e    g    i    I    n    p    l    r
     | c  :sc  :sce :scg :sci :scI :scn :scp :scl
     | e
     | g  :sgc :sge :sg  :sgi :sgI :sgn :sgp :sgl :sgr
     | i  :sic :sie      :si  :siI :sin :sip      :sir
     | I  :sIc :sIe :sIg :sIi :sI  :sIn :sIp :sIl :sIr
     | n
     | p
     | l
     | r  :src      :srg :sri :srI :srn :srp :srl :sr

Exceptions:
     :scr  is  `:scriptnames`
     :se   is  `:set`
     :sig  is  `:sign`
     :sil  is  `:silent`
     :sn   is  `:snext`
     :sp   is  `:split`
     :sl   is  `:sleep`
     :sre  is  `:srewind`



Substitute with an expression                   sub-replace-expression

                                                sub-replace-\= s/\=
When the substitute string starts with "\=" the remainder is interpreted as an
expression.

The special meaning for characters as mentioned at sub-replace-special does
not apply except for "<CR>".  A <NL> character is used as a line break, you
can get one with a double-quote string: "\n".  Prepend a backslash to get a
real <NL> character (which will be a NUL in the file).

The "\=" notation can also be used inside the third argument {sub} of
substitute()   function.  In this case, the special meaning for characters as
mentioned at sub-replace-special does not apply at all. Especially, <CR> and
<NL> are interpreted not as a line break but as a carriage-return and a
new-line respectively.

When the result is a List then the items are joined with separating line
breaks.  Thus each item becomes a line, except that they can contain line
breaks themselves.

The submatch() function can be used to obtain matched text.  The whole
matched text can be accessed with "submatch(0)".  The text matched with the
first pair of () with "submatch(1)".  Likewise for further sub-matches in ().

Be careful: The separation character must not appear in the expression!
Consider using a character like "@" or ":".  There is no problem if the result
of the expression contains the separation character.

Examples:
        :s@\n@\="\r" .. expand("$HOME") .. "\r"@
This replaces an end-of-line with a new line containing the value of $HOME.

        s/E/\="\<Char-0x20ac>"/g
This replaces each 'E' character with a euro sign.  Read more in <Char->.



4.3 Search and replace                                  search-replace


                                                        :pro :promptfind
:promptf[ind] [string]
                        Put up a Search dialog.  When [string] is given, it is
                        used as the initial search string.
                        {only for Win32, Motif and GTK GUI}


                                                :promptr :promptrepl
:promptr[epl] [string]
                        Put up a Search/Replace dialog.  When [string] is
                        given, it is used as the initial search string.
                        {only for Win32, Motif and GTK GUI}



4.4 Changing tabs                                       change-tabs

                                                        :ret :retab :retab!
:[range]ret[ab][!] [new_tabstop]
                        Replace all sequences of white-space containing a
                        <Tab> with new strings of white-space using the new
                        tabstop value given.  If you do not specify a new
                        tabstop size or it is zero, Vim uses the current value
                        of 'tabstop'.
                        The current value of 'tabstop' is always used to
                        compute the width of existing tabs.
                        With !, Vim also replaces strings of only normal
                        spaces with tabs where appropriate.
                        With 'expandtab' on, Vim replaces all tabs with the
                        appropriate number of spaces.
                        This command sets 'tabstop' to the new value given,
                        and if performed on the whole file, which is default,
                        should not make any visible change.
                        Careful: This command modifies any <Tab> characters
                        inside of strings in a C program.  Use "\t" to avoid
                        this (that's a good habit anyway).
                        `:retab!` may also change a sequence of spaces by
                        <Tab> characters, which can mess up a printf().
                        If the +vartabs feature is enabled then a list of
                        tab widths separated by commas may be used in place of
                        a single tabstop.  Each value in the list represents
                        the width of one tabstop, except the final value which
                        applies to all following tabstops.


                                                        retab-example
Example for using autocommands and ":retab" to edit a file which is stored
with tabstops at 8 but edited with tabstops set at 4.  Warning: white space
inside of strings can change!  Also see 'softtabstop' option.

  :auto BufReadPost     *.xx    retab! 4
  :auto BufWritePre     *.xx    retab! 8
  :auto BufWritePost    *.xx    retab! 4
  :auto BufNewFile      *.xx    set ts=4

==============================================================================

5. Copying and moving text                              copy-move


                                                        quote
"{register}             Use {register} for next delete, yank or put.  Use
                        an uppercase character to append with delete and yank.
                        Registers ".", "%", "#" and ":" only work with put.


                                                        :reg :registers
:reg[isters]            Display the type and contents of all numbered and
                        named registers.  If a register is written to for
                        :redir it will not be listed.
                        Type can be one of:
                        "c"     for characterwise text
                        "l"     for linewise text
                        "b"     for blockwise-visual text


:reg[isters] {arg}      Display the contents of the numbered and named
                        registers that are mentioned in {arg}.  For example:
                                :reg 1a
                        to display registers '1' and 'a'.  Spaces are allowed
                        in {arg}.


                                                        :di :display
:di[splay] [arg]        Same as :registers.


                                                        y yank
["x]y{motion}           Yank {motion} text [into register x].  When no
                        characters are to be yanked (e.g., "y0" in column 1),
                        this is an error when 'cpoptions' includes the 'E'
                        flag.


                                                        yy
["x]yy                  Yank [count] lines [into register x] linewise.


                                                        Y
["x]Y                   yank [count] lines [into register x] (synonym for
                        yy, linewise).  If you like "Y" to work from the
                        cursor to the end of line (which is more logical,
                        but not Vi-compatible) use ":map Y y$".


                                                        zy
["x]zy{motion}          Yank {motion} text [into register x].  Only differs
                        from `y` when selecting a block of text, see v_zy.


                                                        v_y
{Visual}["x]y           Yank the highlighted text [into register x] (for
                        {Visual} see Visual-mode).


                                                        v_Y
{Visual}["x]Y           Yank the highlighted lines [into register x] (for
                        {Visual} see Visual-mode).


                                                        v_zy
{Visual}["x]zy          Yank the highlighted text [into register x].  Trailing
                        whitespace at the end of each line of a selected block
                        won't be yanked.  Especially useful in combination
                        with `zp`.  (for {Visual} see Visual-mode)


                                                        :y :yank E850
:[range]y[ank] [x]      Yank [range] lines [into register x]. Yanking to the
                        "* or "+ registers is possible only when the
                        +clipboard feature is included.

:[range]y[ank] [x] {count}
                        Yank {count} lines, starting with last line number
                        in [range] (default: current line cmdline-ranges),
                        [into register x].


                                                p put E353 E1240
["x]p                   Put the text [from register x] after the cursor
                        [count] times.


                                                        P
["x]P                   Put the text [from register x] before the cursor
                        [count] times.


                                                        <MiddleMouse>
["x]<MiddleMouse>       Put the text from a register before the cursor [count]
                        times.  Uses the "* register, unless another is
                        specified.
                        Leaves the cursor at the end of the new text.
                        Using the mouse only works when 'mouse' contains 'n'
                        or 'a'.
                        If you have a scrollwheel and often accidentally paste
                        text, you can use these mappings to disable the
                        pasting with the middle mouse button:
                                :map <MiddleMouse> <Nop>
                                :imap <MiddleMouse> <Nop>
                        You might want to disable the multi-click versions
                        too, see double-click.


                                                        gp
["x]gp                  Just like "p", but leave the cursor just after the new
                        text.


                                                        gP
["x]gP                  Just like "P", but leave the cursor just after the new
                        text.


                                                        :pu :put
:[line]pu[t] [x]        Put the text [from register x] after [line] (default
                        current line).  This always works linewise, thus
                        this command can be used to put a yanked block as new
                        lines.
                        If no register is specified, it depends on the 'cb'
                        option: If 'cb' contains "unnamedplus", paste from the
                        + register quoteplus.  Otherwise, if 'cb' contains
                        "unnamed", paste from the * register quotestar.
                        Otherwise, paste from the unnamed register
                        quote_quote.
                        The register can also be '=' followed by an optional
                        expression.  The expression continues until the end of
                        the command.  You need to escape the '|' and '"''
                        characters to prevent them from terminating the
                        command.  Example:
                                :put ='path' .. \",/test\"
                        If there is no expression after '=', Vim uses the
                        previous expression.  You can see it with ":dis =".

:[line]pu[t]! [x]       Put the text [from register x] before [line] (default
                        current line).


["x]]p              or                                  ]p ]<MiddleMouse>
["x]]<MiddleMouse>      Like "p", but adjust the indent to the current line.
                        Using the mouse only works when 'mouse' contains 'n'
                        or 'a'.


["x][P              or                                  [P

["x]]P              or                                  ]P

["x][p              or                                  [p [<MiddleMouse>
["x][<MiddleMouse>      Like "P", but adjust the indent to the current line.
                        Using the mouse only works when 'mouse' contains 'n'
                        or 'a'.


["x]zp              or                                  zp zP
["x]zP                  Like "p" and "P", except without adding trailing spaces
                        when pasting a block.  Thus the inserted text will not
                        always be a rectangle.  Especially useful in
                        combination with v_zy.

You can use these commands to copy text from one place to another.  Do this
by first getting the text into a register with a yank, delete or change
command, then inserting the register contents with a put command.  You can
also use these commands to move text from one file to another, because Vim
preserves all registers when changing buffers (the CTRL-^ command is a quick
way to toggle between two files).


                                linewise-register characterwise-register
You can repeat the put commands with "." (except for :put) and undo them.  If
the command that was used to get the text into the register was linewise,
Vim inserts the text below ("p") or above ("P") the line where the cursor is.
Otherwise Vim inserts the text after ("p") or before ("P") the cursor.  With
the ":put" command, Vim always inserts the text in the next line.  You can
exchange two characters with the command sequence "xp".  You can exchange two
lines with the command sequence "ddp".  You can exchange two words with the
command sequence "deep" (start with the cursor in the blank space before the
first word).  You can use the "']" or "`]" command after the put command to
move the cursor to the end of the inserted text, or use "'[" or "`[" to move
the cursor to the start.


                                                put-Visual-mode v_p v_P
When using a put command like p or P in Visual mode, Vim will try to
replace the selected text with the contents of the register.  Whether this
works well depends on the type of selection and the type of the text in the
register.  With blockwise selection it also depends on the size of the block
and whether the corners are on an existing character.  (Implementation detail:
it actually works by first putting the register after the selection and then
deleting the selection.)
With p the previously selected text is put in the unnamed register (and
possibly the selection and/or clipboard).  This is useful if you want to put
that text somewhere else.  But you cannot repeat the same change.
With P the unnamed register is not changed (and neither the selection or
clipboard), you can repeat the same change. But the deleted text cannot be
used.  If you do need it you can use p with another register.  E.g., yank
the text to copy, Visually select the text to replace and use "0p .  You can
repeat this as many times as you like, and the unnamed register will be
changed each time.

                                                        blockwise-put
When a register contains text from one line (characterwise), using a
blockwise Visual selection, putting that register will paste that text
repeatedly in each of the selected lines, thus replacing the blockwise
selected region by multiple copies of the register text.  For example:
        - yank the word "TEXT" into a register with `yw`
        - select a visual block, marked with "v" in this text:
            aaavvaaa
            bbbvvbbb
            cccvvccc
        - press `p`, results in:
            aaaTEXTaaa
            bbbTEXTbbb
            cccTEXTccc


                                                        blockwise-register
If you use a blockwise Visual mode command to get the text into the register,
the block of text will be inserted before ("P") or after ("p") the cursor
column in the current and next lines.  Vim makes the whole block of text start
in the same column.  Thus the inserted text looks the same as when it was
yanked or deleted.  Vim may replace some <Tab> characters with spaces to make
this happen.  However, if the width of the block is not a multiple of a <Tab>
width and the text after the inserted block contains <Tab>s, that text may be
misaligned.

Use zP/zp to paste a blockwise yanked register without appending trailing
spaces.

Note that after a characterwise yank command, Vim leaves the cursor on the
first yanked character that is closest to the start of the buffer.  This means
that "yl" doesn't move the cursor, but "yh" moves the cursor one character
left.
Rationale:      In Vi the "y" command followed by a backwards motion would
                sometimes not move the cursor to the first yanked character,
                because redisplaying was skipped.  In Vim it always moves to
                the first character, as specified by Posix.
With a linewise yank command the cursor is put in the first line, but the
column is unmodified, thus it may not be on the first yanked character.


There are ten types of registers:               registers {register} E354
1. The unnamed register ""
2. 10 numbered registers "0 to "9
3. The small delete register "-
4. 26 named registers "a to "z or "A to "Z
5. Three read-only registers ":, "., "%
6. Alternate buffer register "#
7. The expression register "=
8. The selection and drop registers "*, "+ and "~ 
9. The black hole register "_
10. Last search pattern register "/


1. Unnamed register ""                          quote_quote quotequote
Vim fills this register with text deleted with the "d", "c", "s", "x" commands
or copied with the yank "y" command, regardless of whether or not a specific
register was used (e.g.  "xdd).  This is like the unnamed register is pointing
to the last used register.  Thus when appending using an uppercase register
name, the unnamed register contains the same text as the named register.
An exception is the '_' register: "_dd does not store the deleted text in any
register.
Vim uses the contents of the unnamed register for any put command (p or P)
which does not specify a register.  Additionally you can access it with the
name '"''.  This means you have to type two double quotes.  Writing to the ""
register writes to register "0.
{Vi: register contents are lost when changing files, no '"''}


2. Numbered registers "0 to "9          quote_number quote0 quote1

                                        quote2 quote3 quote4 quote9
Vim fills these registers with text from yank and delete commands.
   Numbered register 0 contains the text from the most recent yank command,
unless the command specified another register with ["x].
   Numbered register 1 contains the text deleted by the most recent delete or
change command, unless the command specified another register or the text is
less than one line (the small delete register is used then).  An exception is
made for the delete operator with these movement commands: %, (, ), `,
/  , ?, n, N, { and }.  Register "1 is always used then (this is Vi
compatible).  The "- register is used as well if the delete is within a line.
Note that these characters may be mapped.  E.g. % is mapped by the matchit
plugin.
   With each successive deletion or change, Vim shifts the previous contents
of register 1 into register 2, 2 into 3, and so forth, losing the previous
contents of register 9.
{Vi: numbered register contents are lost when changing files; register 0 does
not exist}


3. Small delete register "-                             quote_- quote-
This register contains text from commands that delete less than one line,
except when the command specifies a register with ["x].


4. Named registers "a to "z or "A to "Z                 quote_alpha quotea
Vim fills these registers only when you say so.  Specify them as lowercase
letters to replace their previous contents or as uppercase letters to append
to their previous contents.  When the '>' flag is present in 'cpoptions' then
a line break is inserted before the appended text.

5. Read-only registers ":, ". and "%
These are '%', ':' and '.'.  You can use them only with the "p", "P",
and ":put" commands and with CTRL-R.

                                                quote_. quote. E29
        ".      Contains the last inserted text (the same as what is inserted
                with the insert mode commands CTRL-A and CTRL-@).  Note: this
                doesn't work with CTRL-R on the command-line.  It works a bit
                differently, like inserting the text instead of putting it
                ('textwidth' and other options affect what is inserted).

                                                        quote_% quote%
        "%      Contains the name of the current file.

                                                quote_: quote: E30
        ":      Contains the most recent executed command-line.  Example: Use
                "@:" to repeat the previous command-line command.
                The command-line is only stored in this register when at least
                one character of it was typed.  Thus it remains unchanged if
                the command was completely from a mapping.
                {not available when compiled without the +cmdline_hist
                feature}

                                                        quote_# quote#
6. Alternate file register "#
Contains the name of the alternate file for the current window.  It will
change how the CTRL-^ command works.
This register is writable, mainly to allow for restoring it after a plugin has
changed it.  It accepts buffer number:
    let altbuf = bufnr(@#)
    ...
    let @# = altbuf
It will give error E86 if you pass buffer number and this buffer does not
exist.
It can also accept a match with an existing buffer name:
    let @# = 'buffer_name'
Error E93 if there is more than one buffer matching the given name or E94
if none of buffers matches the given name.


7. Expression register "=                       quote_= quote= @=
This is not really a register that stores text, but is a way to use an
expression in commands which use a register.  The expression register is
read-write.

When typing the '=' after " or CTRL-R the cursor moves to the command-line,
where you can enter any expression (see expression).  All normal
command-line editing commands are available, including a special history for
expressions.  When you end the command-line by typing <CR>, Vim computes the
result of the expression.  If you end it with <Esc>, Vim abandons the
expression.  If you do not enter an expression, Vim uses the previous
expression (like with the "/" command).

The expression must evaluate to a String.  A Number is always automatically
converted to a String.  For the "p" and ":put" command, if the result is a
Float it's converted into a String.  If the result is a List each element is
turned into a String and used as a line.  A Dictionary or FuncRef results in
an error message (use string() to convert).

If the "= register is used for the "p" command, the String is split up at <NL>
characters.  If the String ends in a <NL>, it is regarded as a linewise
register.

8. Selection and drop registers "*, "+ and "~ 
Use these registers for storing and retrieving the selected text for the GUI.
See quotestar and quoteplus.  When the clipboard is not available or not
working, the unnamed register is used instead.  For Unix systems the clipboard
is only available when the +xterm_clipboard feature is present.

Note that there is only a distinction between "* and "+ for X11 systems.  For
an explanation of the difference, see x11-selection.  Under MS-Windows, use
of "* and "+ is actually synonymous and refers to the gui-clipboard.


                                                quote_~ quote~ <Drop>
The read-only "~ register stores the dropped text from the last drag'n'drop
operation.  When something has been dropped onto Vim, the "~ register is
filled in and the <Drop> pseudo key is sent for notification.  You can remap
this key if you want; the default action (for all modes) is to insert the
contents of the "~ register at the cursor position.
{only available when compiled with the +dnd feature, currently only with the
GTK GUI}

Note: The "~ register is only used when dropping plain text onto Vim.
Drag'n'drop of URI lists is handled internally.


9. Black hole register "_                               quote_
When writing to this register, nothing happens.  This can be used to delete
text without affecting the normal registers.  When reading from this register,
nothing is returned.

10. Last search pattern register        "/              *quote_/* *quote/*
Contains the most recent search-pattern.  This is used for "n" and 'hlsearch'.
It is writable with `:let`, you can change it to have 'hlsearch' highlight
other matches without actually searching.  You can't yank or delete into this
register.  The search direction is available in v:searchforward.
Note that the value is restored when returning from a function
function-search-undo  .


                                                        @/
You can write to a register with a `:let` command :let-@.  Example:
        :let @/ = "the"

If you use a put command without specifying a register, Vim uses the register
that was last filled (this is also the contents of the unnamed register).  If
you are confused, use the `:dis` command to find out what Vim will put (this
command displays all named and numbered registers; the unnamed register is
labelled '"'').

The next three commands always work on whole lines.


:[range]co[py] {address}                                :co :copy
                        Copy the lines given by [range] to below the line
                        given by {address}.


                                                        :t
:t                      Synonym for copy.
                        This command is not supported in Vim9 script,
                        because it is too easily confused with a variable
                        name.


:[range]m[ove] {address}                        :m :mo :move E134
                        Move the lines given by [range] to below the line
                        given by {address}.

==============================================================================

6. Formatting text                                      formatting


:[range]ce[nter] [width]                                :ce :center
                        Center lines in [range] between [width] columns
                        (default 'textwidth' or 80 when 'textwidth' is 0).


:[range]ri[ght] [width]                                 :ri :right
                        Right-align lines in [range] at [width] columns
                        (default 'textwidth' or 80 when 'textwidth' is 0).


                                                        :le :left
:[range]le[ft] [indent]
                        Left-align lines in [range].  Sets the indent in the
                        lines to [indent] (default 0).


                                                        gq
gq{motion}              Format the lines that {motion} moves over.
                        Formatting is done with one of three methods:
                        1. If 'formatexpr' is not empty the expression is
                           evaluated.  This can differ for each buffer.
                        2. If 'formatprg' is not empty an external program
                           is used.
                        3. Otherwise formatting is done internally.

                        In the third case the 'textwidth' option controls the
                        length of each formatted line (see below).
                        If the 'textwidth' option is 0, the formatted line
                        length is the screen width (with a maximum width of
                        79).
                        The 'formatoptions' option controls the type of
                        formatting fo-table.
                        The cursor is left on the first non-blank of the last
                        formatted line.
                        NOTE: The "Q" command formerly performed this
                        function.  If you still want to use "Q" for
                        formatting, use this mapping:
                                :nnoremap Q gq


gqgq                                                    gqgq gqq
gqq                     Format the current line.  With a count format that
                        many lines.


                                                        v_gq
{Visual}gq              Format the highlighted text.  (for {Visual} see
                        Visual-mode).


                                                        gw
gw{motion}              Format the lines that {motion} moves over.  Similar to
                        gq but puts the cursor back at the same position in
                        the text.  However, 'formatprg' and 'formatexpr' are
                        not used.


gwgw                                                    gwgw gww
gww                     Format the current line as with "gw".


                                                        v_gw
{Visual}gw              Format the highlighted text as with "gw".  (for
                        {Visual} see Visual-mode).


Example: To format the current paragraph use:                   gqap 
        gqap

The "gq" command leaves the cursor in the line where the motion command takes
the cursor.  This allows you to repeat formatting repeated with ".".  This
works well with "gqj" (format current and next line) and "gq}" (format until
end of paragraph).  Note: When 'formatprg' is set, "gq" leaves the cursor on
the first formatted line (as with using a filter command).

If you want to format the current paragraph and continue where you were, use:
        gwap
If you always want to keep paragraphs formatted you may want to add the 'a'
flag to 'formatoptions'.  See auto-format.

If the 'autoindent' option is on, Vim uses the indent of the first line for
the following lines.

Formatting does not change empty lines (but it does change lines with only
white space!).

The 'joinspaces' option is used when lines are joined together.

You can set the 'formatexpr' option to an expression or the 'formatprg' option
to the name of an external program for Vim to use for text formatting.  The
'textwidth' and other options have no effect on formatting by an external
program.


                                                        format-formatexpr
The 'formatexpr' option can be set to a Vim script function that performs
reformatting of the buffer.  This should usually happen in an ftplugin,
since formatting is highly dependent on the type of file.  It makes
sense to use an autoload script, so the corresponding script is only loaded
when actually needed and the script should be called <filetype>format.vim.

For example, the XML filetype plugin distributed with Vim in the $VIMRUNTIME
directory, sets the 'formatexpr' option to:

   setlocal formatexpr=xmlformat#Format()

That means, you will find the corresponding script, defining the
xmlformat#Format() function, in the directory:
`$VIMRUNTIME/autoload/xmlformat.vim`

Here is an example script that removes trailing whitespace from the selected
text.  Put it in your autoload directory, e.g. ~/.vim/autoload/format.vim:

  func! format#Format()
    " only reformat on explicit gq command
    if mode() != 'n'
      " fall back to Vim's internal reformatting
      return 1
    endif
    let lines = getline(v:lnum, v:lnum + v:count - 1)
    call map(lines, {key, val -> substitute(val, '\s\+$', '', 'g')})
    call setline('.', lines)

    " do not run internal formatter!
    return 0
  endfunc

You can then enable the formatting by executing:
  setlocal formatexpr=format#Format()

Note: this function explicitly returns non-zero when called from insert mode
(which basically means, text is inserted beyond the 'textwidth' limit).  This
causes Vim to fall back to reformat the text by using the internal formatter.

However, if the gq command is used to reformat the text, the function
will receive the selected lines, trim trailing whitespace from those lines and
put them back in place.  If you are going to split single lines into multiple
lines, be careful not to overwrite anything.

If you want to allow reformatting of text from insert or replace mode, one has
to be very careful, because the function might be called recursively.  For
debugging it helps to set the 'debug' option.


                                                        right-justify
There is no command in Vim to right justify text.  You can do it with
an external command, like "par" (e.g.: "!}par" to format until the end of the
paragraph) or set 'formatprg' to "par".


                                                        format-comments
An overview of comment formatting is in section 30.6 of the user manual.

Vim can automatically insert and format comments in a special way.  Vim
recognizes a comment by a specific string at the start of the line (ignoring
white space).  Three types of comments can be used:

- A comment string that repeats at the start of each line.  An example is the
  type of comment used in shell scripts, starting with "#".
- A comment string that occurs only in the first line, not in the following
  lines.  An example is this list with dashes.
- Three-piece comments that have a start string, an end string, and optional
  lines in between.  The strings for the start, middle and end are different.
  An example is the C style comment:
        /*
         * this is a C comment
         */

The 'comments' option is a comma-separated list of parts.  Each part defines a
type of comment string.  A part consists of:
        {flags}:{string}

{string} is the literal text that must appear.

{flags}:
  n     Nested comment.  Nesting with mixed parts is allowed.  If 'comments'
        is "n:),n:>" a line starting with "> ) >" is a comment.

  b     Blank (<Space>, <Tab> or <EOL>) required after {string}.

  f     Only the first line has the comment string.  Do not repeat comment on
        the next line, but preserve indentation (e.g., a bullet-list).

  s     Start of three-piece comment

  m     Middle of a three-piece comment

  e     End of a three-piece comment

  l     Left align. Used together with 's' or 'e', the leftmost character of
        start or end will line up with the leftmost character from the middle.
        This is the default and can be omitted. See below for more details.

  r     Right align. Same as above but rightmost instead of leftmost. See
        below for more details.

  O     Don't consider this comment for the "O" command.

  x     Allows three-piece comments to be ended by just typing the last
        character of the end-comment string as the first action on a new
        line when the middle-comment string has been inserted automatically.
        See below for more details.

  {digits}
        When together with 's' or 'e': add {digit} amount of offset to an
        automatically inserted middle or end comment leader. The offset begins
        from a left alignment. See below for more details.

  -{digits}
        Like {digits} but reduce the indent.  This only works when there is
        some indent for the start or end part that can be removed.

When a string has none of the 'f', 's', 'm' or 'e' flags, Vim assumes the
comment string repeats at the start of each line.  The flags field may be
empty.

Any blank space in the text before and after the {string} is part of the
{string}, so do not include leading or trailing blanks unless the blanks are a
required part of the comment string.

When one comment leader is part of another, specify the part after the whole.
For example, to include both "-" and "->", use
        :set comments=f:->,f:-

A three-piece comment must always be given as start,middle,end, with no other
parts in between.  An example of a three-piece comment is
        sr:/*,mb:*,ex:*/
for C-comments.  To avoid recognizing "*ptr" as a comment, the middle string
includes the 'b' flag.  For three-piece comments, Vim checks the text after
the start and middle strings for the end string.  If Vim finds the end string,
the comment does not continue on the next line.  Three-piece comments must
have a middle string because otherwise Vim can't recognize the middle lines.

Notice the use of the "x" flag in the above three-piece comment definition.
When you hit Return in a C-comment, Vim will insert the middle comment leader
for the new line: " * ".  To close this comment you just have to type "/"
before typing anything else on the new line.  This will replace the
middle-comment leader with the end-comment leader and apply any specified
alignment, leaving just " */".  There is no need to hit Backspace first.

When there is a match with a middle part, but there also is a matching end
part which is longer, the end part is used.  This makes a C style comment work
without requiring the middle part to end with a space.

Here is an example of alignment flags at work to make a comment stand out
(kind of looks like a 1 too). Consider comment string:
        :set comments=sr:/***,m:**,ex-2:******/
 
                                   /*** 
                                     **<--right aligned from "r" flag 
                                     ** 
offset 2 spaces for the "-2" flag--->** 
                                   ******/ 
In this case, the first comment was typed, then return was pressed 4 times,
then "/" was pressed to end the comment.

Here are some finer points of three part comments. There are three times when
alignment and offset flags are taken into consideration: opening a new line
after a start-comment, opening a new line before an end-comment, and
automatically ending a three-piece comment.  The end alignment flag has a
backwards perspective; the result is that the same alignment flag used with
"s" and "e" will result in the same indent for the starting and ending pieces.
Only one alignment per comment part is meant to be used, but an offset number
will override the "r" and "l" flag.

Enabling 'cindent' will override the alignment flags in many cases.
Reindenting using a different method like gq or = will not consult
alignment flags either. The same behaviour can be defined in those other
formatting options. One consideration is that 'cindent' has additional options
for context based indenting of comments but cannot replicate many three piece
indent alignments.  However, 'indentexpr' has the ability to work better with
three piece comments.

Other examples:
   "b:*"        Includes lines starting with "*", but not if the "*" is
                followed by a non-blank.  This avoids a pointer dereference
                like "*str" to be recognized as a comment.
   "n:>"        Includes a line starting with ">", ">>", ">>>", etc.
   "fb:-"       Format a list that starts with "- ".

By default, "b:#" is included.  This means that a line that starts with
"#include" is not recognized as a comment line.  But a line that starts with
"# define" is recognized.  This is a compromise.


                                                        fo-table
You can use the 'formatoptions' option  to influence how Vim formats text.
'formatoptions' is a string that can contain any of the letters below.  The
default setting is "tcq".  You can separate the option letters with commas for
readability.

letter   meaning when present in 'formatoptions'    

                                                        fo-t
t       Auto-wrap text using 'textwidth'

                                                        fo-c
c       Auto-wrap comments using 'textwidth', inserting the current comment
        leader automatically.

                                                        fo-r
r       Automatically insert the current comment leader after hitting
        <Enter> in Insert mode.

                                                        fo-o
o       Automatically insert the current comment leader after hitting 'o' or
        'O' in Normal mode.  In case comment is unwanted in a specific place
        use CTRL-U to quickly delete it. i_CTRL-U

                                                        fo-/
/       When 'o' is included: do not insert the comment leader for a //
        comment after a statement, only when // is at the start of the line.

                                                        fo-q
q       Allow formatting of comments with "gq".
        Note that formatting will not change blank lines or lines containing
        only the comment leader.  A new paragraph starts after such a line,
        or when the comment leader changes.

                                                        fo-w
w       Trailing white space indicates a paragraph continues in the next line.
        A line that ends in a non-white character ends a paragraph.

                                                        fo-a
a       Automatic formatting of paragraphs.  Every time text is inserted or
        deleted the paragraph will be reformatted.  See auto-format.
        When the 'c' flag is present this only happens for recognized
        comments.

                                                        fo-n
n       When formatting text, recognize numbered lists.  This actually uses
        the 'formatlistpat' option, thus any kind of list can be used.  The
        indent of the text after the number is used for the next line.  The
        default is to find a number, optionally followed by '.', ':', ')',
        ']' or '}'.  Note that 'autoindent' must be set too.  Doesn't work
        well together with "2".
        Example:
                1. the first item
                   wraps
                2. the second item

                                                        fo-2
2       When formatting text, use the indent of the second line of a paragraph
        for the rest of the paragraph, instead of the indent of the first
        line.  This supports paragraphs in which the first line has a
        different indent than the rest.  Note that 'autoindent' must be set
        too.  Example:
                        first line of a paragraph
                second line of the same paragraph
                third line.
        This also works inside comments, ignoring the comment leader.

                                                        fo-v
v       Vi-compatible auto-wrapping in insert mode: Only break a line at a
        blank that you have entered during the current insert command.  (Note:
        this is not 100% Vi compatible.  Vi has some "unexpected features" or
        bugs in this area.  It uses the screen column instead of the line
        column.)

                                                        fo-b
b       Like 'v', but only auto-wrap if you enter a blank at or before
        the wrap margin.  If the line was longer than 'textwidth' when you
        started the insert, or you do not enter a blank in the insert before
        reaching 'textwidth', Vim does not perform auto-wrapping.

                                                        fo-l
l       Long lines are not broken in insert mode: When a line was longer than
        'textwidth' when the insert command started, Vim does not
        automatically format it.

                                                        fo-m
m       Also break at a multibyte character above 255.  This is useful for
        Asian text where every character is a word on its own.

                                                        fo-M
M       When joining lines, don't insert a space before or after a multibyte
        character.  Overrules the 'B' flag.

                                                        fo-B
B       When joining lines, don't insert a space between two multibyte
        characters.  Overruled by the 'M' flag.

                                                        fo-1
1       Don't break a line after a one-letter word.  It's broken before it
        instead (if possible).

                                                        fo-]
]       Respect 'textwidth' rigorously. With this flag set, no line can be
        longer than 'textwidth', unless line-break-prohibition rules make this
        impossible.  Mainly for CJK scripts and works only if 'encoding' is
        "utf-8".

                                                        fo-j
j       Where it makes sense, remove a comment leader when joining lines.  For
        example, joining:
                int i;   // the index 
                         // in the list 
        Becomes:
                int i;   // the index in the list 

                                                        fo-p
p       Don't break lines at single spaces that follow periods.  This is
        intended to complement 'joinspaces' and cpo-J, for prose with
        sentences separated by two spaces.  For example, with 'textwidth' set
        to 28:
                Surely you're joking, Mr. Feynman!
        Becomes:
                Surely you're joking,
                Mr. Feynman!
        Instead of:
                Surely you're joking, Mr.
                Feynman!


With 't' and 'c' you can specify when Vim performs auto-wrapping:
value   action  
""      no automatic formatting (you can use "gq" for manual formatting)
"t"     automatic formatting of text, but not comments
"c"     automatic formatting for comments, but not text (good for C code)
"tc"    automatic formatting for text and comments

Note that when 'textwidth' is 0, Vim does no automatic formatting anyway (but
does insert comment leaders according to the 'comments' option).  An exception
is when the 'a' flag is present. auto-format

Note that when 'paste' is on, Vim does no formatting at all.

Note that 'textwidth' can be non-zero even if Vim never performs auto-wrapping;
'textwidth' is still useful for formatting with "gq".

If the 'comments' option includes "/*", "*" and/or "*/", then Vim has some
built in stuff to treat these types of comments a bit more cleverly.
Opening a new line before or after "/*" or "*/" (with 'r' or 'o' present in
'formatoptions') gives the correct start of the line automatically.  The same
happens with formatting and auto-wrapping.  Opening a line after a line
starting with "/*" or "*" and containing "*/", will cause no comment leader to
be inserted, and the indent of the new line is taken from the line containing
the start of the comment.
E.g.:
    /* 
     * Your typical comment. 
     */ 
    The indent on this line is the same as the start of the above
    comment.

All of this should be really cool, especially in conjunction with the new
:autocmd command to prepare different settings for different types of file.

Some examples:
  for C code (only format comments):
        :set fo=croq
  for Mail/news (format all, don't start comment with "o" command):
        :set fo=tcrq
 


Automatic formatting                            auto-format autoformat

When the 'a' flag is present in 'formatoptions' text is formatted
automatically when inserting text or deleting text.  This works nicely for
editing text paragraphs.  A few hints on how to use this:

- You need to properly define paragraphs.  The simplest is paragraphs that are
  separated by a blank line.  When there is no separating blank line, consider
  using the 'w' flag and adding a space at the end of each line in the
  paragraphs except the last one.

- You can set the 'formatoptions' based on the type of file filetype or
  specifically for one file with a modeline.

- Set 'formatoptions' to "aw2tq" to make text with indents like this:

            bla bla foobar bla 
        bla foobar bla foobar bla
            bla bla foobar bla 
        bla foobar bla bla foobar

- Add the 'c' flag to only auto-format comments.  Useful in source code.

- Set 'textwidth' to the desired width.  If it is zero then 79 is used, or the
  width of the screen if this is smaller.

And a few warnings:

- When part of the text is not properly separated in paragraphs, making
  changes in this text will cause it to be formatted anyway.  Consider doing

        :set fo-=a

- When using the 'w' flag (trailing space means paragraph continues) and
  deleting the last line of a paragraph with dd, the paragraph will be
  joined with the next one.

- Changed text is saved for undo.  Formatting is also a change.  Thus each
  format action saves text for undo.  This may consume quite a lot of memory.

- Formatting a long paragraph and/or with complicated indenting may be slow.

==============================================================================

7. Sorting text                                         sorting

Vim has a sorting function and a sorting command.  The sorting function can be
found here: sort(), uniq().


                                                        :sor :sort
:[range]sor[t][!] [b][f][i][l][n][o][r][u][x] [/{pattern}/]
                        Sort lines in [range].  When no range is given all
                        lines are sorted.

                        With [!] the order is reversed.

                        With [i] case is ignored.

                        With [l] sort uses the current collation locale.
                        Implementation details: strcoll() is used to compare
                        strings. See :language to check or set the collation
                        locale. Example:
                                :language collate en_US.UTF-8
                                :%sort l
                        v:collate can also used to check the current locale.
                        Sorting using the locale typically ignores case.
                        This does not work properly on Mac.

                        Options [n][f][x][o][b] are mutually exclusive.

                        With [n] sorting is done on the first decimal number
                        in the line (after or inside a {pattern} match).
                        One leading '-' is included in the number.

                        With [f] sorting is done on the Float in the line.
                        The value of Float is determined similar to passing
                        the text (after or inside a {pattern} match) to
                        str2float() function. This option is available only
                        if Vim was compiled with Floating point support.

                        With [x] sorting is done on the first hexadecimal
                        number in the line (after or inside a {pattern}
                        match).  A leading "0x" or "0X" is ignored.
                        One leading '-' is included in the number.

                        With [o] sorting is done on the first octal number in
                        the line (after or inside a {pattern} match).

                        With [b] sorting is done on the first binary number in
                        the line (after or inside a {pattern} match).

                        With [u] (u stands for unique) only keep the first of
                        a sequence of identical lines (ignoring case when [i]
                        is used).  Without this flag, a sequence of identical
                        lines will be kept in their original order.
                        Note that leading and trailing white space may cause
                        lines to be different.

                        When /{pattern}/ is specified and there is no [r] flag
                        the text matched with {pattern} is skipped, so that
                        you sort on what comes after the match.
                        'ignorecase' applies to the pattern, but 'smartcase'
                        is not used.
                        Instead of the slash any non-letter can be used.
                        For example, to sort on the second comma-separated
                        field:
                                :sort /[^,]*,/
                        To sort on the text at virtual column 10 (thus
                        ignoring the difference between tabs and spaces):
                                :sort /.*\%10v/
                        To sort on the first number in the line, no matter
                        what is in front of it:
                                :sort /.\{-}\ze\d/
                        (Explanation: ".\{-}" matches any text, "\ze" sets the
                        end of the match and \d matches a digit.)
                        With [r] sorting is done on the matching {pattern}
                        instead of skipping past it as described above.
                        For example, to sort on only the first three letters
                        of each line:
                                :sort /\a\a\a/ r

                        If a {pattern} is used, any lines which don't have a
                        match for {pattern} are kept in their current order,
                        but separate from the lines which do match {pattern}.
                        If you sorted in reverse, they will be in reverse
                        order after the sorted lines, otherwise they will be
                        in their original order, right before the sorted
                        lines.

                        If {pattern} is empty (e.g. // is specified), the
                        last search pattern is used.  This allows trying out
                        a pattern first.

Note that using `:sort` with `:global` doesn't sort the matching lines, it's
quite useless.

`:sort` does not use the current locale unless the l flag is used.
Vim does do a "stable" sort.

The sorting can be interrupted, but if you interrupt it too late in the
process you may end up with duplicated lines.  This also depends on the system
library function used.