path: root/runtime/doc/starting.txt

*starting.txt*  Nvim


                  VIM REFERENCE MANUAL    by Bram Moolenaar


Starting Vim                                            *starting*

                                      Type |gO| to see the table of contents.

==============================================================================
Nvim arguments                                          *cli-arguments*

Most often, Nvim is started to edit a single file with the command: >

        nvim filename

More generally, Nvim is started with: >

        nvim [option | filename] ..

Option arguments and file name arguments can be mixed, and any number of them
can be given.  However, watch out for options that take an argument.

The following items decide how to start editing:

                                                        *-file* *---*
filename        One or more file names.  The first one will be the current
                file and read into the buffer.  The cursor will be positioned
                on the first line of the buffer.
                To avoid a file name starting with a '-' being interpreted as
                an option, precede the arglist with "--", e.g.: >
                        nvim -- -filename
<                All arguments after "--" are interpreted as file names, no
                other options or "+command" arguments can follow.

`-`                                                     *--*
                Alias for stdin (standard input).
                Example: >
                        echo text | nvim - file
<                "text" is read into buffer 1, "file" is opened as buffer 2.
                In most cases (except -s, -es, |--embed|, --headless) if stdin
                is not a TTY then it is read as text, so "-" is implied: >
                        echo text | nvim file
<                The buffer will be marked as modified, because it contains
                text that needs to be saved (except for readonly |-R| mode).
                If you don't like that, put these lines in your init.vim: >
                        " Don't set 'modified' when reading from stdin
                        au StdinReadPost * set nomodified
<
                To read stdin as Normal commands use |-s| with "-": >
                        echo "ifoo" | nvim -s -
<                To read stdin as Ex commands use |-es| or |-e|: >
                        echo "echo getpid()" | nvim -e - -V1
<                To open a file literally named "-", put it after "--": >
                        echo foo | nvim -- -
<                To read stdin as text with |--headless| use "-".

                                                        *-t* *-tag*
-t {tag}        A tag.  "tag" is looked up in the tags file, the associated
                file becomes the current file, and the associated command is
                executed.  Mostly this is used for C programs, in which case
                "tag" often is a function name.  The effect is that the file
                containing that function becomes the current file and the
                cursor is positioned on the start of the function (see
                |tags|).

                                                        *-q* *-qf*
-q [errorfile]  QuickFix mode.  The file with the name [errorfile] is read
                and the first error is displayed.  See |quickfix|.
                If [errorfile] is not given, the 'errorfile' option is used
                for the file name.  See 'errorfile' for the default value.

(nothing)       Without one of the four items above, Vim will start editing a
                new buffer.  It's empty and doesn't have a file name.

                                                        *startup-options*
The option arguments may be given in any order.  Single-letter options can be
combined after one dash.  There can be no option arguments after the "--"
argument.

--help                                                  *--help*
-?                                                      *-?*
-h                                                      *-h*
                Give usage (help) message and exit.

--version                                               *--version*
-v                                                      *-v*
                Print version information and exit.  Same output as for
                |:version| command.

--clean                                                 *--clean*
                Mimics a fresh install of Nvim:
                - Skips initializations from files and environment variables.
                - No 'shada' file is read or written.
                - Excludes user directories from 'runtimepath'
                - Loads builtin plugins, unlike "-u NONE -i NONE".

                                                        *--noplugin*
--noplugin      Skip loading plugins.  Resets the 'loadplugins' option.
                Note that the |-u| argument may also disable loading plugins:
                        argument        load vimrc files        load plugins >
                        (nothing)               yes                 yes
                        -u NONE                 no                  no
                        -u NORC                 no                  yes
                        --noplugin              yes                 no
<
--startuptime {fname}                                   *--startuptime*
                During startup write timing messages to the file {fname}.
                This can be used to find out where time is spent while loading
                your |config|, plugins and opening the first file.
                When {fname} already exists new messages are appended.

                                                        *-+*
+[num]          The cursor will be positioned on line "num" for the first
                file being edited.  If "num" is missing, the cursor will be
                positioned on the last line.

                                                        *-+/*
+/{pat}         The cursor will be positioned on the first line containing
                "pat" in the first file being edited (see |pattern| for the
                available search patterns).  The search starts at the cursor
                position, which can be the first line or the cursor position
                last used from |shada|.  To force a search from the first
                line use "+1 +/pat".

+{command}                                              *-+c*
-c {command}                                            *-c*
                {command} will be executed after the first file has been
                read (and after autocommands and modelines for that file have
                been processed).  "command" is interpreted as an Ex command.
                If the "command" contains spaces, it must be enclosed in
                double quotes (this depends on the shell that is used).
                Example: >
                        vim  "+set si"  main.c
                        vim  "+find stdio.h"
                        vim  -c "set ff=dos"  -c wq  mine.mak
<
                Note: You can use up to 10 "+" or "-c" arguments in a Vim
                command.  They are executed in the order given.  A "-S"
                argument counts as a "-c" argument as well.

--cmd {command}                                         *--cmd*
                {command} will be executed before processing any vimrc file.
                Otherwise, it acts like -c {command}.  You can use up to 10 of
                these commands, independently from "-c" commands.

                                                        *-S*
-S [file]       Executes Vimscript or Lua (".lua") [file] after the first file
                has been read. See also |:source|. If [file] is not given,
                defaults to "Session.vim". Equivalent to: >
                        -c "source {file}"
<                Can be repeated like "-c", subject to the same limit of 10
                "-c" arguments. {file} cannot start with a "-".

-L                                                      *-L*
-r                                                      *-r*
                Recovery mode.  Without a file name argument, a list of
                existing swap files is given.  With a file name, a swap file
                is read to recover a crashed editing session.  See
                |crash-recovery|.

                                                        *-R*
-R              Readonly mode.  The 'readonly' option will be set for all the
                files being edited.  You can still edit the buffer, but will
                be prevented from accidentally overwriting a file.  If you
                forgot that you are in View mode and did make some changes,
                you can overwrite a file by adding an exclamation mark to
                the Ex command, as in ":w!".  The 'readonly' option can be
                reset with ":set noro" (see the options chapter, |options|).
                Subsequent edits will not be done in readonly mode.
                The 'updatecount' option will be set to 10000, meaning that
                the swap file will not be updated automatically very often.
                See |-M| for disallowing modifications.

                                                        *-m*
-m              Modifications not allowed to be written.  The 'write' option
                will be reset, so that writing files is disabled.  However,
                the 'write' option can be set to enable writing again.