runtime/doc/vim.man

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