cmdline.txt   For Vim version 8.2.  Last change: 2019 Nov 26


                  VIM REFERENCE MANUAL    by Bram Moolenaar


                                Cmdline-mode Command-line-mode
Command-line mode               Cmdline Command-line mode-cmdline :

Command-line mode is used to enter Ex commands (":"), search patterns
("/" and "?"), and filter commands ("!").

Basic command line editing is explained in chapter 20 of the user manual
usr_20.txt.

1. Command-line editing         cmdline-editing
4. Ex command-line ranges       cmdline-ranges
6. Ex special characters        cmdline-special

==============================================================================
1. Command-line editing                                 cmdline-editing

Normally characters are inserted in front of the cursor position.  You can
move around in the command-line with the left and right cursor keys.  With the
<Insert> key, you can toggle between inserting and overstriking characters.

                                                cmdline-history history
The command-lines that you enter are remembered in a history table.  You can
recall them with the up and down cursor keys.  There are actually five
history tables:
- one for ':' commands
- one for search strings
These are completely separate.  Each history can only be accessed when
entering the same type of line.
Use the 'history' option to set the number of lines that are remembered
(default: 50).
Notes:
- When you enter a command-line that is exactly the same as an older one, the
  old one is removed (to avoid repeated commands moving older commands out of
  the history).
- Only commands that are typed are remembered.  Ones that completely come from
  mappings are not put in the history.
- All searches are put in the search history, including the ones that come
  from commands like "*" and "#".  But for a mapping, only the last search is
  remembered (to avoid that long mappings trash the history).


                                                        c_<Left> c_Left
<Left>          cursor left
                                                        c_<Right> c_Right
<Right>         cursor right
                                                        c_<C-Left>
<C-Left>        cursor one WORD left
                                                        c_<C-Right>
<C-Right>       cursor one WORD right
                                                        c_<Home> c_Home
<Home>          cursor to beginning of command-line
                                                        c_<End> c_End
<End>           cursor to end of command-line

                                                        c_<LeftMouse>
<LeftMouse>     Move the cursor to the position of the mouse click.

CTRL-R {register}                                       c_CTRL-R c_<C-R>
                Insert the contents of a numbered or named register.  Between
                typing CTRL-R and the second character '"' will be displayed
                to indicate that you are expected to enter the name of a
                register.
                The text is inserted as if you typed it, but mappings and
                abbreviations are not used.  Command-line completion through
                'wildchar' is not triggered though.

                With jVi, characters less than space are filtered out; so no
                <Esc>, <CR>, <NL>, or any other control characters can be
                entered. But java, so utf-16 is handled.
                Special registers:
                        '"'     the unnamed register, containing the text of
                                the last delete or yank
                        '%'     the current file name
                        '#'     the alternate file name
                        '*'     the clipboard contents (X11: primary selection)
                        '+'     the clipboard contents
                        '/'     the last search pattern
                        ':'     the last command-line
                        '-'     the last small (less than a line) delete
                        '.'     the last inserted text


                                                        c_<Up> c_Up
<Up>            recall older command-line from history, whose beginning
                matches the current command-line (see below).
                                                        c_<Down> c_Down
<Down>          recall more recent command-line from history, whose beginning
                matches the current command-line (see below).

The <Up> and <Down> keys take the current command-line as a search string.
The beginning of the next/previous command-lines are compared with this
string.  The first line that matches is the new command-line.  When typing
these two keys repeatedly, the same string is used again.  For example, this
can be used to find the previous substitute command: Type ":s" and then <Up>.
The same could be done by typing <S-Up> a number of times until the desired
command-line is shown.  (Note: the shifted arrow keys do not work on all
terminals)
                                                        :his :history
:his[tory]      Print the history of last entered commands.

:his[tory] [{name}] [{first}][, [{last}]]
                List the contents of history {name} which can be:
                c[md]    or :           command-line history
                s[earch] or / or ?      search string history
                a[ll]                   all of the above

                If the numbers {first} and/or {last} are given, the respective
                range of entries from a history is listed.  These numbers can
                be specified in the following form:
                                                        :history-indexing
                A positive number represents the absolute index of an entry
                as it is given in the first column of a :history listing.
                This number remains fixed even if other entries are deleted.

                A negative number means the relative position of an entry,
                counted from the newest entry (which has index -1) backwards.

                Examples:
                List entries 6 to 12 from the search history: 
                        :history / 6,12

                List the penultimate entry from all histories: 
                        :history all -2

                List the most recent two entries from all histories: 
                        :history all -2,


==============================================================================
4. Ex command-line ranges       cmdline-ranges [range] E16

Some Ex commands accept a line range in front of them.  This is noted as
[range].  It consists of one or more line specifiers, separated with ','.

The basics are explained in section 10.3 of the user manual.

The default line specifier for most commands is the cursor position, but the
commands ":write" and ":global" have the whole file (1,$) as default.

If more line specifiers are given than required for the command, the first
one(s) will be ignored.

Line numbers may be specified with:             :range {address}
        {number}        an absolute line number  E1247
        .               the current line                          :.
        $               the last line in the file                 :$
        %               equal to 1,$ (the entire file)            :%
        't              position of mark t (lowercase)            :'

