path: root/man/nvim.1

.Dd January 28, 2016
.Dt NVIM 1
.Os
.Sh NAME
.Nm nvim
.Nd edit text
.Sh SYNOPSIS
.Nm
.Op Ar options
.Op Ar file ...
.Nm
.Op Ar options
.Fl
.Nm
.Op Ar options
.Fl t Ar tag
.Nm
.Op Ar options
.Fl q Op Ar errorfile
.Sh DESCRIPTION
.Nm
is a text editor based on Vim.
To enter commands in
.Nm ,
type a colon
.Pq Sq \&:
which is also used in this manual to denote commands.
For more information, consult the on-line help system with the
.Ic :help
command.
.Bl -tag -width Fl
.It Ar file ...
File(s) to edit.
If none are specified, open an empty buffer.
If multiple files are specified, open one buffer for each file.
To switch between buffers, use the
.Ic :next
and
.Ic :previous
commands.
.It Fl
Read text from standard input until
.Dv EOF ,
then open a buffer with that text.
Commands are read from standard error, which should be a terminal.
.It Fl t Ar tag
The file to edit and the initial cursor position depends on a
tag, a sort of goto label.
.Ar tag
is looked up in the tags file, the associated file becomes the current
file and the associated command is executed.
If
.Ar tag
is a function name, the file containing that function is opened
with the cursor positioned at the start of the function.
See
.Ic :help tag-commands .
.It Fl q Op Ar errorfile
QuickFix mode.
Display the first error in
.Ar errorfile .
If
.Ar errorfile
is omitted, the value of the 'errorfile' option is used (defaults to
.Cm errors.err ) .
Further errors can be jumped to with the
.Ic :cnext
command.
See
.Ic :help quickfix .
.It There are a number of other options:
.It Fl -
Interpret all further arguments as files.
Can be used to edit files starting with a hyphen
.Pq Sq - .
.It Fl -literal
Interpret filenames literally, that is, do not expand wildcards.
Has no effect on Unix-like systems, where the shell expands wildcards.
.It Fl e
Ex mode.
See
.Ic :help Ex-mode .
.It Fl E
Improved Ex mode.
See
.Ic :help gQ .
.It Fl s
Silent mode.
Only takes effect if
.Fl e
or
.Fl E
is specified before it.
.It Fl d
Diff mode.
Show the difference between two to four files, similar to
.Xr sdiff 1 .
See
.Ic :help diff .
.It Fl R
Read-only mode.
Sets the option 'readonly'.
Implies
.Fl n .
Buffers can still be edited, but cannot be written to disk if already
associated with a file.
To overwrite a file, add an exclamation mark to the needed Ex command, such as
.Ic :w! .
See
.Ic :help 'readonly' .
.It Fl Z
Restricted mode.
Disable commands that make use of an external shell.
.It Fl m
Disable file modifications.
Unsets the option 'write'.
Writing to a file is disabled, but buffers can still be modified.
.It Fl M
Disable file and buffer modifications.
Unsets the options 'write' and 'modifiable'.
Note that these options can be set to re-enable making modifications.
.It Fl b
Binary mode.
See
.Ic :help edit-binary .
.It Fl l
Lisp mode.
Sets the options 'lisp' and 'showmatch'.
.It Fl A
Arabic mode.
Sets the option 'arabic'.
.It Fl F
Farsi mode.
Sets the options 'fkmap' and 'rightleft'.
.It Fl H
Hebrew mode.
Sets the options 'hkmap' and 'rightleft'.
.It Fl V Ns Oo Ar N Oc Ns Op Ar file
Verbose mode.
Print messages about which files are being sourced and for reading and
writing a ShaDa file.
.Ar N
is the value for the 'verbose' option; defaults to
.Cm 10
if omitted.
If
.Ar file
is specified, append messages to
.Ar file
instead of printing them.
.It Fl D
Debugging mode.
Started when executing the first command from a script.
.It Fl n
Disable the use of swap files.
Sets the option 'updatecount' to
.Cm 0 .
Can be useful for editing file(s) on a slow medium.
.It Fl r Op Ar file
Recovery mode.
If
.Ar file
is omitted
then list swap files with recovery information.
Otherwise the swap file
.Ar file
is used to recover a crashed session.
The swap file has the same name as the file it's associated with, but with
.Sq .swp
appended.
See
.Ic :help recovery .
.It Fl L Op Ar file
Alias for
.Fl r .
.It Fl u Ar vimrc
Use
.Ar vimrc
instead of the default of
.Pa ~/.config/nvim/init.vim .
If
.Ar vimrc
is
.Cm NORC ,
do not load any initialization files (excluding plugins),
and do not attempt to parse environment variables.
If
.Ar vimrc
is
.Cm NONE ,
loading plugins is also skipped.
See
.Ic :help initialization .
.It Fl i Ar shada
Use
.Ar shada
instead of the default of
.Pa ~/.local/share/nvim/shada/main.shada .
If
.Ar shada
is
.Cm NONE ,
do not read or write a ShaDa file.
See
.Ic :help shada .
.It Fl -noplugin
Skip loading plugins.
Implied by
.Cm -u NONE .
.It Fl o Ns Op Ar N
Open
.Ar N
windows stacked horizontally.
If
.Ar N
is omitted, open one window for each file.
If
.Ar N
is less than the number of file arguments, allocate windows for the first
.Ar N
files and hide the rest.
.It Fl O Ns Op Ar N
Like
.Fl o ,
but tile windows vertically.
.It Fl p Ns Op Ar N
Like
.Fl o ,
but for tab pages.
.It Cm + Ns Op Ar linenum
For the first file, position the cursor on line
.Ar linenum .
If
.Ar linenum
is omitted, position the cursor on the last line of the file.
Note that
.Cm +5
and
.Cm -c 5
on the command-line are equivalent to
.Ic :5
inside
.Nm .
.It Cm +/ Ns Op Ar pattern
For the first file, position the cursor on the first occurrence of
.Ar pattern .
If
.Ar pattern
is omitted, the most recently used search pattern is used (if there is one).
Note that
.Cm +/foo
and
.Cm -c /foo
on the command-line are equivalent to
.Ic /foo
and
.Ic :/foo
inside
.Nm .
See
.Ic :help search-pattern .
.It Fl c Ar command
Execute
.Ar command
after reading the first file.
Up to 10 instances of
.Fl c
or
.Cm +
can be used.
Note that
.Qq Cm +set si
and
.Cm -c \(dqset si\(dq
are equivalent.
.It Fl -cmd Ar command
Like
.Fl c ,
but execute
.Ar command
before processing any vimrc.
Up to 10 instances of these can be used independently from instances of
.Fl c .
.It Fl S Op Ar session
Source
.Ar session
after the first file argument has been read.
Equivalent to
.Cm -c \(dqsource session\(dq .
.Ar session
cannot start with a hyphen
.Pq Sq - .
If
.Ar session
is omitted, then
.Pa Session.vim ,
if found, is used.
See
.Ic :help session-file .
.It Fl s Ar scriptin
Read normal mode commands from
.Ar scriptin .
The same can be done with the command
.Ic :source! scriptin .
If the end of the file is reached before
.Nm
exits, further characters are read from the keyboard.
.It Fl w Ar scriptout
Append all typed characters to
.Ar scriptout .
Can be used for creating a script to be used with
.Fl s
or
.Ic :source! .
.It Fl W Ar scriptout
Like
.Fl w ,
but truncate
.Ar scriptout .
.It Fl -startuptime Ar file
During startup, append timing messages to
.Ar file .
Can be used to diagnose slow startup times.
.It Fl -api-info
Dump API metadata serialized to msgpack and exit.
.It Fl -embed
Use standard input and standard output as a msgpack-rpc channel.
Implies
.Fl -headless .
.It Fl -headless
Do not start a user interface.
.It Fl h , -help
Print usage information and exit.
.It Fl v , -version
Print version information and exit.
.El
.Sh ENVIRONMENT
.Bl -tag -width Fl
.It Ev VIM
Used to locate various user files, such as the user's init.vim.
.It Ev VIMRUNTIME
Used to locate run time files, such as on-line documentation and
syntax highlighting definitions.
.It Ev XDG_CONFIG_HOME
Path to use for the user-local configuration directory, see
.Sx FILES .
Defaults to
.Pa ~/.config
if not set.
.It Ev XDG_DATA_HOME
Like
.Ev XDG_CONFIG_HOME ,
but used to store data not generally edited by the user,
namely swap, backup, and ShaDa files.
Defaults to
.Pa ~/.local/share
if not set.
.It Ev VIMINIT
A string of Ex commands to be executed at startup.
For example, the command to quit is
.Ic :q ,
so to have
.Nm
quit immediately after starting, set
.Ev VIMINIT
to
.Cm q .
See
.Ic :help VIMINIT .
.It Ev SHELL
Used to set the 'shell' option, which determines the shell used by the
.Ic :terminal
command.
.It Ev NVIM_TUI_ENABLE_CURSOR_SHAPE
If defined, change the cursor shape to a vertical bar while in insert mode.
Requires that the host terminal supports the DECSCUSR CSI escape sequence.
Has no effect in GUIs.
.Pp
Depending on the terminal emulator, using this option with
.Nm
under
.Xr tmux 1
might require adding the following to
.Pa ~/.tmux.conf :
.Bd -literal -offset indent
set -ga terminal-overrides ',*:Ss=\eE[%p1%d q:Se=\eE[2 q'
.Ed
.Pp
See
.Ic terminal-overrides
in the
.Xr tmux 1
manual page for more information.
.El
.Sh FILES
.Bl -tag -width "~/.config/nvim/init.vim"
.It Pa ~/.config/nvim/init.vim
The user-local
.Nm
configuration file.
See
.Ev XDG_CONFIG_HOME
above.
.It Pa ~/.config/nvim
The user-local
.Nm
configuration directory.
See
.Ev XDG_CONFIG_HOME
above.
.It Pa $VIM/sysinit.vim
The system-global
.Nm
configuration file.
.It Pa /usr/local/share/nvim
The system-global
.Nm
runtime directory.
.El
.Sh AUTHORS
.Nm
was started by
.An Thiago de Arruda ,
with a lot of help from others.
.Pp
Most of Vim was written by
.An -nosplit
.An Bram Moolenaar ,
with a lot of help from others.
See
.Ic :help credits .
.Pp
Vim is based on Stevie, worked on by
.An Tim Thompson ,
.An Tony Andrews ,
and
.An G.R. (Fred) Walter .