vim

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

vim.1 (18606B)


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