Predefined variables vvars v:var v:

Most variables are read-only, when a variable can be set by the user, it will be mentioned at the variable description below. The type cannot be changed.

v:argf v:argf argf-variable File arguments (expanded to absolute paths) given at startup.

Unlike v:argv, this does not include option arguments such as -u, --cmd, or +cmd. Unlike argv(), it is not affected by later :args, :argadd, or plugin modifications.

Example:

nvim file1.txt +ls -- file2.txt
:echo v:argf
" ['/path/to/cwd/file1.txt', '/path/to/cwd/file2.txt']

v:argv v:argv argv-variable Command line arguments (-u, --cmd, +cmd, …) Nvim was invoked with. The first item is the Nvim command.

See v:progpath to get the full path to Nvim. See v:argf to get only file args, without other options.

v:cascading v:cascading cascading-variable v:true during multicursor cascade, v:false otherwise. Read-only.

v:char v:char char-variable Argument for evaluating 'formatexpr' and used for the typed character when using <expr> in an abbreviation :map-<expr>. It is also used by the InsertCharPre, InsertEnter, CmdlineLeave and CmdlineLeavePre events.

v:charconvert_from v:charconvert_from charconvert_from-variable The name of the character encoding of a file to be converted. Only valid while evaluating the 'charconvert' option.

v:charconvert_to v:charconvert_to charconvert_to-variable The name of the character encoding of a file after conversion. Only valid while evaluating the 'charconvert' option.

v:cmdarg v:cmdarg cmdarg-variable The extra arguments ("++p", "++enc=", "++ff=") given to a file read/write command. This is set before an autocommand event for a file read/write command is triggered. There is a leading space to make it possible to append this variable directly after the read/write command. Note: "+cmd" isn't included here, because it will be executed anyway.

v:cmdbang v:cmdbang cmdbang-variable Set like v:cmdarg for a file read/write command. When a "!" was used the value is 1, otherwise it is 0. Note that this can only be used in autocommands. For user commands <bang> can be used.

v:collate v:collate collate-variable The current locale setting for collation order of the runtime environment. This allows Vim scripts to be aware of the current locale encoding. Technical: it's the value of LC_COLLATE. When not using a locale the value is "C". This variable can not be set directly, use the :language command. See multi-lang.

v:completed_item v:completed_item completed_item-variable Dictionary containing the complete-items for the most recently completed word after CompleteDone. Empty if the completion failed, or after leaving and re-entering insert mode. Note: Plugins can modify the value to emulate the builtin CompleteDone event behavior.

v:count v:count count-variable The count given for the last Normal mode command. Can be used to get the count before a mapping. Read-only. Example:

:map _x :<C-U>echo "the count is " .. v:count<CR>

Note: The <C-U> is required to remove the line range that you get when typing ':' after a count. When there are two counts, as in "3d2w", they are multiplied, just like what happens in the command, "d6w" for the example. Also used for evaluating the 'formatexpr' option.

v:count1 v:count1 count1-variable Just like "v:count", but defaults to one when no count is used.

v:ctype v:ctype ctype-variable The current locale setting for characters of the runtime environment. This allows Vim scripts to be aware of the current locale encoding. Technical: it's the value of LC_CTYPE. When not using a locale the value is "C". This variable can not be set directly, use the :language command. See multi-lang.

v:dying v:dying dying-variable Normally zero. When a deadly signal is caught it's set to one. When multiple signals are caught the number increases. Can be used in an autocommand to check if Vim didn't terminate normally. Example:

:au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif

Note: if another deadly signal is caught when v:dying is one, VimLeave autocommands will not be executed.

v:echospace v:echospace echospace-variable Number of screen cells that can be used for an :echo message in the last screen line before causing the hit-enter prompt (no longer applicable when ui2 is enabled).

Depends on 'showcmd', 'ruler' and 'columns'. You need to check 'cmdheight' for whether there are full-width lines available above the last line.

v:errmsg v:errmsg errmsg-variable Last error message that occurred (not necessarily displayed). Modifiable (can be set). Example:

let v:errmsg = ""
silent! next
if v:errmsg != ""
  " ... handle error

v:errors v:errors errors-variable assert-return Errors found by assert functions, such as assert_true(). This is a list of strings. The assert functions append an item when an assert fails. The return value indicates this: a one is returned if an item was added to v:errors, otherwise zero is returned. To remove old results make it empty:

let v:errors = []

If v:errors is set to anything but a list it is made an empty list by the assert function.

v:event v:event event-variable Dictionary of event data for the current autocommand. Valid only during the event lifetime; storing or passing v:event is invalid! Copy it instead:

