From e12a9e7c4ea6c95bdf4de56162f0e3ffd8dfdd5b Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 22 Mar 2026 00:38:26 +0100 Subject: [PATCH] docs: starting.txt new layout --- runtime/doc/index.txt | 2 +- runtime/doc/lua-guide.txt | 2 +- runtime/doc/lua.txt | 4 +- runtime/doc/repeat.txt | 5 +- runtime/doc/starting.txt | 1098 +++++++++++++++--------------- runtime/lua/vim/_core/editor.lua | 2 +- src/gen/gen_help_html.lua | 1 + src/nvim/ex_session.c | 4 +- 8 files changed, 564 insertions(+), 554 deletions(-) diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt index a1e85a0fb6..6d3ece1faf 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -1127,7 +1127,7 @@ to terminal mode. You found it, Arthur! *holy-grail* ============================================================================== -6. EX commands *Ex-commands* *ex-cmd-index* *:index* +6. EX commands *Ex-command* *ex-cmd-index* *:index* This is a brief but complete listing of all the ":" commands, without mentioning any arguments. The optional part of the command name is inside []. diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt index 4bec8e0820..7abdb3f2dc 100644 --- a/runtime/doc/lua-guide.txt +++ b/runtime/doc/lua-guide.txt @@ -29,7 +29,7 @@ The purpose of this guide is to introduce the different ways of interacting with Nvim through Lua (the "API"). This API consists of three different layers: -1. The "Vim API" inherited from Vim: |Ex-commands| and |vimscript-functions| +1. The "Vim API" inherited from Vim: |Ex-command|s and |vimscript-functions| as well as |user-function|s in Vimscript. These are accessed through |vim.cmd()| and |vim.fn| respectively, which are discussed under |lua-guide-vimscript| below. diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 4335092003..5a05ef17d4 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -17,7 +17,7 @@ get an idea of what lurks beneath: >vim :lua vim.print(package.loaded) Nvim includes a "standard library" |lua-stdlib| for Lua. It complements the -"editor stdlib" (|vimscript-functions| + |Ex-commands|) and the |API|, all of +"editor stdlib" (|vimscript-functions| + |Ex-command|s) and the |API|, all of which can be used from Lua code (|lua-vimscript| |vim.api|). These three namespaces form the Nvim programming interface. @@ -1231,7 +1231,7 @@ vim.wo[{winid}][{bufnr}] *vim.wo* Lua module: vim *lua-vim* vim.cmd({command}) *vim.cmd()* - Executes Vimscript (|Ex-commands|). + Executes Vimscript (|Ex-command|s). Can be indexed with a command name to get a function, thus you can write `vim.cmd.echo(…)` instead of `vim.cmd{cmd='echo',…}`. diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt index a0db7ae084..02d74e9b12 100644 --- a/runtime/doc/repeat.txt +++ b/runtime/doc/repeat.txt @@ -192,9 +192,8 @@ Using Vim scripts *using-scripts* For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. *:so* *:source* -:so[urce] {file} Runs |Ex-commands| or Lua code (".lua" files) from - {file}. - Triggers the |SourcePre| autocommand. +:so[urce] {file} Runs |Ex-command|s or Lua code (".lua" files) from + {file}. Triggers the |SourcePre| autocommand. :[range]so[urce] Read Ex commands or Lua code from the [range] of lines in the current buffer. When [range] is omitted read diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index b95e92e216..7f22bd699b 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -1,440 +1,441 @@ *starting.txt* Nvim - VIM REFERENCE MANUAL by Bram Moolenaar + VIM REFERENCE MANUAL by Bram Moolenaar -Starting Vim *starting* +Starting Vim *starting* Type |gO| to see the table of contents. ============================================================================== -Nvim arguments *cli-arguments* +Nvim arguments *cli-arguments* Most often, Nvim is started to edit a single file with the command: > - nvim filename + nvim filename More generally, Nvim is started with: > - nvim [option | filename] .. + 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. + *-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 + *--* +`-` 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 "-". + 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|). + *-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. + *-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. +(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* + *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 *-h* *--help* *-?* +--help *-h* *--help* *-?* -? --h Give usage (help) message and exit. +-h Give usage (help) message and exit. ---version *-v* *--version* --v Print version information and exit. Same output as for - |:version| command. +--version *-v* *--version* +-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". + *--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* --c {command} {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 + *--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 < - 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. +--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. ---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. + *-+* ++[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. - *-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 "-". + *-+/* ++/{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". --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. - - *-M* --M Modifications not allowed. The 'modifiable' option will be - reset, so that changes are not allowed. The 'write' option - will be reset, so that writing files is disabled. However, - the 'modifiable' and 'write' options can be set to enable - changes and writing. - --e *-e* *-E* --E Start Nvim in Ex mode |gQ|, see |Ex-mode|. - - If stdin is not a TTY: - -e reads/executes stdin as Ex commands. - -E reads stdin as text (into buffer 1). - --es *-es* *-Es* *-s-ex* *silent-mode* --Es Script mode, aka "silent mode", aka "batch mode". No UI, - disables most prompts and messages. Unrelated to |-s|. - See also |-S| to run script files. - - -es reads/executes stdin as Ex commands. > - printf "put ='foo'\n%%print\n" | nvim -es - -< -Es reads stdin as text (into buffer 1). Use |-c| or "+" to - send commands. > - printf "foo\n" | nvim -Es +"%print" - -< These commands display on stdout: - :list - :number - :print - :set - With |:verbose| or 'verbose', other commands display on stderr: > - nvim -es +"verbose echo 'foo'" - nvim -V1 -es +"echo 'foo'" ++{command} *-+c* *-c* +-c {command} {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 < - Skips user |config| unless |-u| was given. - Disables |shada| unless |-i| was given. - Disables swapfile (like |-n|). + 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. - *-l* +--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. + + *-M* +-M Modifications not allowed. The 'modifiable' option will be + reset, so that changes are not allowed. The 'write' option + will be reset, so that writing files is disabled. However, + the 'modifiable' and 'write' options can be set to enable + changes and writing. + +-e *-e* *-E* +-E Start Nvim in Ex mode |gQ|, see |Ex-mode|. + + If stdin is not a TTY: + • -e reads/executes stdin as Ex commands. + • -E reads stdin as text (into buffer 1). + +-es *-es* *-Es* *-s-ex* *silent-mode* +-Es Script mode, aka "silent mode", aka "batch mode". No UI, + disables most prompts and messages. Unrelated to |-s|. + See also |-S| to run script files. + + -es reads/executes stdin as Ex commands. > + printf "put ='foo'\n%%print\n" | nvim -es + +< -Es reads stdin as text (into buffer 1). Use |-c| or "+" to + send commands. > + printf "foo\n" | nvim -Es +"%print" + +< These commands display on stdout: + • :list + • :number + • :print + • :set + + With |:verbose| or 'verbose', other commands display on stderr: > + nvim -es +"verbose echo 'foo'" + nvim -V1 -es +"echo 'foo'" +< + Skips user |config| unless |-u| was given. + Disables |shada| unless |-i| was given. + Disables swapfile (like |-n|). + + *-l* -l {script} [args] - Executes Lua {script} non-interactively (no UI) with optional - [args] after processing any preceding Nvim |cli-arguments|, - then exits. Exits 1 on Lua error. See |-S| to run multiple Lua - scripts without args, with a UI. - *lua-args* - All [args] are treated as {script} arguments and stored in the - Lua `_G.arg` global table, thus "-l" ends processing of Nvim - arguments. The {script} name is stored at `_G.arg[0]`. + Executes Lua {script} non-interactively (no UI) with optional + [args] after processing any preceding Nvim |cli-arguments|, + then exits. Exits 1 on Lua error. See |-S| to run multiple Lua + scripts without args, with a UI. + *lua-args* + All [args] are treated as {script} arguments and stored in the + Lua `_G.arg` global table, thus "-l" ends processing of Nvim + arguments. The {script} name is stored at `_G.arg[0]`. - Sets 'verbose' to 1 (like "-V1"), so Lua `print()` writes to - output, as well as other message-emitting functions like - |:echo|. - If {script} prints messages and doesn't cause Nvim to exit, - Nvim ensures output ends with a newline. + Sets 'verbose' to 1 (like "-V1"), so Lua `print()` writes to + output, as well as other message-emitting functions like + |:echo|. + If {script} prints messages and doesn't cause Nvim to exit, + Nvim ensures output ends with a newline. - Arguments before "-l" are processed before executing {script}. - This example quits before executing "foo.lua": > - nvim +q -l foo.lua -< This loads Lua module "bar" before executing "foo.lua": > - nvim +"lua require('bar')" -l foo.lua -< *lua-shebang* - You can set the "shebang" of the script so that Nvim executes - the script when called with "./" from a shell (remember to - "chmod u+x"): > - #!/usr/bin/env -S nvim -l + Arguments before "-l" are processed before executing {script}. + This example quits before executing "foo.lua": > + nvim +q -l foo.lua +< This loads Lua module "bar" before executing "foo.lua": > + nvim +"lua require('bar')" -l foo.lua +< *lua-shebang* + You can set the "shebang" of the script so that Nvim executes + the script when called with "./" from a shell (remember to + "chmod u+x"): > + #!/usr/bin/env -S nvim -l < - Skips user |config| unless |-u| was given. - Disables plugins unless 'loadplugins' was set. - Disables |shada| unless |-i| was given. - Disables swapfile (like |-n|). + Skips user |config| unless |-u| was given. + Disables plugins unless 'loadplugins' was set. + Disables |shada| unless |-i| was given. + Disables swapfile (like |-n|). - *-ll* + *-ll* -ll {script} [args] - Executes a Lua script, similarly to |-l|, but the editor is not - initialized. This gives a Lua environment similar to a worker - thread. See |lua-loop-threading|. + Executes a Lua script, similarly to |-l|, but the editor is not + initialized. This gives a Lua environment similar to a worker + thread. See |lua-loop-threading|. - Unlike `-l` no prior arguments are allowed. + Unlike `-l` no prior arguments are allowed. - *-b* --b Binary mode. File I/O will only recognize to separate - lines. The 'expandtab' option will be reset. The 'textwidth' - option is set to 0. 'modeline' is reset. The 'binary' option - is set. This is done after reading the |vimrc| but before - reading any file in the arglist. See also |edit-binary|. + *-b* +-b Binary mode. File I/O will only recognize to separate + lines. The 'expandtab' option will be reset. The 'textwidth' + option is set to 0. 'modeline' is reset. The 'binary' option + is set. This is done after reading the |vimrc| but before + reading any file in the arglist. See also |edit-binary|. - *-A* --A Arabic mode. Sets the 'arabic' option on. + *-A* +-A Arabic mode. Sets the 'arabic' option on. - *-H* --H Hebrew mode. Sets the 'rightleft' option on and the 'keymap' - option to "hebrew". + *-H* +-H Hebrew mode. Sets the 'rightleft' option on and the 'keymap' + option to "hebrew". - *-V* *verbose* --V[N] Verbose. Sets the 'verbose' option to [N] (default: 10). - Messages will be given for each file that is ":source"d and - for reading or writing a ShaDa file. Can be used to find - out what is happening upon startup and exit. - Example: > - nvim -V8 + *-V* *verbose* +-V[N] Verbose. Sets the 'verbose' option to [N] (default: 10). + Messages will be given for each file that is ":source"d and + for reading or writing a ShaDa file. Can be used to find + out what is happening upon startup and exit. + Example: > + nvim -V8 -V[N]{file} - Like -V and sets 'verbosefile' to {file} (must not start with - a digit). Messages are not displayed, instead they are - written to {file}. - Example: > - nvim -V20vimlog + Like -V and sets 'verbosefile' to {file} (must not start with + a digit). Messages are not displayed, instead they are + written to {file}. + Example: > + nvim -V20vimlog < - *-D* --D Debugging. Go to debugging mode when executing the first - command from a script. |debug-mode| + *-D* +-D Debugging. Go to debugging mode when executing the first + command from a script. |debug-mode| - *-n* --n Disables |swap-file| by setting 'updatecount' to 0 (after - executing any |vimrc|). Recovery after a crash will be - impossible. Improves performance when working with a file on - a very slow medium (usb drive, network share). + *-n* +-n Disables |swap-file| by setting 'updatecount' to 0 (after + executing any |vimrc|). Recovery after a crash will be + impossible. Improves performance when working with a file on + a very slow medium (usb drive, network share). - Enable it again by setting 'updatecount' to some value, e.g. - ":set updatecount=100". + Enable it again by setting 'updatecount' to some value, e.g. + ":set updatecount=100". - To reduce accesses to the disk, don't use "-n", but set - 'updatetime' and 'updatecount' to very big numbers, and type - ":preserve" when you want to save your work. This way you - keep the possibility for crash recovery. + To reduce accesses to the disk, don't use "-n", but set + 'updatetime' and 'updatecount' to very big numbers, and type + ":preserve" when you want to save your work. This way you + keep the possibility for crash recovery. - *-o* --o[N] Open N windows, split horizontally. If [N] is not given, - one window is opened for every file given as argument. If - there is not enough room, only the first few files get a - window. If there are more windows than arguments, the last - few windows will be editing an empty file. + *-o* +-o[N] Open N windows, split horizontally. If [N] is not given, + one window is opened for every file given as argument. If + there is not enough room, only the first few files get a + window. If there are more windows than arguments, the last + few windows will be editing an empty file. - *-O* --O[N] Open N windows, split vertically. Otherwise, it's like -o. - If both the -o and the -O option are given, the last one on - the command line determines how the windows will be split. + *-O* +-O[N] Open N windows, split vertically. Otherwise, it's like -o. + If both the -o and the -O option are given, the last one on + the command line determines how the windows will be split. - *-p* --p[N] Open N tab pages. If [N] is not given, one tab page is opened - for every file given as argument. The maximum is set with - 'tabpagemax' pages (default 50). If there are more tab pages - than arguments, the last few tab pages will be editing an - empty file. Also see |tabpage|. - *-d* --d Start in |diff-mode|. + *-p* +-p[N] Open N tab pages. If [N] is not given, one tab page is opened + for every file given as argument. The maximum is set with + 'tabpagemax' pages (default 50). If there are more tab pages + than arguments, the last few tab pages will be editing an + empty file. Also see |tabpage|. + *-d* +-d Start in |diff-mode|. - *-u* *E282* --u {vimrc} The file {vimrc} is read for initializations. Most other - initializations are skipped; see |initialization|. + *-u* *E282* +-u {vimrc} The file {vimrc} is read for initializations. Most other + initializations are skipped; see |initialization|. - This can be used to start Vim in a special mode, with special - mappings and settings. A shell alias can be used to make - this easy to use. For example, in a C shell descendant: > - alias vimc 'nvim -u ~/.config/nvim/c_init.vim \!*' -< And in a Bash shell: > - alias vimc='nvim -u ~/.config/nvim/c_init.vim' -< Also consider using autocommands; see |autocommand|. + This can be used to start Vim in a special mode, with special + mappings and settings. A shell alias can be used to make + this easy to use. For example, in a C shell descendant: > + alias vimc 'nvim -u ~/.config/nvim/c_init.vim \!*' +< And in a Bash shell: > + alias vimc='nvim -u ~/.config/nvim/c_init.vim' +< Also consider using autocommands; see |autocommand|. - When {vimrc} is "NONE" (all uppercase), all initializations - from files and environment variables are skipped. Plugins and - syntax highlighting are also skipped. + When {vimrc} is "NONE" (all uppercase), all initializations + from files and environment variables are skipped. Plugins and + syntax highlighting are also skipped. - When {vimrc} is "NORC" (all uppercase), this has the same - effect as "NONE", but plugins and syntax highlighting are not - skipped. + When {vimrc} is "NORC" (all uppercase), this has the same + effect as "NONE", but plugins and syntax highlighting are not + skipped. - *-i* --i {shada} The file {shada} is used instead of the default ShaDa - file. If the name "NONE" is used (all uppercase), no ShaDa - file is read or written, even if 'shada' is set or when - ":rsh" or ":wsh" are used. See also |shada-file|. + *-i* +-i {shada} The file {shada} is used instead of the default ShaDa + file. If the name "NONE" is used (all uppercase), no ShaDa + file is read or written, even if 'shada' is set or when + ":rsh" or ":wsh" are used. See also |shada-file|. - *-s* --s {scriptin} Read script file {scriptin}, interpreting characters as - Normal-mode input. The same can be done with ":source!": > - :source! {scriptin} -< Reads from stdin if {scriptin} is "-": > - echo "ifoo" | nvim -s - -< If the end of the file is reached before Nvim exits, further - characters are read from the keyboard. + *-s* +-s {scriptin} Read script file {scriptin}, interpreting characters as + Normal-mode input. The same can be done with ":source!": > + :source! {scriptin} +< Reads from stdin if {scriptin} is "-": > + echo "ifoo" | nvim -s - +< If the end of the file is reached before Nvim exits, further + characters are read from the keyboard. - Does not work with |-es|. See also |complex-repeat|. + Does not work with |-es|. See also |complex-repeat|. - *-w_nr* + *-w_nr* -w {number} --w{number} Set the 'window' option to {number}. +-w{number} Set the 'window' option to {number}. - *-w* --w {scriptout} All keys that you type are recorded in the file "scriptout", - until you exit Vim. Useful to create a script file to be used - with "vim -s" or ":source!". Appends to the "scriptout" file - if it already exists. {scriptout} cannot start with a digit. - See also |vim.on_key()|. - See also |complex-repeat|. + *-w* +-w {scriptout} All keys that you type are recorded in the file "scriptout", + until you exit Vim. Useful to create a script file to be used + with "vim -s" or ":source!". Appends to the "scriptout" file + if it already exists. {scriptout} cannot start with a digit. + See also |vim.on_key()|. + See also |complex-repeat|. - *-W* --W {scriptout} Like -w, but do not append, overwrite an existing file. + *-W* +-W {scriptout} Like -w, but do not append, overwrite an existing file. - *--api-info* ---api-info Print msgpack-encoded |api-metadata| and exit. + *--api-info* +--api-info Print msgpack-encoded |api-metadata| and exit. - *--embed* ---embed Use stdin/stdout as a msgpack-RPC channel, so applications can - embed and control Nvim via the RPC |API|. If the channel is - closed (except by |:detach|), Nvim exits. + *--embed* +--embed Use stdin/stdout as a msgpack-RPC channel, so applications can + embed and control Nvim via the RPC |API|. If the channel is + closed (except by |:detach|), Nvim exits. - Waits for the client ("embedder") to call |nvim_ui_attach()| - before sourcing startup files and reading buffers, so that UIs - can deterministically handle (display) early messages, - dialogs, etc. The client can do other requests before - `nvim_ui_attach` (e.g. `nvim_get_api_info` for feature-detection). - During this pre-startup phase the user config is of course not - available (similar to `--cmd`). + Waits for the client ("embedder") to call |nvim_ui_attach()| + before sourcing startup files and reading buffers, so that UIs + can deterministically handle (display) early messages, + dialogs, etc. The client can do other requests before + `nvim_ui_attach` (e.g. `nvim_get_api_info` for feature-detection). + During this pre-startup phase the user config is of course not + available (similar to `--cmd`). - Non-UI embedders must pass |--headless|, then startup will - continue without waiting for `nvim_ui_attach`: > - nvim --embed --headless -< which is equivalent to: > - nvim --headless --cmd "call stdioopen({'rpc': v:true})" + Non-UI embedders must pass |--headless|, then startup will + continue without waiting for `nvim_ui_attach`: > + nvim --embed --headless +< which is equivalent to: > + nvim --headless --cmd "call stdioopen({'rpc': v:true})" < - UI embedders that want the UI protocol on a socket (instead of - stdio) must pass |--listen| as well as |--embed|: > - nvim --embed --listen addr + UI embedders that want the UI protocol on a socket (instead of + stdio) must pass |--listen| as well as |--embed|: > + nvim --embed --listen addr -< See also: |ui-startup| |channel-stdio| +< See also: |ui-startup| |channel-stdio| - *--headless* ---headless Start without UI, and do not wait for `nvim_ui_attach`. The - builtin TUI is not used, so stdio works as an arbitrary - communication channel. |channel-stdio| + *--headless* +--headless Start without UI, and do not wait for `nvim_ui_attach`. The + builtin TUI is not used, so stdio works as an arbitrary + communication channel. |channel-stdio| - Also useful for scripting (tests) to see messages that would - not be printed by |-es|. + Also useful for scripting (tests) to see messages that would + not be printed by |-es|. - To detect if a UI is available, check if |nvim_list_uis()| is - empty during or after |VimEnter|. + To detect if a UI is available, check if |nvim_list_uis()| is + empty during or after |VimEnter|. - To read stdin as text, "-" must be given explicitly: - --headless cannot assume that stdin is just text. > - echo foo | nvim --headless +"%print" +"q!" - + To read stdin as text, "-" must be given explicitly: + --headless cannot assume that stdin is just text. > + echo foo | nvim --headless +"%print" +"q!" - < - See also |--embed|. - See also |-es|, which also disables most messages. + See also |--embed|. + See also |-es|, which also disables most messages. ---listen {addr} *--listen* - Start |RPC| server on pipe or TCP address {addr}. Sets the - primary listen address |v:servername| to {addr}. |serverstart()| +--listen {addr} *--listen* + Start |RPC| server on pipe or TCP address {addr}. Sets the + primary listen address |v:servername| to {addr}. |serverstart()| - To start the server on-demand with systemd, use a systemd - socket unit and associated service unit running: > - systemd-socket-proxyd --exit-idle-time + To start the server on-demand with systemd, use a systemd + socket unit and associated service unit running: > + systemd-socket-proxyd --exit-idle-time < ============================================================================== -Initialization *initialization* *startup* +Initialization *initialization* *startup* At startup, Nvim checks environment variables and files and sets values accordingly, proceeding as follows: -1. Set the 'shell' option. *SHELL* *COMSPEC* +1. Set the 'shell' option. *SHELL* *COMSPEC* The environment variable SHELL, if it exists, is used to set the 'shell' option. On Win32, the COMSPEC variable is used if SHELL is not set. @@ -462,43 +463,42 @@ accordingly, proceeding as follows: multiple commands with '|' or ). *config* *init.vim* *init.lua* *vimrc* *exrc* - A file containing initialization commands is generically called a "vimrc" - or config file. It can be either Vimscript ("init.vim") or Lua - ("init.lua"), but not both. *E5422* - See also |vimrc-intro| and |base-directories|. - - The config file is located at: + or config file. It can be Vimscript ("init.vim") or Lua ("init.lua"), + but not both. *E5422* See |vimrc-intro| |base-directories|. + The config file is located at: - Unix ~/.config/nvim/init.vim (or init.lua) - Windows ~/AppData/Local/nvim/init.vim (or init.lua) - |$XDG_CONFIG_HOME| $XDG_CONFIG_HOME/nvim/init.vim (or init.lua) + - If Nvim was started with "-u {file}" then {file} is used as the config and all initializations until 8. are skipped. $MYVIMRC is not set. "nvim -u NORC" can be used to skip these initializations without reading a file. "nvim -u NONE" also skips plugins and syntax highlighting. |-u| + - If Nvim was started with |-es| or |-Es| or |-l| all initializations until "8" are skipped. - - a. *system-vimrc* *sysinit.vim* - The system vimrc file is read for initializations. If - nvim/sysinit.vim file exists in one of $XDG_CONFIG_DIRS, it will be - used. Otherwise the system vimrc file is used. The path of this - file is given by the |:version| command. Usually it's - "$VIM/sysinit.vim". + - a. *system-vimrc* *sysinit.vim* + The system vimrc file is read for initializations. If + nvim/sysinit.vim file exists in one of $XDG_CONFIG_DIRS, it will be + used. Otherwise the system vimrc file is used. The path of this file + is given by the |:version| command. Usually it's "$VIM/sysinit.vim". - - b. *VIMINIT* *EXINIT* *$MYVIMRC* - Locations searched for initializations, in order of preference. - $MYVIMRC is set to the first valid location unless it was already - set or when using $VIMINIT: - - $VIMINIT environment variable (Ex command line). - - User |config|: $XDG_CONFIG_HOME/nvim/init.vim (or init.lua). - - Other config: {dir}/nvim/init.vim (or init.lua) where {dir} is any - directory in $XDG_CONFIG_DIRS. - - $EXINIT environment variable (Ex command line). + - b. *VIMINIT* *EXINIT* *$MYVIMRC* + Locations searched for initializations, in order of preference. + $MYVIMRC is set to the first valid location unless it was already set + or when using $VIMINIT: + - $VIMINIT environment variable (Ex command line). + - User |config|: $XDG_CONFIG_HOME/nvim/init.vim (or init.lua). + - Other config: {dir}/nvim/init.vim (or init.lua) where {dir} is any + directory in $XDG_CONFIG_DIRS. + - $EXINIT environment variable (Ex command line). - - c. If the 'exrc' option is on (which is NOT the default), the current - directory is searched for the following files, in order of precedence. - The first that exists is used, the others are ignored: - - ".nvim.lua" - - ".nvimrc" - - ".exrc" + - c. If the 'exrc' option is on, the |current-directory| is searched until + one of these files is found, in order of precedence: + - ".nvim.lua" + - ".nvimrc" + - ".exrc" 8. Enable filetype detection. Skipped if ":filetype off" was called or if the "-u NONE" command line @@ -539,31 +539,29 @@ accordingly, proceeding as follows: if packages have been found, but that should not add a directory ending in "after". -12. Set 'shellpipe' and 'shellredir' - The 'shellpipe' and 'shellredir' options are set according to the value of - the 'shell' option, unless they have been set before. This means that Nvim - will figure out the values of 'shellpipe' and 'shellredir' for you, unless - you have set them yourself. +12. Set 'shellpipe' and 'shellredir', according to the value of the 'shell' + option, unless they were already set. Nvim will figure out the values of + 'shellpipe' and 'shellredir' for you, unless you have set them yourself. -13. Set 'updatecount' to zero, if "-n" command argument used. +13. Set 'updatecount' to zero, if |-n| was given. -14. Set binary options if the |-b| flag was given. +14. Set binary options if |-b| was given. 15. Read the |shada-file|. -16. Read the quickfix file if the |-q| flag was given, or exit on failure. +16. Read the quickfix file if |-q| was given, or exit on failure. 17. Open all windows. - When |-o| was given, windows will be opened (but not displayed yet). - When |-p| was given, tab pages will be created (but not displayed yet). - When switching screens, it happens now. Redrawing starts. - - If the |-q| flag was given, the first error is jumped to. + - If |-q| was given, the first error is jumped to. - Buffers for all windows will be loaded, without triggering |BufAdd|. 18. Execute startup commands. - If |-t| was given, the tag is jumped to. - Commands given with |-c| and |+cmd| are executed. - - The starting flag is reset, has("vim_starting") will now return zero. + - The |vim_starting| flag is reset, `has("vim_starting")` will now return zero. - The |v:vim_did_enter| variable is set to 1. - The |VimEnter| autocommands are executed. @@ -576,7 +574,7 @@ mapping, then you may want to save them in a vimrc file for later use. See Avoiding trojan horses ~ - *trojan-horse* + *trojan-horse* While reading the "vimrc" or the "exrc" file in the current directory, some commands can be disabled for security reasons by setting the 'secure' option. This is always done when executing the command from a tags file. Otherwise, @@ -584,24 +582,27 @@ it would be possible that you accidentally use a vimrc or tags file that somebody else created and contains nasty commands. The disabled commands are the ones that start a shell, the ones that write to a file, and ":autocmd". The ":map" commands are echoed, so you can see which keys are being mapped. - If you want Vim to execute all commands in a local vimrc file, you -can reset the 'secure' option in the EXINIT or VIMINIT environment variable or -in the global exrc or vimrc file. This is not possible in vimrc or -exrc in the current directory, for obvious reasons. - On Unix systems, this only happens if you are not the owner of the + +If you want Vim to execute all commands in a local vimrc file, you can reset +the 'secure' option in the EXINIT or VIMINIT environment variable or in the +global exrc or vimrc file. This is not possible in vimrc or exrc in the +current directory, for obvious reasons. + +On Unix systems, this only happens if you are not the owner of the vimrc file. Warning: If you unpack an archive that contains a vimrc or exrc file, it will be owned by you. You won't have the security protection. Check the vimrc file before you start Vim in that directory, or reset the 'exrc' option. Some Unix systems allow a user to do "chown" on a file. This makes it possible for another user to create a nasty vimrc and make you the owner. Be careful! - When using tag search commands, executing the search command (the last -part of the line in the tags file) is always done in secure mode. This works -just like executing a command from a vimrc in the current directory. + +When using tag search commands, executing the search command (the last part of +the line in the tags file) is always done in secure mode. This works just +like executing a command from a vimrc in the current directory. If Vim startup is slow ~ - *slow-start* + *slow-start* If Vim takes a long time to start up, use the |--startuptime| argument to find out what happens. @@ -612,7 +613,7 @@ lines stored in a register with ":set shada='20,<50,s10". |shada-file|. Troubleshooting broken configurations ~ - *bisect* + *bisect* The extreme flexibility of editors like Vim and Emacs means that any plugin or setting can affect the entire editor in ways that are not initially obvious. @@ -626,7 +627,7 @@ To find the cause of a problem in your config, you must "bisect" it: Intro message ~ - *:intro* + *:intro* When Vim starts without a file name, an introductory message is displayed. It is removed as soon as the display is redrawn. To see the message again, use the ":intro" command. To avoid the intro message on startup, add the "I" flag @@ -634,7 +635,7 @@ to 'shortmess'. ============================================================================== $VIM and $VIMRUNTIME - *$VIM* + *$VIM* The environment variable "$VIM" is used to locate various user files for Nvim, such as the user |config|. This depends on the system, see |startup|. @@ -651,7 +652,7 @@ Nvim will try to get the value for $VIM in this order: After doing this once, Nvim sets the $VIM environment variable. - *$VIMRUNTIME* + *$VIMRUNTIME* The environment variable "$VIMRUNTIME" is used to locate various support files, such as the documentation and syntax-highlighting files. For example, the main help file is normally "$VIMRUNTIME/doc/help.txt". @@ -671,33 +672,34 @@ After doing this once, Nvim sets the $VIMRUNTIME environment variable. In case you need the value of $VIMRUNTIME in a shell (e.g., for a script that greps in the help files) you might be able to use this: > - VIMRUNTIME="$(nvim --clean --headless --cmd 'echo $VIMRUNTIME|q')" + VIMRUNTIME="$(nvim --clean --headless --cmd 'echo $VIMRUNTIME|q')" ============================================================================== -Suspending *suspend* +Suspending *suspend* - *CTRL-Z* *v_CTRL-Z* -CTRL-Z Suspend Nvim, like ":stop". - Works in Normal and in Visual mode. In Insert and - Command-line mode, the CTRL-Z is inserted as a normal - character. In Visual mode Nvim goes back to Normal - mode before suspending. + *CTRL-Z* *v_CTRL-Z* +CTRL-Z Suspend Nvim, like ":stop". + Works in Normal and in Visual mode. In Insert and + Command-line mode, the CTRL-Z is inserted as a normal + character. In Visual mode Nvim goes back to Normal + mode before suspending. -:sus[pend][!] or *:sus* *:suspend* *:st* *:stop* -:st[op][!] Suspend Nvim using OS "job control"; it will continue - if you make it the foreground job again. Triggers - |VimSuspend| before suspending and |VimResume| when - resumed. - If "!" is not given and 'autowrite' is set, every - buffer with changes and a file name is written out. - If "!" is given or 'autowrite' is not set, changed - buffers are not written, don't forget to bring Nvim - back to the foreground later! +:sus[pend][!] or *:sus* *:suspend* *:st* *:stop* +:st[op][!] Suspend Nvim using OS "job control"; it will continue + if you make it the foreground job again. Triggers + |VimSuspend| before suspending and |VimResume| when + resumed. + + If "!" is not given and 'autowrite' is set, every + buffer with changes and a file name is written out. + If "!" is given or 'autowrite' is not set, changed + buffers are not written, don't forget to bring Nvim + back to the foreground later! In the GUI, suspending is implementation-defined. ============================================================================== -Exiting *exiting* +Exiting *exiting* There are several ways to exit Vim: - Close the last window with `:quit`. Only when there are no changes. @@ -710,26 +712,26 @@ When using `:cquit` or when there was an error message Vim exits with exit code 1. Errors can be avoided by using `:silent!` or with `:catch`. ============================================================================== -Saving settings *save-settings* +Saving settings *save-settings* Mostly you will edit your vimrc files manually. This gives you the greatest flexibility. There are a few commands to generate a vimrc file automatically. You can use these files as they are, or copy/paste lines to include in another vimrc file. - *:mk* *:mkexrc* -:mk[exrc] [file] Write current key mappings and changed options to - [file] (default ".exrc" in the current directory), - unless it already exists. + *:mk* *:mkexrc* +:mk[exrc] [file] Write current key mappings and changed options to + [file] (default ".exrc" in the current directory), + unless it already exists. -:mk[exrc]! [file] Always write current key mappings and changed - options to [file] (default ".exrc" in the current - directory). +:mk[exrc]! [file] Always write current key mappings and changed + options to [file] (default ".exrc" in the current + directory). - *:mkv* *:mkvi* *:mkvimrc* -:mkv[imrc][!] [file] Like ":mkexrc", but the default is ".nvimrc" in the - current directory. The ":version" command is also - written to the file. + *:mkv* *:mkvi* *:mkvimrc* +:mkv[imrc][!] [file] Like ":mkexrc", but the default is ".nvimrc" in the + current directory. The ":version" command is also + written to the file. These commands will write ":map" and ":set" commands to a file, in such a way that when these commands are executed, the current key mappings and options @@ -754,7 +756,7 @@ you want to make this file your default |config|, move it to $XDG_CONFIG_HOME/nvim. You could also use autocommands |autocommand| and/or modelines |modeline|. - *vimrc-option-example* + *vimrc-option-example* If you only want to add a single option setting to your vimrc, you can use these steps: 1. Edit your vimrc file with Vim. @@ -767,17 +769,17 @@ these steps: You need to escape special characters, esp. spaces. ============================================================================== -Views and Sessions *views-sessions* +Views and Sessions *views-sessions* This is introduced in sections |21.4| and |21.5| of the user manual. - *View* *view-file* + *View* *view-file* A View is a collection of settings that apply to one window. You can save a View and when you restore it later, the text is displayed in the same way. The options and mappings in this window will also be restored, so that you can continue editing like when the View was saved. - *Session* *session-file* + *Session* *session-file* A Session keeps the Views for all windows, plus the global settings. You can save a Session and when you restore it later the window layout looks the same. You can use a Session to quickly switch between different projects, @@ -788,13 +790,13 @@ remember information for all Views and Sessions together |shada-file|. You can quickly start editing with a previously saved View or Session with the |-S| argument: > - vim -S Session.vim + vim -S Session.vim < - *:mks* *:mksession* -:mks[ession][!] [file] Write a Vim script that restores the current editing - session. - When [!] is included, an existing file is overwritten. - When [file] is omitted, "Session.vim" is used. + *:mks* *:mksession* +:mks[ession][!] [file] Write a Vim script that restores the current editing + session. + When [!] is included, an existing file is overwritten. + When [file] is omitted, "Session.vim" is used. The output of ":mksession" is like ":mkvimrc", but additional commands are added to the file. Which ones depends on the 'sessionoptions' option. The @@ -841,26 +843,25 @@ A session includes all tab pages, unless "tabpages" was removed from The |SessionLoadPre| autocmd event is triggered before a session file is loaded/sourced and |SessionLoadPost| autocmd event is triggered after. - *SessionLoad-variable* -While the session file is loading, the SessionLoad global variable is set to -1. Plugins can use this to postpone some work until the SessionLoadPost event -is triggered. + *SessionLoad-variable* +While the session file is loading, `g:SessionLoad` is set to 1. Plugins can +use this to postpone some work until the SessionLoadPost event is triggered. - *:mkvie* *:mkview* -:mkvie[w][!] [file] Write a Vim script that restores the contents of the - current window. - When [!] is included, an existing file is overwritten. - When [file] is omitted or is a number from 1 to 9, a - name is generated and 'viewdir' prepended. When the - last path part of 'viewdir' does not exist, this - directory is created. E.g., when 'viewdir' is - "$VIM/vimfiles/view" then "view" is created in - "$VIM/vimfiles". - An existing file is always overwritten then. Use - |:loadview| to load this view again. - When [file] is the name of a file ('viewdir' is not - used), a command to edit the file is added to the - generated file. + *:mkvie* *:mkview* +:mkvie[w][!] [file] Write a Vim script that restores the contents of the + current window. + When [!] is included, an existing file is overwritten. + When [file] is omitted or is a number from 1 to 9, a + name is generated and 'viewdir' prepended. When the + last path part of 'viewdir' does not exist, this + directory is created. E.g., when 'viewdir' is + "$VIM/vimfiles/view" then "view" is created in + "$VIM/vimfiles". + An existing file is always overwritten then. Use + |:loadview| to load this view again. + When [file] is the name of a file ('viewdir' is not + used), a command to edit the file is added to the + generated file. The output of ":mkview" contains these items: 1. The argument list used in the window. When the global argument list is @@ -895,11 +896,11 @@ Note that Views and Sessions are not perfect: - The Vim script is not very efficient. But still faster than typing the commands yourself! - *:lo* *:loadview* -:lo[adview] [nr] Load the view for the current file. When [nr] is - omitted, the view stored with ":mkview" is loaded. - When [nr] is specified, the view stored with ":mkview - [nr]" is loaded. + *:lo* *:loadview* +:lo[adview] [nr] Load the view for the current file. When [nr] is + omitted, the view stored with ":mkview" is loaded. + When [nr] is specified, the view stored with ":mkview + [nr]" is loaded. The combination of ":mkview" and ":loadview" can be used to store up to ten different views of a file. These are remembered in the directory specified @@ -910,11 +911,11 @@ found. You might want to clean up your 'viewdir' directory now and then. To automatically save and restore views for `*.c` files: > - au BufWinLeave *.c mkview - au BufWinEnter *.c silent! loadview + au BufWinLeave *.c mkview + au BufWinEnter *.c silent! loadview ============================================================================== -Shada ("shared data") file *shada* *shada-file* +Shada ("shared data") file *shada* *shada-file* If you exit Vim and later start it again, you would normally lose a lot of information. The ShaDa file can be used to remember that information, which @@ -941,14 +942,14 @@ Session. You could have several Session files, one for each project you are working on. ShaDa and Session files together can be used to effectively enter Vim and directly start working in your desired setup. |session-file| - *shada-read* + *shada-read* When Vim is started and the 'shada' option is non-empty, the contents of the ShaDa file are read and the info can be used in the appropriate places. The |v:oldfiles| variable is filled. The marks are not read in at startup (but file marks are). See |initialization| for how to set the 'shada' option upon startup. - *shada-write* + *shada-write* When Vim exits and 'shada' is non-empty, the info is stored in the ShaDa file (it's actually merged with the existing one, if one exists |shada-merging|). The 'shada' option is a string containing information about what info should @@ -983,7 +984,7 @@ would use "ra:,rb:"). The |v:oldfiles| variable is filled with the file names that the ShaDa file has marks for. - *shada-file-marks* + *shada-file-marks* Uppercase marks ('A to 'Z) are stored when writing the ShaDa file. The numbered marks ('0 to '9) are a bit special. When the ShaDa file is written (when exiting or with the |:wshada| command), '0 is set to the current @@ -994,20 +995,20 @@ having the same position twice. The result is that with "'0", you can jump back to the file and line where you exited Vim. To do that right away, try using this command: > - vim -c "normal '0" + vim -c "normal '0" In a C shell descendant, you could make an alias for it: > - alias lvim vim -c '"'normal "'"0'"' + alias lvim vim -c '"'normal "'"0'"' For a Bash-like shell: > - alias lvim='vim -c "normal '\''0"' + alias lvim='vim -c "normal '\''0"' Use the "r" flag in 'shada' to specify for which files no marks should be remembered. -MERGING *shada-merging* +MERGING *shada-merging* When writing ShaDa files with |:wshada| without bang or at regular exit information in the existing ShaDa file is merged with information from current @@ -1037,7 +1038,7 @@ with ShaDa entries. Specifically the following is being done: fashion: the only header and buffer list present are the ones from the Nvim instance which was last writing the file. |shada-%| -COMPATIBILITY *shada-compatibility* +COMPATIBILITY *shada-compatibility* ShaDa files are forward and backward compatible. This means that @@ -1073,7 +1074,7 @@ ShaDa files are forward and backward compatible. This means that "Blindly" here means that there will be no attempts to somehow merge them, even if other entries (with known name/type/etc) are merged. |shada-merging| -SHADA FILE NAME *shada-file-name* +SHADA FILE NAME *shada-file-name* - Default name of the |shada| file is: Unix: "$XDG_STATE_HOME/nvim/shada/main.shada" @@ -1089,7 +1090,7 @@ SHADA FILE NAME *shada-file-name* default and the name given with 'shada' or "-i" (unless it's NONE). -MANUALLY READING AND WRITING *shada-read-write* +MANUALLY READING AND WRITING *shada-read-write* Two commands can be used to read and write the ShaDa file manually. This can be used to exchange registers between two running Vim programs: First @@ -1106,13 +1107,13 @@ do this. This can be useful in order to create a second file, say you first start Nvim. For example, you can preload registers with particular data, or put certain commands in the command line history. A line in your |config| file like > - :rshada! ~/.my.shada + :rshada! ~/.my.shada can be used to load this information. You could even have different ShaDa files for different types of files (e.g., C code) and load them based on the file name, using the ":autocmd" command (see |:autocmd|). More information on ShaDa file format is contained in |shada-format| section. - *E136* *E929* *shada-error-handling* + *E136* *E929* *shada-error-handling* Some errors make Nvim leave temporary file named `{basename}.tmp.X` (X is any free letter from `a` to `z`) while normally it will create this file, write to it and then rename `{basename}.tmp.X` to `{basename}`. Such errors @@ -1151,44 +1152,44 @@ running) you have additional options: different from using |:wshada| with bang, but "rm -f" works in some cases when you don't have write permissions. - *:rsh* *:rshada* *E886* -:rsh[ada][!] [file] Read from ShaDa file [file] (default: see above). - If [!] is given, then any information that is - already set (registers, marks, |v:oldfiles|, etc.) - will be overwritten. + *:rsh* *:rshada* *E886* +:rsh[ada][!] [file] Read from ShaDa file [file] (default: see above). + If [!] is given, then any information that is + already set (registers, marks, |v:oldfiles|, etc.) + will be overwritten. - *:wsh* *:wshada* *E137* -:wsh[ada][!] [file] Write to ShaDa file [file] (default: see above). - The information in the file is first read in to make - a merge between old and new info. When [!] is used, - the old information is not read first, only the - internal info is written (also disables safety checks - described in |shada-error-handling|). If 'shada' is - empty, marks for up to 100 files will be written. - When you get error "E929: All .tmp.X files exist, - cannot write ShaDa file!", check that no old temp - files were left behind (e.g. - ~/.local/state/nvim/shada/main.shada.tmp*). + *:wsh* *:wshada* *E137* +:wsh[ada][!] [file] Write to ShaDa file [file] (default: see above). + The information in the file is first read in to make + a merge between old and new info. When [!] is used, + the old information is not read first, only the + internal info is written (also disables safety checks + described in |shada-error-handling|). If 'shada' is + empty, marks for up to 100 files will be written. + When you get error "E929: All .tmp.X files exist, + cannot write ShaDa file!", check that no old temp + files were left behind (e.g. + ~/.local/state/nvim/shada/main.shada.tmp*). - Note: Executing :wshada will reset all |'quote| marks. + Note: Executing :wshada will reset all |'quote| marks. - *:o* *:ol* *:oldfiles* -:o[ldfiles] List the files that have marks stored in the ShaDa - file. This list is read on startup and only changes - afterwards with `:rshada!`. Also see |v:oldfiles|. - The number can be used with |c_#<|. - The output can be filtered with |:filter|, e.g.: > - filter /\.vim/ oldfiles -< The filtering happens on the file name. + *:o* *:ol* *:oldfiles* +:o[ldfiles] List the files that have marks stored in the ShaDa + file. This list is read on startup and only changes + afterwards with `:rshada!`. Also see |v:oldfiles|. + The number can be used with |c_#<|. + The output can be filtered with |:filter|, e.g.: > + filter /\.vim/ oldfiles +< The filtering happens on the file name. :bro[wse] o[ldfiles][!] - List file names as with |:oldfiles|, and then prompt - for a number. When the number is valid that file from - the list is edited. + List file names as with |:oldfiles|, and then prompt + for a number. When the number is valid that file from + the list is edited. - Use [!] to abandon a modified buffer. |abandon| + Use [!] to abandon a modified buffer. |abandon| -SHADA FILE FORMAT *shada-format* +SHADA FILE FORMAT *shada-format* ShaDa files are concats of MessagePack entries. Each entry is a concat of exactly four MessagePack objects: @@ -1206,10 +1207,11 @@ exactly four MessagePack objects: Exact format depends on the entry type: Entry type (name) Entry data ~ - 1 (Header) Map containing data that describes the generator + + - 1 (Header) Map containing data that describes the generator instance that wrote this ShaDa file. It is ignored when reading ShaDa files. Contains the following data: - Key Data ~ + Key Data > generator Binary, software used to generate ShaDa file. Is equal to "nvim" when ShaDa file was written by Nvim. @@ -1217,9 +1219,10 @@ exactly four MessagePack objects: encoding Binary, effective 'encoding' value. max_kbyte Integer, effective |shada-s| limit value. pid Integer, instance process ID. - `*` It is allowed to have any number of + * It is allowed to have any number of additional keys with any data. - 2 (SearchPattern) Map containing data describing last used search or +< + - 2 (SearchPattern) Map containing data describing last used search or substitute pattern. Normally ShaDa file contains two such entries: one with "ss" key set to true (describes substitute pattern, see |:substitute|), and one set to @@ -1227,7 +1230,7 @@ exactly four MessagePack objects: |search-commands|). "su" key should be true on one of the entries. If key value is equal to default then it is normally not present. Keys: - Key Type Default Description ~ + Key Type Default Description > sm Boolean true Effective 'magic' value. sc Boolean false Effective 'smartcase' value. sl Boolean true True if search pattern comes @@ -1248,14 +1251,15 @@ exactly four MessagePack objects: sp Binary N/A Actual pattern. Required. sb Boolean false True if search direction is backward. - `*` any none Other keys are allowed for + * any none Other keys are allowed for compatibility reasons, see |shada-compatibility|. - 3 (SubString) Array containing last |:substitute| replacement string. +< + - 3 (SubString) Array containing last |:substitute| replacement string. Contains single entry: binary, replacement string used. More entries are allowed for compatibility reasons, see |shada-compatibility|. - 4 (HistoryEntry) Array containing one entry from history. Should have + - 4 (HistoryEntry) Array containing one entry from history. Should have two or three entries. First one is history type (unsigned integer), second is history line (binary), third is the separator character (unsigned integer, @@ -1264,10 +1268,10 @@ exactly four MessagePack objects: listed in |hist-names|, here are the corresponding numbers: 0 - cmd, 1 - search, 2 - expr, 3 - input, 4 - debug. - 5 (Register) Map describing one register (|registers|). If key + - 5 (Register) Map describing one register (|registers|). If key value is equal to default then it is normally not present. Keys: - Key Type Def Description ~ + Key Type Def Description > rt UInteger 0 Register type: No Description ~ 0 |charwise-register| @@ -1293,18 +1297,19 @@ exactly four MessagePack objects: * any none Other keys are allowed for compatibility reasons, see |shada-compatibility|. - 6 (Variable) Array containing two items: variable name (binary) and +< + - 6 (Variable) Array containing two items: variable name (binary) and variable value (any object). Values are converted using the same code |msgpackparse()| uses when reading, |msgpackdump()| when writing, so there may appear |msgpack-special-dict|s. If there are more then two entries then the rest are ignored (|shada-compatibility|). - 7 (GlobalMark) - 8 (Jump) - 10 (LocalMark) - 11 (Change) Map containing some position description: - Entry Position ~ + - 7 (GlobalMark) + - 8 (Jump) + - 10 (LocalMark) + - 11 (Change) Map containing some position description: + Entry Position > GlobalMark Global mark position. |'A| LocalMark Local mark position. |'a| Jump One position from the |jumplist|. @@ -1319,31 +1324,35 @@ exactly four MessagePack objects: GlobalMark and LocalMark entries. f Binary N/A File name. Required. - `*` any none Other keys are allowed for + * any none Other keys are allowed for compatibility reasons, see |shada-compatibility|. - 9 (BufferList) Array containing maps. Each map in the array +< + - 9 (BufferList) Array containing maps. Each map in the array represents one buffer. Possible keys: - Key Type Default Description ~ + Key Type Default Description > l UInteger 1 Position line number. Must be greater then zero. c UInteger 0 Position column number. f Binary N/A File name. Required. - `*` any none Other keys are allowed for + * any none Other keys are allowed for compatibility reasons, see |shada-compatibility|. - `*` (Unknown) Any other entry type is allowed for compatibility +< + - `*` (Unknown) Any other entry type is allowed for compatibility reasons, see |shada-compatibility|. - *E575* *E576* + *E575* *E576* Errors in ShaDa file may have two types: 1. E575 for “logical” errors. 2. E576 for “critical” errors. + When writing, critical errors trigger behaviour described in |shada-error-handling|. When reading, critical errors cause the rest of the file to be skipped. + Critical errors include: - *shada-critical-contents-errors* + *shada-critical-contents-errors* - Any of first three MessagePack objects being not an unsigned integer. - Third object requesting amount of bytes greater then bytes left in the ShaDa file. @@ -1355,15 +1364,16 @@ Critical errors include: complete MessagePack object. ============================================================================== -Standard Paths *standard-path* +Standard Paths *standard-path* Nvim stores configuration, data, and logs in standard locations. Plugins are strongly encouraged to follow this pattern also. Use |stdpath()| to get the paths. - *base-directories* *xdg* + *base-directories* *xdg* The "base" (root) directories conform to the XDG Base Directory Specification. https://specifications.freedesktop.org/basedir/latest/ + The $XDG_CONFIG_HOME, $XDG_DATA_HOME, $XDG_RUNTIME_DIR, $XDG_STATE_HOME, $XDG_CACHE_HOME, $XDG_CONFIG_DIRS and $XDG_DATA_DIRS environment variables are used if defined, else default values (listed below) are used. @@ -1372,49 +1382,49 @@ Note: In the help these defaults are used as placeholders, e.g. "~/.config" is understood as "$XDG_CONFIG_HOME or ~/.config". CONFIG DIRECTORY (DEFAULT) ~ - *$XDG_CONFIG_HOME* Nvim: stdpath("config") + *$XDG_CONFIG_HOME* Nvim: stdpath("config") > Unix: ~/.config ~/.config/nvim Windows: ~/AppData/Local ~/AppData/Local/nvim DATA DIRECTORY (DEFAULT) ~ - *$XDG_DATA_HOME* Nvim: stdpath("data") + *$XDG_DATA_HOME* Nvim: stdpath("data") > Unix: ~/.local/share ~/.local/share/nvim Windows: ~/AppData/Local ~/AppData/Local/nvim-data RUN DIRECTORY (DEFAULT) ~ - *$XDG_RUNTIME_DIR* Nvim: stdpath("run") + *$XDG_RUNTIME_DIR* Nvim: stdpath("run") > Unix: /tmp/nvim.user/xxx /tmp/nvim.user/xxx Windows: $TMP/nvim.user/xxx $TMP/nvim.user/xxx STATE DIRECTORY (DEFAULT) ~ - *$XDG_STATE_HOME* Nvim: stdpath("state") + *$XDG_STATE_HOME* Nvim: stdpath("state") > Unix: ~/.local/state ~/.local/state/nvim Windows: ~/AppData/Local ~/AppData/Local/nvim-data CACHE DIRECTORY (DEFAULT) ~ - *$XDG_CACHE_HOME* Nvim: stdpath("cache") + *$XDG_CACHE_HOME* Nvim: stdpath("cache") > Unix: ~/.cache ~/.cache/nvim Windows: ~/AppData/Local/Temp ~/AppData/Local/Temp/nvim-data LOG FILE (DEFAULT) ~ - `$NVIM_LOG_FILE` Nvim: stdpath("log")/nvim.log + `$NVIM_LOG_FILE` Nvim: stdpath("log")/nvim.log > Unix: ~/.local/state/nvim ~/.local/state/nvim/nvim.log Windows: ~/AppData/Local/nvim-data ~/AppData/Local/nvim-data/nvim.log Note that stdpath("log") is currently an alias for stdpath("state"). ADDITIONAL CONFIGS DIRECTORY (DEFAULT) ~ - *$XDG_CONFIG_DIRS* Nvim: stdpath("config_dirs") + *$XDG_CONFIG_DIRS* Nvim: stdpath("config_dirs") > Unix: /etc/xdg/ /etc/xdg/nvim Windows: Not applicable Not applicable ADDITIONAL DATA DIRECTORY (DEFAULT) ~ - *$XDG_DATA_DIRS* Nvim: stdpath("data_dirs") + *$XDG_DATA_DIRS* Nvim: stdpath("data_dirs") > Unix: /usr/local/share /usr/local/share/nvim /usr/share /usr/share/nvim Windows: Not applicable Not applicable -NVIM_APPNAME *$NVIM_APPNAME* +NVIM_APPNAME *$NVIM_APPNAME* The standard directories can be further configured by the `$NVIM_APPNAME` environment variable. This variable controls the sub-directory that Nvim will read from (and auto-create) in each of the base directories. For example, @@ -1426,19 +1436,19 @@ relative path, such as "foo/bar". Note: In the help wherever `$XDG_CONFIG_…/nvim` is mentioned it is understood as `$XDG_CONFIG_…/$NVIM_APPNAME`. - *state-isolation* + *state-isolation* One use-case for $NVIM_APPNAME is to "isolate" Nvim applications. Alternatively, for true isolation, on Linux you can use cgroups namespaces: > systemd-run --user -qt -p PrivateUsers=yes -p BindPaths=/home/user/profile_xy:/home/user/.config/nvim nvim < - *stateless* + *stateless* To run Nvim without creating any directories or data files: > NVIM_LOG_FILE=/dev/null nvim -n -i NONE -LOG FILE *log* *$NVIM_LOG_FILE* *E5430* +LOG FILE *log* *$NVIM_LOG_FILE* *E5430* Besides 'debug' and 'verbose', Nvim keeps a general log file for internal debugging, plugins and RPC clients. > - :echo $NVIM_LOG_FILE + :echo $NVIM_LOG_FILE Default location is stdpath("log")/log ($XDG_STATE_HOME/nvim/nvim.log) unless that path is inaccessible or $NVIM_LOG_FILE was set before |startup|. diff --git a/runtime/lua/vim/_core/editor.lua b/runtime/lua/vim/_core/editor.lua index 202a5a4da4..46ada5b9ab 100644 --- a/runtime/lua/vim/_core/editor.lua +++ b/runtime/lua/vim/_core/editor.lua @@ -304,7 +304,7 @@ end local VIM_CMD_ARG_MAX = 20 ---- Executes Vimscript (|Ex-commands|). +--- Executes Vimscript (|Ex-command|s). --- --- Can be indexed with a command name to get a function, thus you can write `vim.cmd.echo(…)` --- instead of `vim.cmd{cmd='echo',…}`. diff --git a/src/gen/gen_help_html.lua b/src/gen/gen_help_html.lua index 35ac7a7054..76027cad44 100644 --- a/src/gen/gen_help_html.lua +++ b/src/gen/gen_help_html.lua @@ -95,6 +95,7 @@ local new_layout = { ['nvim.txt'] = true, ['pack.txt'] = true, ['provider.txt'] = true, + ['starting.txt'] = true, ['terminal.txt'] = true, ['tui.txt'] = true, ['ui.txt'] = true, diff --git a/src/nvim/ex_session.c b/src/nvim/ex_session.c index 7af10d1a87..e4761bda32 100644 --- a/src/nvim/ex_session.c +++ b/src/nvim/ex_session.c @@ -999,7 +999,7 @@ void ex_mkrc(exarg_T *eap) } if (eap->cmdidx == CMD_mksession) { - if (put_line(fd, "let SessionLoad = 1") == FAIL) { + if (put_line(fd, "let g:SessionLoad = 1") == FAIL) { failed = true; } } @@ -1073,7 +1073,7 @@ void ex_mkrc(exarg_T *eap) failed = true; } if (eap->cmdidx == CMD_mksession) { - if (fprintf(fd, "unlet SessionLoad\n") < 0) { + if (fprintf(fd, "unlet g:SessionLoad\n") < 0) { failed = true; } }