Each may be followed (several times) by '+' or '-' and an optional number.
This number is added or subtracted from the preceding line number.  If the
number is omitted, 1 is used.  If there is nothing before the '+' or '-' then
the current line is used.

The {number} must be between 0 and the number of lines in the file.  When
using a 0 (zero) this is interpreted as a 1 by most commands.  Commands that
use it as a count do use it as a zero (:tag, :pop, etc).  Some commands
interpret the zero as "before the first line" (:read, search pattern, etc).

Examples: 
        .+3             three lines below the cursor
        .,$             from current line until end of file


Folds and Range

When folds are active the line numbers are rounded off to include the whole
closed fold.  See fold-behavior.


Reverse Range                                           E493

A range should have the lower line number first.  If this is not the case, Vim
will ask you if it should swap the line numbers.
        Backwards range given, OK to swap 
This is not done within the global command ":g".


Count and Range                                         N:

When giving a count before entering ":", this is translated into:
                :.,.+(count - 1)
In words: The 'count' lines at and after the cursor.  Example: To delete
three lines: 
                3:d<CR>         is translated into: .,.+2d<CR>


Visual Mode and Range
                                                        v_:
{Visual}:       Starts a command-line with the Visual selected lines as a
                range.  The code `:'<,'>` is used for this range, which makes
                it possible to select a similar line from the command-line
                history for repeating a command on different Visually selected
                lines.


==============================================================================
6. Ex special characters                                cmdline-special

Note: These are special characters in the executed command line.  If you want
to insert special things while typing you can use the CTRL-R command.  For
example, "%" stands for the current file name, while CTRL-R % inserts the
current file name right away.  See c_CTRL-R.


In Ex commands, at places where a file name can be used, the following
characters have a special meaning.
        %       Is replaced with the current file name.           :_% c_%
        #       Is replaced with the alternate file name.         :_# c_#
                This is remembered for every window.
        #n      (where n is a number) is replaced with            :_#0 :_#n
                the file name of buffer n.  "#0" is the same as "#".     c_#n
        #-n     (where n is a number) is replaced with
                the file name of buffer n from the mru list.
                See :ls.
        %       Is replaced with the current file name.

If an absolute path is needed (when using the file name from a different
directory), you need to add ":p".  See filename-modifiers.

                                                         filename-modifiers
:_%: ::8 ::p ::. ::~ ::h ::t ::r ::e ::s ::gs ::S
     %:8 %:p %:. %:~ %:h %:t %:r %:e %:s %:gs %:S
The file name modifiers can be used after "%", "#", "#n", "<cfile>", "<sfile>",
"<afile>" or "<abuf>".  They are also used with the fnamemodify() function.

These modifiers can be given, in this order:
        :p      Make file name a full path.  Must be the first modifier.  Also
                changes "~/" (and "~user/" for Unix and VMS) to the path for
                the home directory.  If the name is a directory a path
                separator is added at the end.  For a file name that does not
                exist and does not have an absolute path the result is
                unpredictable.  On MS-Windows an 8.3 filename is expanded to
                the long name.
        :~      Reduce file name to be relative to the home directory, if
                possible.  File name is unmodified if it is not below the home
                directory.
        :.      Reduce file name to be relative to current directory, if
                possible.  File name is unmodified if it is not below the
                current directory.
                For maximum shortness, use ":~:.".
        :h      Head of the file name (the last component and any separators
                removed).  Cannot be used with :e, :r or :t.
                Can be repeated to remove several components at the end.
                When the file name ends in a path separator, only the path
                separator is removed.  Thus ":p:h" on a directory name results
                on the directory name itself (without trailing slash).
                When the file name is an absolute path (starts with "/" for
                Unix; "x:\" for Win32; "drive:" for Amiga), that part is not
                removed.  When there is no head (path is relative to current
                directory) the result is empty.
        :t      Tail of the file name (last component of the name).  Must
                precede any :r or :e.
        :r      Root of the file name (the last extension removed).  When
                there is only an extension (file name that starts with '.',
                e.g., ".vimrc"), it is not removed.  Can be repeated to remove
                several extensions (last one first).
        :e      Extension of the file name.  Only makes sense when used alone.
                When there is no extension the result is empty.
                When there is only an extension (file name that starts with
                '.'), the result is empty.  Can be repeated to include more
                extensions.  If there are not enough extensions (but at least
                one) as much as possible are included.

Examples, when the file name is "src/version.c", current dir
"/home/mool/vim": 
  :p                    /home/mool/vim/src/version.c
  :p:.                                 src/version.c
  :p:~                           ~/vim/src/version.c
  :h                                   src
  :p:h                  /home/mool/vim/src
  :p:h:h                /home/mool/vim
  :t                                       version.c
  :p:t                                     version.c
  :r                                   src/version
  :p:r                  /home/mool/vim/src/version
  :t:r                                     version
  :e                                               c

Examples, when the file name is "src/version.c.gz": 
  :p                    /home/mool/vim/src/version.c.gz
  :e                                                 gz
  :e:e                                             c.gz
  :e:e:e                                           c.gz
  :e:e:r                                           c
  :r                                   src/version.c
  :r:e                                             c
  :r:r                                 src/version
  :r:r:r                               src/version