vim

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

vim.man (24454B)


      1 VIM(1)                      General Commands Manual                     VIM(1)
      2 
      3 NAME
      4        vim - Vi IMproved, a programmer's text editor
      5 
      6 SYNOPSIS
      7        vim [options] [file ..]
      8        vim [options] -
      9        vim [options] -t tag
     10        vim [options] -q [errorfile]
     11 
     12        ex
     13        view
     14        gvim gview evim eview
     15        rvim rview rgvim rgview
     16 
     17 DESCRIPTION
     18        Vim  is a text editor that is upwards compatible to Vi.  It can be used
     19        to edit all kinds of plain text.  It is especially useful  for  editing
     20        programs.
     21 
     22        There  are a lot of enhancements above Vi: multi level undo, multi win‐
     23        dows and buffers, syntax highlighting, command line  editing,  filename
     24        completion,   on-line   help,   visual  selection,  etc..   See  ":help
     25        vi_diff.txt" for a summary of the differences between Vim and Vi.
     26 
     27        While running Vim a lot of help can be obtained from the  on-line  help
     28        system, with the ":help" command.  See the ON-LINE HELP section below.
     29 
     30        Most often Vim is started to edit a single file with the command
     31 
     32             vim file
     33 
     34        More generally Vim is started with:
     35 
     36             vim [options] [filelist]
     37 
     38        If the filelist is missing, the editor will start with an empty buffer.
     39        Otherwise  exactly  one out of the following four may be used to choose
     40        one or more files to be edited.
     41 
     42        file ..     A list of filenames.  The first one  will  be  the  current
     43                    file  and  read  into the buffer.  The cursor will be posi‐
     44                    tioned on the first line of the buffer.  You can get to the
     45                    other files with the ":next" command.  To edit a file  that
     46                    starts with a dash, precede the filelist with "--".
     47 
     48        -           The  file  to  edit  is read from stdin.  Commands are read
     49                    from stderr, which should be a tty.
     50 
     51        -t {tag}    The file to edit and the initial cursor position depends on
     52                    a "tag", a sort of goto label.  {tag} is looked up  in  the
     53                    tags file, the associated file becomes the current file and
     54                    the  associated  command  is executed.  Mostly this is used
     55                    for C programs, in which case {tag}  could  be  a  function
     56                    name.  The effect is that the file containing that function
     57                    becomes  the  current  file and the cursor is positioned on
     58                    the start of the function.  See ":help tag-commands".
     59 
     60        -q [errorfile]
     61                    Start in quickFix mode.  The file [errorfile] is  read  and
     62                    the  first  error is displayed.  If [errorfile] is omitted,
     63                    the filename is obtained from the 'errorfile'  option  (de‐
     64                    faults to "AztecC.Err" for the Amiga, "errors.err" on other
     65                    systems).   Further  errors can be jumped to with the ":cn"
     66                    command.  See ":help quickfix".
     67 
     68        Vim behaves differently, depending on the name of the command (the exe‐
     69        cutable may still be the same file).
     70 
     71        vim       The "normal" way, everything is default.
     72 
     73        ex        Start in Ex mode.  Go to Normal mode with the ":vi"  command.
     74                  Can also be done with the "-e" argument.
     75 
     76        view      Start  in read-only mode.  You will be protected from writing
     77                  the files.  Can also be done with the "-R" argument.
     78 
     79        gvim gview
     80                  The GUI version.  Starts a new window.  Can also be done with
     81                  the "-g" argument.
     82 
     83        evim eview
     84                  The GUI version in easy mode.  Starts a new window.  Can also
     85                  be done with the "-y" argument.
     86 
     87        rvim rview rgvim rgview
     88                  Like the above, but with restrictions.  It will not be possi‐
     89                  ble to start shell commands, or suspend  Vim.   Can  also  be
     90                  done with the "-Z" argument.
     91 
     92 OPTIONS
     93        The  options may be given in any order, before or after filenames.  Op‐
     94        tions without an argument can be combined after a single dash.
     95 
     96        +[num]      For the first file the cursor will be  positioned  on  line
     97                    "num".   If "num" is missing, the cursor will be positioned
     98                    on the last line.
     99 
    100        +/{pat}     For the first file the cursor will  be  positioned  in  the
    101                    line  with  the  first  occurrence  of  {pat}.   See ":help
    102                    search-pattern" for the available search patterns.
    103 
    104        +{command}
    105 
    106        -c {command}
    107                    {command} will be executed after the first  file  has  been
    108                    read.   {command}  is interpreted as an Ex command.  If the
    109                    {command} contains spaces it must  be  enclosed  in  double
    110                    quotes  (this depends on the shell that is used).  Example:
    111                    vim "+set si" main.c
    112                    Note: You can use up to 10 "+" or "-c" commands.
    113 
    114        -A          If Vim has been compiled with ARABIC  support  for  editing
    115                    right-to-left  oriented  files and Arabic keyboard mapping,
    116                    this option starts Vim in Arabic  mode,  i.e.  'arabic'  is
    117                    set.  Otherwise an error message is given and Vim aborts.
    118 
    119        -b          Binary  mode.  A few options will be set that makes it pos‐
    120                    sible to edit a binary or executable file.
    121 
    122        -C          Compatible.  Set the 'compatible' option.  This  will  make
    123                    Vim  behave  mostly  like Vi, even though a .vimrc file ex‐
    124                    ists.
    125 
    126        -d          Start in diff mode.  There should between two to eight file
    127                    name arguments.  Vim will open all the files and show  dif‐
    128                    ferences between them.  Works like vimdiff(1).
    129 
    130        -d {device}, -dev {device}
    131                    Open  {device}  for  use as a terminal.  Only on the Amiga.
    132                    Example: "-d con:20/30/600/150".
    133 
    134        -D          Debugging.  Go to debugging mode when executing  the  first
    135                    command from a script.
    136 
    137        -e          Start  Vim  in Ex mode, just like the executable was called
    138                    "ex".
    139 
    140        -display {display}
    141                    Run Vim on {display}, connecting to that X  server  instead
    142                    of  the  one in $DISPLAY.  The "--display" long form is ac‐
    143                    cepted only by the GTK+ 2 or GTK+ 3 GUI.   Both  forms  re‐
    144                    quire the +xterm_clipboard feature.
    145 
    146        -E          Start Vim in improved Ex mode, just like the executable was
    147                    called "exim".
    148 
    149        -f          Foreground.  For the GUI version, Vim will not fork and de‐
    150                    tach  from  the shell it was started in.  On the Amiga, Vim
    151                    is not restarted to open a new window.  This option  should
    152                    be  used  when  Vim is executed by a program that will wait
    153                    for the edit session to finish (e.g. mail).  On  the  Amiga
    154                    the ":sh" and ":!" commands will not work.
    155 
    156        -F          If  Vim  has  been  compiled with FKMAP support for editing
    157                    right-to-left oriented files and  Farsi  keyboard  mapping,
    158                    this  option  starts  Vim  in  Farsi mode, i.e. 'fkmap' and
    159                    'rightleft' are set.  Otherwise an error message  is  given
    160                    and Vim aborts.
    161                    Note: Farsi support has been removed in patch 8.1.0932.
    162 
    163        -g          If  Vim has been compiled with GUI support, this option en‐
    164                    ables the GUI.  If no GUI support was compiled in, an error
    165                    message is given and Vim aborts.
    166 
    167        -H          If Vim has been compiled with RIGHTLEFT support for editing
    168                    right-to-left oriented files and Hebrew  keyboard  mapping,
    169                    this  option  starts  Vim  in Hebrew mode, i.e. 'hkmap' and
    170                    'rightleft' are set.  Otherwise an error message  is  given
    171                    and Vim aborts.
    172 
    173        -i {viminfo}
    174                    Specifies  the  filename to use when reading or writing the
    175                    viminfo file, instead of the  default  "~/.viminfo".   This
    176                    can  also  be used to skip the use of the .viminfo file, by
    177                    giving the name "NONE".
    178 
    179        -l          Lisp mode.  Sets the 'lisp' and 'showmatch' options on.
    180 
    181        -L          Same as -r.
    182 
    183        -m          Modifying files is disabled.  Resets  the  'write'  option.
    184                    You  can still modify the buffer, but writing a file is not
    185                    possible.
    186 
    187        -M          Modifications not allowed.  The  'modifiable'  and  'write'
    188                    options  will be unset, so that changes are not allowed and
    189                    files can not be written.  Note that these options  can  be
    190                    set to enable making modifications.
    191 
    192        -n          No  swap file will be used.  Recovery after a crash will be
    193                    impossible.  Handy if you want to edit a  file  on  a  very
    194                    slow  medium  (e.g.  floppy).   Can also be done with ":set
    195                    uc=0".  Can be undone with ":set uc=200".
    196 
    197        -N          No-compatible mode.  Resets the 'compatible' option.   This
    198                    will  make Vim behave a bit better, but less Vi compatible,
    199                    even though a .vimrc file does not exist.
    200 
    201        -nb         Become an editor server for NetBeans.  See the docs for de‐
    202                    tails.
    203 
    204        -o[N]       Open N windows stacked.  When N is omitted, open one window
    205                    for each file.
    206 
    207        -O[N]       Open N windows side by side.  When N is omitted,  open  one
    208                    window for each file.
    209 
    210        -p[N]       Open N tab pages.  When N is omitted, open one tab page for
    211                    each file.
    212 
    213        -P {parent-title}
    214                    Win32  GUI  only:  Specify the title of the parent applica‐
    215                    tion.  When possible, Vim will run in an MDI window  inside
    216                    the  application.  {parent-title} must appear in the window
    217                    title of the parent application.  Make sure that it is spe‐
    218                    cific enough. Note that the implementation is still  primi‐
    219                    tive.   It  won't  work  with all applications and the menu
    220                    doesn't work.
    221 
    222        -r          List swap files, with information about using them for  re‐
    223                    covery.
    224 
    225        -r {file}   Recovery  mode.  The swap file is used to recover a crashed
    226                    editing session.  The swap file is a  file  with  the  same
    227                    filename as the text file with ".swp" appended.  See ":help
    228                    recovery".
    229 
    230        -R          Read-only  mode.   The  'readonly' option will be set.  You
    231                    can still edit the buffer, but will be prevented from acci‐
    232                    dentally overwriting a file.  If you do want to overwrite a
    233                    file, add an exclamation mark to  the  Ex  command,  as  in
    234                    ":w!".   The  -R  option  also  implies  the -n option (see
    235                    above).  The 'readonly' option  can  be  reset  with  ":set
    236                    noro".  See ":help 'readonly'".
    237 
    238        -s          Silent  mode.   Only  when started as "Ex" or when the "-e"
    239                    option was given before the "-s" option.
    240 
    241        -s {scriptin}
    242                    The script file {scriptin} is read.  The characters in  the
    243                    file  are  interpreted  as if you had typed them.  The same
    244                    can be done with the command ":source! {scriptin}".  If the
    245                    end of the file is reached before the editor exits, further
    246                    characters are read from the keyboard.
    247 
    248        -S {file}   {file} will be sourced after the first file has been  read.
    249                    This  is  equivalent  to -c "source {file}".  {file} cannot
    250                    start with '-'.  If {file} is omitted "Session.vim" is used
    251                    (only works when -S is the last argument).
    252 
    253        -T {terminal}
    254                    Tells Vim the name of the terminal you are using.  Only re‐
    255                    quired when the automatic way doesn't work.   Should  be  a
    256                    terminal  known  to Vim (builtin) or defined in the termcap
    257                    or terminfo file.
    258 
    259        -u {vimrc}  Use the commands in the file {vimrc}  for  initializations.
    260                    All  the  other  initializations  are skipped.  Use this to
    261                    edit a special kind of files.  It can also be used to  skip
    262                    all  initializations by giving the name "NONE".  See ":help
    263                    initialization" within vim for more details.
    264 
    265        -U {gvimrc} Use the commands in the file {gvimrc} for  GUI  initializa‐
    266                    tions.   All the other GUI initializations are skipped.  It
    267                    can also be used to skip all GUI initializations by  giving
    268                    the  name "NONE".  See ":help gui-init" within vim for more
    269                    details.
    270 
    271        -v          Start Vim in Vi mode, just like the executable  was  called
    272                    "vi".   This  only has effect when the executable is called
    273                    "ex".
    274 
    275        -V[N]       Verbose.  Give messages about which files are  sourced  and
    276                    for  reading and writing a viminfo file.  The optional num‐
    277                    ber N is the value for 'verbose'.  Default is 10.
    278 
    279        -V[N]{filename}
    280                    Like -V and set 'verbosefile' to {filename}.  The result is
    281                    that messages are not displayed but  written  to  the  file
    282                    {filename}.  {filename} must not start with a digit.
    283 
    284        -w{number}  Set the 'window' option to {number}.
    285 
    286        -w {scriptout}
    287                    All  the  characters that you type are recorded in the file
    288                    {scriptout}, until you exit Vim.  This  is  useful  if  you
    289                    want  to  create  a script file to be used with "vim -s" or
    290                    ":source!".  If the {scriptout} file exists, characters are
    291                    appended.
    292 
    293        -W {scriptout}
    294                    Like -w, but an existing file is overwritten.
    295 
    296        -x          If Vim has been compiled with encryption support,  use  en‐
    297                    cryption when writing files.  Will prompt for a crypt key.
    298 
    299        -X          Don't  connect to the X server.  Shortens startup time in a
    300                    terminal, but the window title and clipboard  will  not  be
    301                    used.
    302 
    303        -Y          Don't connect to the wayland compositor
    304 
    305        -y          Start Vim in easy mode, just like the executable was called
    306                    "evim"  or "eview".  Makes Vim behave like a click-and-type
    307                    editor.
    308 
    309        -Z          Restricted mode.  Works like  the  executable  starts  with
    310                    "r".
    311 
    312        --          Denotes  the end of the options.  Arguments after this will
    313                    be handled as a file name.  This can  be  used  to  edit  a
    314                    filename that starts with a '-'.
    315 
    316        --clean     Do  not  use  any  personal  configuration (vimrc, plugins,
    317                    etc.).  Useful to see if a problem reproduces with a  clean
    318                    Vim setup.
    319 
    320        --cmd {command}
    321                    Like  using  "-c",  but the command is executed just before
    322                    processing any vimrc file.  You can use up to 10  of  these
    323                    commands, independently from "-c" commands.
    324 
    325        --echo-wid  GTK GUI only: Echo the Window ID on stdout.
    326 
    327        --gui-dialog-file {name}
    328                    When  using the GUI, instead of showing a dialog, write the
    329                    title and message of the dialog to file {name}.   The  file
    330                    is  created  or  appended  to.  Only useful for testing, to
    331                    avoid that the test gets stuck on a dialog  that  can't  be
    332                    seen.  Without the GUI the argument is ignored.
    333 
    334        --help, -h, -?
    335                    Give a bit of help about the command line arguments and op‐
    336                    tions.  After this Vim exits.
    337 
    338        --literal   Take  file  name  arguments  literally, do not expand wild‐
    339                    cards.  This has no effect on Unix where the shell  expands
    340                    wildcards.
    341 
    342        --log {filename}
    343                    If  Vim  has  been  compiled with eval and channel feature,
    344                    start logging and write entries to {filename}.  This  works
    345                    like calling ch_logfile({filename}, 'ao') very early during
    346                    startup.
    347 
    348        --nofork    Foreground.  For the GUI version, Vim will not fork and de‐
    349                    tach from the shell it was started in.
    350 
    351        --noplugin  Skip loading plugins.  Implied by -u NONE.
    352 
    353        --not-a-term
    354                    Tells  Vim that the user knows that the input and/or output
    355                    is not connected to a terminal.  This will avoid the  warn‐
    356                    ing and the two second delay that would happen.
    357 
    358        --prg-name {name}
    359                    Set GTK program name. Only for GTK4 GUI.
    360 
    361        --remote    Connect to a Vim server and make it edit the files given in
    362                    the rest of the arguments.  If no server is found a warning
    363                    is given and the files are edited in the current Vim.
    364 
    365        --remote-expr {expr}
    366                    Connect  to  a  Vim server, evaluate {expr} in it and print
    367                    the result on stdout.
    368 
    369        --remote-send {keys}
    370                    Connect to a Vim server and send {keys} to it.
    371 
    372        --remote-silent
    373                    As --remote, but without the  warning  when  no  server  is
    374                    found.
    375 
    376        --remote-tab
    377                    As --remote, but open each file in a new tabpage.
    378 
    379        --remote-tab-silent
    380                    As --remote-silent, but open each file in a new tabpage.
    381 
    382        --remote-tab-wait
    383                    As --remote-wait, but open each file in a new tabpage.
    384 
    385        --remote-tab-wait-silent
    386                    As  --remote-wait-silent,  but open each file in a new tab‐
    387                    page.
    388 
    389        --remote-wait
    390                    As --remote, but Vim does not exit  until  the  files  have
    391                    been edited.
    392 
    393        --remote-wait-silent
    394                    As --remote-wait, but without the warning when no server is
    395                    found.
    396 
    397        --serverlist
    398                    List the names of all Vim servers that can be found.
    399 
    400        --servername {name}
    401                    Use  {name}  as the server name.  Used for the current Vim,
    402                    unless used with a --remote argument, then it's the name of
    403                    the server to connect to.  If the socketserver  backend  is
    404                    being used, if the name starts with "/", "./", or "../", it
    405                    is  taken  as either an absolute, relative or relative path
    406                    to the socket.
    407 
    408        --clientserver {backend}
    409                    Use {backend} as the backend for  clientserver  functional‐
    410                    ity, either "socket", "x11", or "mswin" respectively.  Only
    411                    available when compiled with both socketserver and X11 fea‐
    412                    tures  present, or if compiled with socketserver on MS-Win‐
    413                    dows. The $VIM_CLIENTSERVER environment variable  may  also
    414                    be  set  which will be interpreted in the same way, but the
    415                    --clientserver argument will always take priority.
    416 
    417        --socketid {id}
    418                    GTK GUI only: Use the GtkPlug mechanism to run gVim in  an‐
    419                    other window.
    420 
    421        --startuptime {file}
    422                    During startup write timing messages to the file {fname}.
    423 
    424        --stdio-channel
    425                    Use  the  stdin  and stdout of Vim for a channel instead of
    426                    for a terminal.  Implies "-es": nothing is displayed, no Ex
    427                    commands are read and the GUI is  not  started.   A  script
    428                    opens  the  channel with ch_open() and the address "stdio",
    429                    see ":help --stdio-channel".  Only available when  compiled
    430                    with the channel feature.
    431 
    432        --ttyfail   When  stdin  or  stdout  is  not a terminal (tty) then exit
    433                    right away.
    434 
    435        --version   Print version information and exit.
    436 
    437        --windowid {id}
    438                    Win32 GUI only: Make gVim try to use the window {id}  as  a
    439                    parent, so that it runs inside that window.
    440 
    441 ON-LINE HELP
    442        Type  ":help"  in Vim to get started.  Type ":help subject" to get help
    443        on a specific subject.  For example: ":help ZZ" to  get  help  for  the
    444        "ZZ"  command.   Use <Tab> and CTRL-D to complete subjects (":help cmd‐
    445        line-completion").  Tags are present to jump from one place to  another
    446        (sort of hypertext links, see ":help").  All documentation files can be
    447        viewed in this way, for example ":help syntax.txt".
    448 
    449 FILES
    450        /usr/local/share/vim/vim??/doc/*.txt
    451                       The  Vim documentation files.  Use ":help doc-file-list"
    452                       to get the complete list.
    453                       vim??  is short version number, like vim91 for Vim 9.1
    454 
    455        /usr/local/share/vim/vim??/doc/tags
    456                       The tags file used for finding information in the  docu‐
    457                       mentation files.
    458 
    459        /usr/local/share/vim/vim??/syntax/syntax.vim
    460                       System wide syntax initializations.
    461 
    462        /usr/local/share/vim/vim??/syntax/*.vim
    463                       Syntax files for various languages.
    464 
    465        /usr/local/share/vim/vimrc
    466                       System wide Vim initializations.
    467 
    468        ~/.vimrc, ~/.vim/vimrc, $XDG_CONFIG_HOME/vim/vimrc
    469                       Your  personal  Vim  initializations (first one found is
    470                       used).
    471 
    472        /usr/local/share/vim/gvimrc
    473                       System wide gvim initializations.
    474 
    475        ~/.gvimrc, ~/.vim/gvimrc, $XDG_CONFIG_HOME/vim/gvimrc
    476                       Your personal gVim initializations (first one  found  is
    477                       used).
    478 
    479        /usr/local/share/vim/vim??/optwin.vim
    480                       Script  used  for  the ":options" command, a nice way to
    481                       view and set options.
    482 
    483        /usr/local/share/vim/vim??/menu.vim
    484                       System wide menu initializations for gVim.
    485 
    486        /usr/local/share/vim/vim??/bugreport.vim
    487                       Script to generate a bug report.  See ":help bugs".
    488 
    489        /usr/local/share/vim/vim??/filetype.vim
    490                       Script to detect the type of a file by  its  name.   See
    491                       ":help 'filetype'".
    492 
    493        /usr/local/share/vim/vim??/scripts.vim
    494                       Script  to  detect  the  type of a file by its contents.
    495                       See ":help 'filetype'".
    496 
    497        /usr/local/share/vim/vim??/print/*.ps
    498                       Files used for PostScript printing.
    499 
    500        For recent info read the VIM home page:
    501        <URL:http://www.vim.org/>
    502 
    503 SEE ALSO
    504        vimtutor(1)
    505 
    506 AUTHOR
    507        Most of Vim was made by Bram Moolenaar, with a lot of help from others.
    508        See ":help credits" in Vim.
    509        Vim is based on Stevie, worked on by: Tim Thompson,  Tony  Andrews  and
    510        G.R. (Fred) Walter.  Although hardly any of the original code remains.
    511 
    512 BUGS
    513        Probably.  See ":help todo" for a list of known problems.
    514 
    515        Note  that a number of things that may be regarded as bugs by some, are
    516        in fact caused by a too-faithful reproduction of Vi's  behaviour.   And
    517        if  you  think  other things are bugs "because Vi does it differently",
    518        you should take a closer look at the vi_diff.txt file  (or  type  :help
    519        vi_diff.txt  when  in  Vim).   Also have a look at the 'compatible' and
    520        'cpoptions' options.
    521 
    522                                   2026 Sep 28                           VIM(1)