raw/man1/vi.1

   1 .TH VIM 1 "2002 Feb 22"
   2 .SH NAME
   3 vim \- Vi IMproved, a programmers 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 .br
  26 .B rvim
  27 .B rview
  28 .B rgvim
  29 .B rgview
  30 .SH DESCRIPTION
  31 .B Vim
  32 is a text editor that is upwards compatible to Vi.
  33 It can be used to edit all kinds of plain text.
  34 It is especially useful for editing programs.
  35 .PP
  36 There are a lot of enhancements above Vi: multi level undo,
  37 multi windows and buffers, syntax highlighting, command line
  38 editing, filename completion, on-line help, visual selection, etc..
  39 See ":help vi_diff.txt" for a summary of the differences between
  40 .B Vim
  41 and Vi.
  42 .PP
  43 While running
  44 .B Vim
  45 a lot of help can be obtained from the on-line help system, with the ":help"
  46 command.
  47 See the ON-LINE HELP section below.
  48 .PP
  49 Most often
  50 .B Vim
  51 is started to edit a single file with the command
  52 .PP
  53         vim file
  54 .PP
  55 More generally
  56 .B Vim
  57 is started with:
  58 .PP
  59         vim [options] [filelist]
  60 .PP
  61 If the filelist is missing, the editor will start with an empty buffer.
  62 Otherwise exactly one out of the following four may be used to choose one or
  63 more files to be edited.
  64 .TP 12
  65 file ..
  66 A list of filenames.
  67 The first one will be the current file and read into the buffer.
  68 The cursor will be positioned on the first line of the buffer.
  69 You can get to the other files with the ":next" command.
  70 To edit a file that starts with a dash, precede the filelist with "--".
  71 .TP
  72 -
  73 The file to edit is read from stdin.  Commands are read from stderr, which
  74 should be a tty.
  75 .TP
  76 -t {tag}
  77 The file to edit and the initial cursor position depends on a "tag", a sort
  78 of goto label.
  79 {tag} is looked up in the tags file, the associated file becomes the current
  80 file and the associated command is executed.
  81 Mostly this is used for C programs, in which case {tag} could be a function
  82 name.
  83 The effect is that the file containing that function becomes the current file
  84 and the cursor is positioned on the start of the function.
  85 See ":help tag-commands".
  86 .TP
  87 -q [errorfile]
  88 Start in quickFix mode.
  89 The file [errorfile] is read and the first error is displayed.
  90 If [errorfile] is omitted, the filename is obtained from the 'errorfile'
  91 option (defaults to "AztecC.Err" for the Amiga, "errors.err" on other
  92 systems).
  93 Further errors can be jumped to with the ":cn" command.
  94 See ":help quickfix".
  95 .PP
  96 .B Vim
  97 behaves differently, depending on the name of the command (the executable may
  98 still be the same file).
  99 .TP 10
 100 vim
 101 The "normal" way, everything is default.
 102 .TP
 103 ex
 104 Start in Ex mode.
 105 Go to Normal mode with the ":vi" command.
 106 Can also be done with the "-e" argument.
 107 .TP
 108 view
 109 Start in read-only mode.  You will be protected from writing the files.  Can
 110 also be done with the "-R" argument.
 111 .TP
 112 gvim gview
 113 The GUI version.
 114 Starts a new window.
 115 Can also be done with the "-g" argument.
 116 .TP
 117 rvim rview rgvim rgview
 118 Like the above, but with restrictions.  It will not be possible to start shell
 119 commands, or suspend
 120 .B Vim.
 121 Can also be done with the "-Z" argument.
 122 .SH OPTIONS
 123 The options may be given in any order, before or after filenames.
 124 Options without an argument can be combined after a single dash.
 125 .TP 12
 126 +[num]
 127 For the first file the cursor will be positioned on line "num".
 128 If "num" is missing, the cursor will be positioned on the last line.
 129 .TP
 130 +/{pat}
 131 For the first file the cursor will be positioned on the
 132 first occurrence of {pat}.
 133 See ":help search-pattern" for the available search patterns.
 134 .TP
 135 +{command}
 136 .TP
 137 -c {command}
 138 {command} will be executed after the
 139 first file has been read.
 140 {command} is interpreted as an Ex command.
 141 If the {command} contains spaces it must be enclosed in double quotes (this
 142 depends on the shell that is used).
 143 Example: Vim "+set si" main.c
 144 .br
 145 Note: You can use up to 10 "+" or "-c" commands.
 146 .TP
 147 --cmd {command}
 148 Like using "-c", but the command is executed just before
 149 processing any vimrc file.
 150 You can use up to 10 of these commands, independently from "-c" commands.
 151 .TP
 152 -A
 153 If
 154 .B Vim
 155 has been compiled with ARABIC support for editing right-to-left
 156 oriented files and Arabic keyboard mapping, this option starts
 157 .B Vim
 158 in Arabic mode, i.e. 'arabic' is set.  Otherwise an error
 159 message is given and
 160 .B Vim
 161 aborts.
 162 .TP
 163 -b
 164 Binary mode.
 165 A few options will be set that makes it possible to edit a binary or
 166 executable file.
 167 .TP
 168 -C
 169 Compatible.  Set the 'compatible' option.
 170 This will make
 171 .B Vim
 172 behave mostly like Vi, even though a .vimrc file exists.
 173 .TP
 174 -d
 175 Start in diff mode.
 176 There should be two or three file name arguments.
 177 .B Vim
 178 will open all the files and show differences between them.
 179 Works like vimdiff(1).
 180 .TP
 181 -d {device}
 182 Open {device} for use as a terminal.
 183 Only on the Amiga.
 184 Example:
 185 "\-d con:20/30/600/150".
 186 .TP
 187 -e
 188 Start
 189 .B Vim
 190 in Ex mode, just like the executable was called "ex".
 191 .TP
 192 -f
 193 Foreground.  For the GUI version,
 194 .B Vim
 195 will not fork and detach from the shell it was started in.
 196 On the Amiga,
 197 .B Vim
 198 is not restarted to open a new window.
 199 This option should be used when
 200 .B Vim
 201 is executed by a program that will wait for the edit
 202 session to finish (e.g. mail).
 203 On the Amiga the ":sh" and ":!" commands will not work.
 204 .TP
 205 --nofork
 206 Foreground.  For the GUI version,
 207 .B Vim
 208 will not fork and detach from the shell it was started in.
 209 .TP
 210 -F
 211 If
 212 .B Vim
 213 has been compiled with FKMAP support for editing right-to-left
 214 oriented files and Farsi keyboard mapping, this option starts
 215 .B Vim
 216 in Farsi mode, i.e. 'fkmap' and 'rightleft' are set.
 217 Otherwise an error message is given and
 218 .B Vim
 219 aborts.
 220 .TP
 221 -g
 222 If
 223 .B Vim
 224 has been compiled with GUI support, this option enables the GUI.
 225 If no GUI support was compiled in, an error message is given and
 226 .B Vim
 227 aborts.
 228 .TP
 229 -h
 230 Give a bit of help about the command line arguments and options.
 231 After this
 232 .B Vim
 233 exits.
 234 .TP
 235 -H
 236 If
 237 .B Vim
 238 has been compiled with RIGHTLEFT support for editing right-to-left
 239 oriented files and Hebrew keyboard mapping, this option starts
 240 .B Vim
 241 in Hebrew mode, i.e. 'hkmap' and 'rightleft' are set.
 242 Otherwise an error message is given and
 243 .B Vim
 244 aborts.
 245 .TP
 246 -i {viminfo}
 247 When using the viminfo file is enabled, this option sets the filename to use,
 248 instead of the default "~/.viminfo".
 249 This can also be used to skip the use of the .viminfo file, by giving the name
 250 "NONE".
 251 .TP
 252 -L
 253 Same as -r.
 254 .TP
 255 -l
 256 Lisp mode.
 257 Sets the 'lisp' and 'showmatch' options on.
 258 .TP
 259 -m
 260 Modifying files is disabled.
 261 Resets the 'write' option, so that writing files is not possible.
 262 .TP
 263 -N
 264 No-compatible mode.  Reset the 'compatible' option.
 265 This will make
 266 .B Vim
 267 behave a bit better, but less Vi compatible, even though a .vimrc file does
 268 not exist.
 269 .TP
 270 -n
 271 No swap file will be used.
 272 Recovery after a crash will be impossible.
 273 Handy if you want to edit a file on a very slow medium (e.g. floppy).
 274 Can also be done with ":set uc=0".
 275 Can be undone with ":set uc=200".
 276 .TP
 277 -o[N]
 278 Open N windows stacked.
 279 When N is omitted, open one window for each file.
 280 .TP
 281 -O[N]
 282 Open N windows side by side.
 283 When N is omitted, open one window for each file.
 284 .TP
 285 -R
 286 Read-only mode.
 287 The 'readonly' option will be set.
 288 You can still edit the buffer, but will be prevented from accidently
 289 overwriting a file.
 290 If you do want to overwrite a file, add an exclamation mark to the Ex command,
 291 as in ":w!".
 292 The -R option also implies the -n option (see below).
 293 The 'readonly' option can be reset with ":set noro".
 294 See ":help 'readonly'".
 295 .TP
 296 -r
 297 List swap files, with information about using them for recovery.
 298 .TP
 299 -r {file}
 300 Recovery mode.
 301 The swap file is used to recover a crashed editing session.
 302 The swap file is a file with the same filename as the text file with ".swp"
 303 appended.
 304 See ":help recovery".
 305 .TP
 306 -s
 307 Silent mode.  Only when started as "Ex" or when the "-e" option was given
 308 before the "-s" option.
 309 .TP
 310 -s {scriptin}
 311 The script file {scriptin} is read.
 312 The characters in the file are interpreted as if you had typed them.
 313 The same can be done with the command ":source! {scriptin}".
 314 If the end of the file is reached before the editor exits, further characters
 315 are read from the keyboard.
 316 .TP
 317 -T {terminal}
 318 Tells
 319 .B Vim
 320 the name of the terminal you are using.
 321 Only required when the automatic way doesn't work.
 322 Should be a terminal known
 323 to
 324 .B Vim
 325 (builtin) or defined in the termcap or terminfo file.
 326 .TP
 327 -u {vimrc}
 328 Use the commands in the file {vimrc} for initializations.
 329 All the other initializations are skipped.
 330 Use this to edit a special kind of files.
 331 It can also be used to skip all initializations by giving the name "NONE".
 332 See ":help initialization" within vim for more details.
 333 .TP
 334 -U {gvimrc}
 335 Use the commands in the file {gvimrc} for GUI initializations.
 336 All the other GUI initializations are skipped.
 337 It can also be used to skip all GUI initializations by giving the name "NONE".
 338 See ":help gui-init" within vim for more details.
 339 .TP
 340 -V
 341 Verbose.  Give messages about which files are sourced and for reading and
 342 writing a viminfo file.
 343 .TP
 344 -v
 345 Start
 346 .B Vim
 347 in Vi mode, just like the executable was called "vi".  This only has effect
 348 when the executable is called "ex".
 349 .TP
 350 -w {scriptout}
 351 All the characters that you type are recorded in the file
 352 {scriptout}, until you exit
 353 .B Vim.
 354 This is useful if you want to create a script file to be used with "vim -s" or
 355 ":source!".
 356 If the {scriptout} file exists, characters are appended.
 357 .TP
 358 -W {scriptout}
 359 Like -w, but an existing file is overwritten.
 360 .TP
 361 -x
 362 Use encryption when writing files.   Will prompt for a crypt key.
 363 .TP
 364 -X
 365 Don't connect to the X server.  Shortens startup time in a terminal, but the
 366 window title and clipboard will not be used.
 367 .TP
 368 -Z
 369 Restricted mode.  Works like the executable starts with "r".
 370 .TP
 371 --
 372 Denotes the end of the options.
 373 Arguments after this will be handled as a file name.
 374 This can be used to edit a filename that starts with a '-'.
 375 .TP
 376 --help
 377 Give a help message and exit, just like "-h".
 378 .TP
 379 --version
 380 Print version information and exit.
 381 .TP
 382 --remote
 383 Connect to a Vim server and make it edit the files given in the rest of the
 384 arguments.  If no server is found a warning is given and the files are edited
 385 in the current Vim.
 386 .TP
 387 --remote-expr {expr}
 388 Connect to a Vim server, evaluate {expr} in it and print the result on stdout.
 389 .TP
 390 --remote-send {keys}
 391 Connect to a Vim server and send {keys} to it.
 392 .TP
 393 --remote-silent
 394 As --remote, but without the warning when no server is found.
 395 .TP
 396 --remote-wait
 397 As --remote, but Vim does not exit until the files have been edited.
 398 .TP
 399 --remote-wait-silent
 400 As --remote-wait, but without the warning when no server is found.
 401 .TP
 402 --serverlist
 403 List the names of all Vim servers that can be found.
 404 .TP
 405 --servername {name}
 406 Use {name} as the server name.  Used for the current Vim, unless used with a
 407 --remote argument, then it's the name of the server to connect to.
 408 .TP
 409 --socketid {id}
 410 GTK GUI only: Use the GtkPlug mechanism to run gvim in another window.
 411 .TP
 412 --echo-wid
 413 GTK GUI only: Echo the Window ID on stdout
 414 .SH ON-LINE HELP
 415 Type ":help" in
 416 .B Vim
 417 to get started.
 418 Type ":help subject" to get help on a specific subject.
 419 For example: ":help ZZ" to get help for the "ZZ" command.
 420 Use <Tab> and CTRL-D to complete subjects (":help cmdline-completion").
 421 Tags are present to jump from one place to another (sort of hypertext links,
 422 see ":help").
 423 All documentation files can be viewed in this way, for example
 424 ":help syntax.txt".
 425 .SH FILES
 426 .TP 15
 427 /usr/share/vim/vim62/doc/*.txt
 428 The
 429 .B Vim
 430 documentation files.
 431 Use ":help doc-file-list" to get the complete list.
 432 .TP
 433 /usr/share/vim/vim62/doc/tags
 434 The tags file used for finding information in the documentation files.
 435 .TP
 436 /usr/share/vim/vim62/syntax/syntax.vim
 437 System wide syntax initializations.
 438 .TP
 439 /usr/share/vim/vim62/syntax/*.vim
 440 Syntax files for various languages.
 441 .TP
 442 /usr/share/vim/vimrc
 443 System wide
 444 .B Vim
 445 initializations.
 446 .TP
 447 /usr/share/vim/gvimrc
 448 System wide gvim initializations.
 449 .TP
 450 /usr/share/vim/vim62/optwin.vim
 451 Script used for the ":options" command, a nice way to view and set options.
 452 .TP
 453 /usr/share/vim/vim62/menu.vim
 454 System wide menu initializations for gvim.
 455 .TP
 456 /usr/share/vim/vim62/bugreport.vim
 457 Script to generate a bug report.  See ":help bugs".
 458 .TP
 459 /usr/share/vim/vim62/filetype.vim
 460 Script to detect the type of a file by its name.  See ":help 'filetype'".
 461 .TP
 462 /usr/share/vim/vim62/scripts.vim
 463 Script to detect the type of a file by its contents.  See ":help 'filetype'".
 464 .TP
 465 /usr/share/vim/vim62/*.ps
 466 Files used for PostScript printing.
 467 .PP
 468 For recent info read the VIM home page:
 469 .br
 470 <URL:http://www.vim.org/>
 471 .SH SEE ALSO
 472 vimtutor(1)
 473 .SH AUTHOR
 474 Most of
 475 .B Vim
 476 was made by Bram Moolenaar, with a lot of help from others.
 477 See ":help credits" in
 478 .B Vim.
 479 .br
 480 .B Vim
 481 is based on Stevie, worked on by: Tim Thompson,
 482 Tony Andrews and G.R. (Fred) Walter.
 483 Although hardly any of the original code remains.
 484 .SH BUGS
 485 Probably.
 486 See ":help todo" for a list of known problems.
 487 .PP
 488 Note that a number of things that may be regarded as bugs by some, are in fact
 489 caused by a too-faithful reproduction of Vi's behaviour.
 490 And if you think other things are bugs "because Vi does it differently",
 491 you should take a closer look at the vi_diff.txt file (or type :help
 492 vi_diff.txt when in Vim).
 493 Also have a look at the 'compatible' and 'cpoptions' options.