au TextYankPost * let g:foo = deepcopy(v:event)

Keys vary by event; see the documentation for the specific event, e.g. DirChanged or TextYankPost. abort Whether the event triggered during an aborting condition (e.g. c_Esc or c_CTRL-C for CmdlineLeave). chan channel-id changed_window Is v:true if the event fired while changing window (or tab) on DirChanged. cmdlevel Level of cmdline. cmdtype Type of cmdline, cmdline-char. col Column count of popup menu on CompleteChanged, relative to screen. complete_type See complete_info_mode complete_word The selected word, or empty if completion was abandoned/discarded. completed_item Current selected item on CompleteChanged, or {} if no item selected. cwd Current working directory. height Height of popup menu on CompleteChanged inclusive Motion is inclusive, else exclusive. info Dict of arbitrary event data. operator Current operator. Also set for Ex commands (unlike v:operator). For example if TextYankPost is triggered by the :yank Ex command then v:event.operator is "y". reason CompleteDone reason. regcontents Text stored in the register as a readfile()-style list of lines. regname Requested register (e.g "x" for "xyy), or empty string for an unnamed operation. regtype Type of register as returned by getregtype(). row Row count of popup menu on CompleteChanged, relative to screen. scope Event-specific scope name. scrollbar v:true if popup menu has a scrollbar, or v:false if not. size Total number of completion items on CompleteChanged. status Job status or exit code, -1 means "unknown". TermClose visual Selection is visual (as opposed to e.g. a motion range). width Width of popup menu on CompleteChanged windows List of window IDs that changed on WinResized

v:exception v:exception exception-variable The value of the exception most recently caught and not finished. See also v:stacktrace, v:throwpoint, and throw-variables. Example:

try
  throw "oops"
catch /.*/
  echo "caught " .. v:exception
endtry

Output: "caught oops".

v:exiting v:exiting exiting-variable Exit code, or v:null before invoking the VimLeavePre and VimLeave autocmds. See :q, :x and :cquit. Example:

:au VimLeave * echo "Exit code is " .. v:exiting

v:exitreason v:exitreason exitreason-variable Reason for the current exit. Set before QuitPre. Reset if exit was canceled.

Possible values:

Example:

autocmd ExitPre * if v:exitreason ==# 'restart' | echomsg 'restarting' | endif

Read-only.

v:false v:false false-variable Special value used to put "false" in JSON and msgpack. See json_encode(). This value is converted to "v:false" when used as a String (e.g. in expr5 with string concatenation operator) and to zero when used as a Number (e.g. in expr5 or expr7 when used with numeric operators). Read-only.

v:fcs_choice v:fcs_choice fcs_choice-variable What should happen after a FileChangedShell event was triggered. Can be used in an autocommand to tell Vim what to do with the affected buffer: reload Reload the buffer (does not work if the file was deleted). edit Reload the buffer and detect the values for options such as 'fileformat', 'fileencoding', 'binary' (does not work if the file was deleted). ask Ask the user what to do, as if there was no autocommand. Except that when only the timestamp changed nothing will happen. <empty> Nothing, the autocommand should do everything that needs to be done. The default is empty. If another (invalid) value is used then Vim behaves like it is empty, there is no warning message.

v:fcs_reason v:fcs_reason fcs_reason-variable The reason why the FileChangedShell event was triggered. Can be used in an autocommand to decide what to do and/or what to set v:fcs_choice to. Possible values:

v:fname v:fname fname-variable When evaluating 'includeexpr': the file name that was detected. Empty otherwise.

v:fname_diff v:fname_diff fname_diff-variable The name of the diff (patch) file. Only valid while evaluating 'patchexpr'.

v:fname_in v:fname_in fname_in-variable The name of the input file. Valid while evaluating: 'charconvert' file to be converted 'diffexpr' original file 'patchexpr' original file And set to the swap file name for SwapExists.

v:fname_new v:fname_new fname_new-variable The name of the new version of the file. Only valid while evaluating 'diffexpr'.

v:fname_out v:fname_out fname_out-variable The name of the output file. Only valid while evaluating: 'charconvert' resulting converted file [1] 'diffexpr' output of diff 'patchexpr' resulting patched file [1] When doing conversion for a write command (e.g., ":w file") it will be equal to v:fname_in. When doing conversion for a read command (e.g., ":e file") it will be a temporary file and different from v:fname_in.

v:folddashes v:folddashes folddashes-variable Used for 'foldtext': dashes representing foldlevel of a closed fold. Read-only in the sandbox. fold-foldtext

v:foldend v:foldend foldend-variable Used for 'foldtext': last line of closed fold. Read-only in the sandbox. fold-foldtext

v:foldlevel v:foldlevel foldlevel-variable Used for 'foldtext': foldlevel of closed fold. Read-only in the sandbox. fold-foldtext

v:foldstart v:foldstart foldstart-variable Used for 'foldtext': first line of closed fold. Read-only in the sandbox. fold-foldtext

v:hlsearch v:hlsearch hlsearch-variable Variable that indicates whether search highlighting is on. Setting it makes sense only if 'hlsearch' is enabled. Setting this variable to zero acts like the :nohlsearch command, setting it to one acts like

let &hlsearch = &hlsearch

Note that the value is restored when returning from a function. function-search-undo.

v:insertmode v:insertmode insertmode-variable Used for the InsertEnter and InsertChange autocommand events. Values: i Insert mode r Replace mode v Virtual Replace mode

v:key v:key key-variable Key of the current item of a Dictionary. Only valid while evaluating the expression used with map() and filter(). Read-only.

v:lang v:lang lang-variable The current locale setting for messages of the runtime environment. This allows Vim scripts to be aware of the current language. Technical: it's the value of LC_MESSAGES. The value is system dependent. This variable can not be set directly, use the :language command. It can be different from v:ctype when messages are desired in a different language than what is used for character encoding. See multi-lang.

v:lc_time v:lc_time lc_time-variable The current locale setting for time messages of the runtime environment. This allows Vim scripts to be aware of the current language. Technical: it's the value of LC_TIME. This variable can not be set directly, use the :language command. See multi-lang.

v:lnum v:lnum lnum-variable Line number for the 'foldexpr' fold-expr, 'formatexpr', 'indentexpr' and 'statuscolumn' expressions, tab page number for 'guitablabel' and 'guitabtooltip'. Only valid while one of these expressions is being evaluated. Read-only when in the sandbox.

v:lua v:lua lua-variable Prefix for calling Lua functions from expressions. See v:lua-call for more information.

v:maxcol v:maxcol maxcol-variable Maximum line length. Depending on where it is used it can be screen columns, characters or bytes. The value currently is 2147483647 on all systems.

v:mouse_col v:mouse_col mouse_col-variable Column number for a mouse click obtained with getchar(). This is the screen column number, like with virtcol(). The value is zero when there was no mouse button click.

v:mouse_lnum v:mouse_lnum mouse_lnum-variable Line number for a mouse click obtained with getchar(). This is the text line number, not the screen line number. The value is zero when there was no mouse button click.

v:mouse_win v:mouse_win mouse_win-variable Window number for a mouse click obtained with getchar(). First window has number 1, like with winnr(). The value is zero when there was no mouse button click.

v:mouse_winid v:mouse_winid mouse_winid-variable window-ID for a mouse click obtained with getchar(). The value is zero when there was no mouse button click.

v:msgpack_types v:msgpack_types msgpack_types-variable Dictionary containing msgpack types used by msgpackparse() and msgpackdump(). All types inside dictionary are fixed (not editable) empty lists. To check whether some list is one of msgpack types, use is operator.

v:null v:null null-variable Special value used to put "null" in JSON and NIL in msgpack. See json_encode(). This value is converted to "v:null" when used as a String (e.g. in expr5 with string concatenation operator) and to zero when used as a Number (e.g. in expr5 or expr7 when used with numeric operators). Read-only. In some places v:null can be used for a List, Dict, etc. that is not set. That is slightly different than an empty List, Dict, etc.

v:numbermax v:numbermax numbermax-variable Maximum value of a number.

v:numbermin v:numbermin numbermin-variable Minimum value of a number (negative).

v:numbersize v:numbersize numbersize-variable Number of bits in a Number. This is normally 64, but on some systems it may be 32.

v:oldfiles v:oldfiles oldfiles-variable List of file names that is loaded from the shada file on startup. These are the files that Vim remembers marks for. The length of the List is limited by the ' argument of the 'shada' option (default is 100). When the shada file is not used the List is empty. Also see :oldfiles and c_#<. The List can be modified, but this has no effect on what is stored in the shada file later. If you use values other than String this will cause trouble.

v:operator v:operator operator-variable The last operator given in Normal mode. This is a single character except for commands starting with <g> or <z>, in which case it is two characters. Best used alongside v:prevcount and v:register. Useful if you want to cancel Operator-pending mode and then use the operator, e.g.:

:omap O <Esc>:call MyMotion(v:operator)<CR>

The value remains set until another operator is entered, thus don't expect it to be empty. v:operator is not set for :delete, :yank or other Ex commands. Read-only.

v:option_command v:option_command option_command-variable Command used to set the option. Valid while executing an OptionSet autocommand. "setlocal" :setlocal or :let l:xxx "setglobal" :setglobal or :let g:xxx "set" :set or :let "modeline" modeline

v:option_new v:option_new option_new-variable New value of the option. Valid while executing an OptionSet autocommand.

v:option_old v:option_old option_old-variable Old value of the option. Valid while executing an OptionSet autocommand. Depending on the command used for setting and the kind of option this is either the local old value or the global old value.

v:option_oldglobal v:option_oldglobal option_oldglobal-variable Old global value of the option. Valid while executing an OptionSet autocommand.

v:option_oldlocal v:option_oldlocal option_oldlocal-variable Old local value of the option. Valid while executing an OptionSet autocommand.

v:option_type v:option_type option_type-variable Scope of the set command. Valid while executing an OptionSet autocommand. Can be either "global" or "local"

v:prevcount v:prevcount prevcount-variable The count given for the last but one Normal mode command. This is the v:count value of the previous command. Useful if you want to cancel Visual or Operator-pending mode and then use the count, e.g.:

:vmap % <Esc>:call MyFilter(v:prevcount)<CR>

Read-only.

v:profiling v:profiling profiling-variable Normally zero. Set to one after using ":profile start". See profiling.

v:progname v:progname progname-variable The name by which Nvim was invoked (with path removed). Read-only.

v:progpath v:progpath progpath-variable Absolute path to the current running Nvim. Read-only.

v:register v:register register-variable The name of the register in effect for the current normal mode command (regardless of whether that command actually used a register). Or for the currently executing normal mode mapping (use this in custom commands that take a register). If none is supplied it is the default register '"', unless 'clipboard' contains "unnamed" or "unnamedplus", then it is "*" or '+'. Also see getreg() and setreg()

v:relnum v:relnum relnum-variable Relative line number for the 'statuscolumn' expression. Read-only.

v:scrollstart v:scrollstart scrollstart-variable String describing the script or function that caused the screen to scroll up. It's only set when it is empty, thus the first reason is remembered. It is set to "Unknown" for a typed command.

v:searchforward v:searchforward searchforward-variable Search direction: 1 after a forward search, 0 after a backward search. It is reset to forward when directly setting the last search pattern, see quote/. Note that the value is restored when returning from a function. function-search-undo. Read-write.

v:servername v:servername servername-variable Primary listen-address of Nvim, the first item returned by serverlist(). Usually this is the named pipe created by Nvim at startup or given by --listen (or the deprecated $NVIM_LISTEN_ADDRESS env var).

See also serverstart() serverstop(). Read-only.

$NVIM $NVIM is set to v:servername by terminal and jobstart(), and is thus a hint that the current environment is a child (direct subprocess) of Nvim.

Example: a child Nvim process can detect and make requests to its parent Nvim:

if vim.env.NVIM then
  local ok, chan = pcall(vim.fn.sockconnect, 'pipe', vim.env.NVIM, {rpc=true})
  if ok and chan then
    local client = vim.api.nvim_get_chan_info(chan).client
    local rv = vim.rpcrequest(chan, 'nvim_exec_lua', [[return ... + 1]], { 41 })
    vim.print(('got "%s" from parent Nvim'):format(rv))
  end
end

v:shell_error v:shell_error shell_error-variable Result of the last shell command. When non-zero, the last shell command had an error. When zero, there was no problem. This only works when the shell returns the error code to Vim. The value -1 is often used when the command could not be executed. Read-only. Example:

!mv foo bar
if v:shell_error
  echo 'could not rename "foo" to "bar"!'
endif

v:stacktrace v:stacktrace stacktrace-variable The stack trace of the exception most recently caught and not finished. Refer to getstacktrace() for the structure of stack trace. See also v:exception, v:throwpoint, and throw-variables.

v:startreason v:startreason startreason-variable The reason Nvim started. Possible values:

Read-only.

v:starttime v:starttime starttime-variable Timestamp (nanoseconds since UNIX epoch) when the Nvim process started.

To see the current "uptime":

vim.print(('uptime: %d seconds'):format(os.time() - (vim.v.starttime / 1e9)))

Read-only.

v:statusmsg v:statusmsg statusmsg-variable Last given status message. Modifiable (can be set).

v:stderr v:stderr stderr-variable channel-id corresponding to stderr. The value is always 2; use this variable to make your code more descriptive. Unlike stdin and stdout (see stdioopen()), stderr is always open for writing. Example:

:call chansend(v:stderr, "error: toaster empty\n")

v:swapchoice v:swapchoice swapchoice-variable SwapExists autocommands can set this to the selected choice for handling an existing swapfile: 'o' Open read-only 'e' Edit anyway 'r' Recover 'd' Delete swapfile 'q' Quit 'a' Abort The value should be a single-character string. An empty value results in the user being asked, as would happen when there is no SwapExists autocommand. The default is empty.

v:swapcommand v:swapcommand swapcommand-variable Normal mode command to be executed after a file has been opened. Can be used for a SwapExists autocommand to have another Vim open the file and jump to the right place. For example, when jumping to a tag the value is ":tag tagname\r". For ":edit +cmd file" the value is ":cmd\r".

v:swapname v:swapname swapname-variable Name of the swapfile found. Only valid during SwapExists event. Read-only.

v:t_blob v:t_blob t_blob-variable v:t_TYPE Value of Blob type. Read-only. See: type()

v:t_bool v:t_bool t_bool-variable Value of Boolean type. Read-only. See: type()

v:t_dict v:t_dict t_dict-variable Value of Dictionary type. Read-only. See: type()

v:t_float v:t_float t_float-variable Value of Float type. Read-only. See: type()

v:t_func v:t_func t_func-variable Value of Funcref type. Read-only. See: type()

v:t_list v:t_list t_list-variable Value of List type. Read-only. See: type()

v:t_number v:t_number t_number-variable Value of Number type. Read-only. See: type()

v:t_string v:t_string t_string-variable Value of String type. Read-only. See: type()

v:termrequest v:termrequest termrequest-variable The value of the most recent OSC, DCS or APC control sequence sent from a process running in the embedded terminal. This can be read in a TermRequest event handler to respond to queries from embedded applications.

v:termresponse v:termresponse termresponse-variable The most recent OSC, DCS, APC, or recognized CSI (DA1, kitty multiple-cursors) control sequence received by Nvim from the host-terminal. Can be read in a TermResponse event handler after querying the terminal.

v:testing v:testing testing-variable Must be set before using test_garbagecollect_now().

v:this_session v:this_session this_session-variable Full filename of the last loaded or saved session file. Empty when no session file has been saved. See :mksession. Modifiable (can be set).

v:throwpoint v:throwpoint throwpoint-variable The point where the exception most recently caught and not finished was thrown. Not set when commands are typed. See also v:exception, v:stacktrace, and throw-variables. Example:

try
  throw "oops"
catch /.*/
  echo "Exception from" v:throwpoint
endtry

Output: "Exception from test.vim, line 2"

v:true v:true true-variable Special value used to put "true" in JSON and msgpack. See json_encode(). This value is converted to "v:true" when used as a String (e.g. in expr5 with string concatenation operator) and to one when used as a Number (e.g. in expr5 or expr7 when used with numeric operators). Read-only.

v:useractive v:useractive useractive-variable user-idle Timestamp (nanoseconds since UNIX epoch) indicating the most recent user activity, i.e. when a key is received from a UI (TUI input or nvim_input()).

Initialized to 0 (no user activity since startup). Read-only.

v:val v:val val-variable Value of the current item of a List or Dictionary. Only valid while evaluating the expression used with map() and filter(). Read-only.

v:version v:version version-variable Vim version number: major version times 100 plus minor version. Vim 5.0 is 500, Vim 5.1 is 501. Read-only. Use has() to check the Nvim (not Vim) version:

:if has("nvim-0.2.1")

v:versionlong v:versionlong versionlong-variable Like v:version, but also including the patchlevel in the last four digits. Version 8.1 with patch 123 has value 8010123. This can be used like this:

if v:versionlong >= 8010123

However, if there are gaps in the list of patches included this will not work well. This can happen if a recent patch was included into an older version, e.g. for a security fix. Use the has() function to make sure the patch is actually included.

v:vim_did_enter v:vim_did_enter vim_did_enter-variable 0 during startup, 1 just before VimEnter. See also v:vim_did_init, which is set earlier. Read-only.

v:vim_did_init v:vim_did_init vim_did_init-variable 0 during initialization, 1 after sourcing the user vimrc, just before load-plugins. See also v:vim_did_enter, which is set later. Read-only.

v:virtnum v:virtnum virtnum-variable Virtual line number for the 'statuscolumn' expression. Negative when drawing the status column for virtual lines, zero when drawing an actual buffer line, and positive when drawing the wrapped part of a buffer line. Read-only.

v:warningmsg v:warningmsg warningmsg-variable Last given warning message. Modifiable (can be set).

v:windowid v:windowid windowid-variable Application-specific window "handle" which may be set by any attached UI. Defaults to zero. Note: For Nvim windows use winnr() or win_getid(), see window-ID.