Predefined variables

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

v:argvargv-variablev:argvThe command line arguments Vim was invoked with. This is alist of strings. The first item is the Vim command.Seev:progpath for the command with full path.

v:charchar-variablev:charArgument for evaluating'formatexpr' and used for the typedcharacter when using<expr> in an abbreviation:map-<expr>.It is also used by theInsertCharPre,InsertEnter,CmdlineLeave andCmdlineLeavePre events.

v:charconvert_fromcharconvert_from-variablev:charconvert_fromThe name of the character encoding of a file to be converted.Only valid while evaluating the'charconvert' option.

v:charconvert_tocharconvert_to-variablev:charconvert_toThe name of the character encoding of a file after conversion.Only valid while evaluating the'charconvert' option.

v:cmdargcmdarg-variablev:cmdargThe extra arguments ("++p", "++enc=", "++ff=") given to a fileread/write command. This is set before an autocommand eventfor a file read/write command is triggered. There is aleading space to make it possible to append this variabledirectly after the read/write command. Note: "+cmd" isn'tincluded here, because it will be executed anyway.

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

v:collatecollate-variablev:collateThe current locale setting for collation order of the runtimeenvironment. This allows Vim scripts to be aware of thecurrent locale encoding. Technical: it's the value ofLC_COLLATE. When not using a locale the value is "C".This variable can not be set directly, use the:languagecommand.Seemulti-lang.

v:completed_itemcompleted_item-variablev:completed_itemDictionary containing thecomplete-items for the mostrecently completed word afterCompleteDone. Empty if thecompletion failed, or after leaving and re-entering insertmode.Note: Plugins can modify the value to emulate the builtinCompleteDone event behavior.

v:countcount-variablev:countThe count given for the last Normal mode command. Can be usedto 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 youget 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:count1count1-variablev:count1Just like "v:count", but defaults to one when no count isused.

v:ctypectype-variablev:ctypeThe current locale setting for characters of the runtimeenvironment. This allows Vim scripts to be aware of thecurrent locale encoding. Technical: it's the value ofLC_CTYPE. When not using a locale the value is "C".This variable can not be set directly, use the:languagecommand.Seemulti-lang.

v:dyingdying-variablev:dyingNormally zero. When a deadly signal is caught it's set toone. When multiple signals are caught the number increases.Can be used in an autocommand to check if Vim didn'tterminate 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:echospaceechospace-variablev:echospaceNumber of screen cells that can be used for an:echo messagein the last screen line before causing thehit-enter-prompt.Depends on'showcmd','ruler' and'columns'. You need tocheck'cmdheight' for whether there are full-width linesavailable above the last line.

v:errmsgerrmsg-variablev:errmsgLast given error message.Modifiable (can be set).Example:

let v:errmsg = ""silent! nextif v:errmsg != ""  " ... handle error

v:errorserrors-variableassert-returnv:errorsErrors found by assert functions, such asassert_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 itemwas 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 emptylist by the assert function.

v:eventevent-variablev:eventDictionary of event data for the currentautocommand. Validonly during the event lifetime; storing or passing v:event isinvalid! Copy it instead:

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

Keys vary by event; see the documentation for the specificevent, e.g.DirChanged orTextYankPost. abort Whether the event triggered during an aborting condition (e.g.c_Esc orc_CTRL-C forCmdlineLeave). chanchannel-id changed_window Isv:true if the event fired while changing window (or tab) onDirChanged. cmdlevel Level of cmdline. cmdtype Type of cmdline,cmdline-char. col Column count of popup menu onCompleteChanged, relative to screen. complete_type Seecomplete_info_mode complete_word The selected word, or empty if completion was abandoned/discarded. completed_item Current selected item onCompleteChanged, or{} if no item selected. cwd Current working directory. height Height of popup menu onCompleteChanged inclusive Motion isinclusive, else exclusive. info Dict of arbitrary event data. operator Currentoperator. Also set for Ex commands (unlikev:operator). For example ifTextYankPost is triggered by the:yank Ex command thenv:event.operator is "y". reasonCompleteDone reason. regcontents Text stored in the register as areadfile()-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 bygetregtype(). row Row count of popup menu onCompleteChanged, relative to screen. scope Event-specific scope name. scrollbarv:true if popup menu has a scrollbar, orv:false if not. size Total number of completion items onCompleteChanged. 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 onCompleteChanged windows List of window IDs that changed onWinResized

v:exceptionexception-variablev:exceptionThe value of the exception most recently caught and notfinished. See alsov:stacktrace,v:throwpoint, andthrow-variables.Example:

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

Output: "caught oops".

v:exitingexiting-variablev:exitingExit code, orv:null before invoking theVimLeavePreandVimLeave autocmds. See:q,:x and:cquit.Example:

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

v:falsefalse-variablev:falseSpecial value used to put "false" in JSON and msgpack. Seejson_encode(). This value is converted to "v:false" when usedas a String (e.g. inexpr5 with string concatenationoperator) and to zero when used as a Number (e.g. inexpr5orexpr7 when used with numeric operators). Read-only.

v:fcs_choicefcs_choice-variablev:fcs_choiceWhat should happen after aFileChangedShell event wastriggered. Can be used in an autocommand to tell Vim what todo 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 thenVim behaves like it is empty, there is no warning message.

v:fcs_reasonfcs_reason-variablev:fcs_reasonThe reason why theFileChangedShell event was triggered.Can be used in an autocommand to decide what to do and/or whatto set v:fcs_choice to. Possible values: deleted file no longer exists conflict file contents, mode or timestamp was changed and buffer is modified changed file contents has changed mode mode of file changed time only file timestamp changed

v:fnamefname-variablev:fnameWhen evaluating'includeexpr': the file name that wasdetected. Empty otherwise.

v:fname_difffname_diff-variablev:fname_diffThe name of the diff (patch) file. Only valid whileevaluating'patchexpr'.

v:fname_infname_in-variablev:fname_inThe name of the input file. Valid while evaluating:'charconvert' file to be converted'diffexpr' original file'patchexpr' original fileAnd set to the swap file name forSwapExists.

v:fname_newfname_new-variablev:fname_newThe name of the new version of the file. Only valid whileevaluating'diffexpr'.

v:fname_outfname_out-variablev:fname_outThe name of the output file. Only valid whileevaluating:'charconvert' resulting converted file [1]'diffexpr' output of diff'patchexpr' resulting patched file[1] When doing conversion for a write command (e.g., ":wfile") it will be equal to v:fname_in. When doing conversionfor a read command (e.g., ":e file") it will be a temporaryfile and different from v:fname_in.

v:folddashesfolddashes-variablev:folddashesUsed for'foldtext': dashes representing foldlevel of a closedfold.Read-only in thesandbox.fold-foldtext

v:foldendfoldend-variablev:foldendUsed for'foldtext': last line of closed fold.Read-only in thesandbox.fold-foldtext

v:foldlevelfoldlevel-variablev:foldlevelUsed for'foldtext': foldlevel of closed fold.Read-only in thesandbox.fold-foldtext

v:foldstartfoldstart-variablev:foldstartUsed for'foldtext': first line of closed fold.Read-only in thesandbox.fold-foldtext

v:hlsearchhlsearch-variablev:hlsearchVariable that indicates whether search highlighting is on.Setting it makes sense only if'hlsearch' is enabled. Settingthis 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 afunction.function-search-undo.

v:insertmodeinsertmode-variablev:insertmodeUsed for theInsertEnter andInsertChange autocommandevents. Values: i Insert mode r Replace mode v Virtual Replace mode

v:keykey-variablev:keyKey of the current item of aDictionary. Only valid whileevaluating the expression used withmap() andfilter().Read-only.

v:langlang-variablev:langThe current locale setting for messages of the runtimeenvironment. This allows Vim scripts to be aware of thecurrent language. Technical: it's the value of LC_MESSAGES.The value is system dependent.This variable can not be set directly, use the:languagecommand.It can be different fromv:ctype when messages are desiredin a different language than what is used for characterencoding. Seemulti-lang.

v:lc_timelc_time-variablev:lc_timeThe current locale setting for time messages of the runtimeenvironment. This allows Vim scripts to be aware of thecurrent language. Technical: it's the value of LC_TIME.This variable can not be set directly, use the:languagecommand. Seemulti-lang.

v:lnumlnum-variablev:lnumLine number for the'foldexpr'fold-expr,'formatexpr','indentexpr' and'statuscolumn' expressions, tab page numberfor'guitablabel' and'guitabtooltip'. Only valid while one ofthese expressions is being evaluated. Read-only when in thesandbox.

v:lualua-variablev:luaPrefix for calling Lua functions from expressions.Seev:lua-call for more information.

v:maxcolmaxcol-variablev:maxcolMaximum line length. Depending on where it is used it can bescreen columns, characters or bytes. The value currently is2147483647 on all systems.

v:mouse_colmouse_col-variablev:mouse_colColumn number for a mouse click obtained withgetchar().This is the screen column number, like withvirtcol(). Thevalue is zero when there was no mouse button click.

v:mouse_lnummouse_lnum-variablev:mouse_lnumLine number for a mouse click obtained withgetchar().This is the text line number, not the screen line number. Thevalue is zero when there was no mouse button click.

v:mouse_winmouse_win-variablev:mouse_winWindow number for a mouse click obtained withgetchar().First window has number 1, like withwinnr(). The value iszero when there was no mouse button click.

v:mouse_winidmouse_winid-variablev:mouse_winidwindow-ID for a mouse click obtained withgetchar().The value is zero when there was no mouse button click.

v:msgpack_typesmsgpack_types-variablev:msgpack_typesDictionary containing msgpack types used bymsgpackparse()andmsgpackdump(). All types inside dictionary are fixed(not editable) empty lists. To check whether some list is oneof msgpack types, useis operator.

v:nullnull-variablev:nullSpecial value used to put "null" in JSON and NIL in msgpack.Seejson_encode(). This value is converted to "v:null" whenused as a String (e.g. inexpr5 with string concatenationoperator) and to zero when used as a Number (e.g. inexpr5orexpr7 when used with numeric operators). Read-only.In some placesv:null can be used for a List, Dict, etc.that is not set. That is slightly different than an emptyList, Dict, etc.

v:numbermaxnumbermax-variablev:numbermaxMaximum value of a number.

v:numberminnumbermin-variablev:numberminMinimum value of a number (negative).

v:numbersizenumbersize-variablev:numbersizeNumber of bits in a Number. This is normally 64, but on somesystems it may be 32.

v:oldfilesoldfiles-variablev:oldfilesList of file names that is loaded from theshada file onstartup. 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 theshada file is not used the List is empty.Also see:oldfiles andc_#<.The List can be modified, but this has no effect on what isstored in theshada file later. If you use values otherthan String this will cause trouble.

v:operatoroperator-variablev:operatorThe last operator given in Normal mode. This is a singlecharacter except for commands starting with<g> or<z>,in which case it is two characters. Best used alongsidev:prevcount andv:register. Useful if you want to cancelOperator-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, thusdon't expect it to be empty.v:operator is not set for:delete,:yank or other Excommands.Read-only.

v:option_commandoption_command-variablev:option_commandCommand used to set the option. Valid while executing anOptionSet autocommand. "setlocal":setlocal or:let l:xxx "setglobal":setglobal or:let g:xxx "set":set or:let "modeline"modeline

v:option_newoption_new-variablev:option_newNew value of the option. Valid while executing anOptionSetautocommand.

v:option_oldoption_old-variablev:option_oldOld value of the option. Valid while executing anOptionSetautocommand. Depending on the command used for setting andthe kind of option this is either the local old value or theglobal old value.

v:option_oldglobaloption_oldglobal-variablev:option_oldglobalOld global value of the option. Valid while executing anOptionSet autocommand.

v:option_oldlocaloption_oldlocal-variablev:option_oldlocalOld local value of the option. Valid while executing anOptionSet autocommand.

v:option_typeoption_type-variablev:option_typeScope of the set command. Valid while executing anOptionSet autocommand. Can be either "global" or "local"

v:prevcountprevcount-variablev:prevcountThe count given for the last but one Normal mode command.This is the v:count value of the previous command. Useful ifyou want to cancel Visual or Operator-pending mode and thenuse the count, e.g.:

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

Read-only.

v:profilingprofiling-variablev:profilingNormally zero. Set to one after using ":profile start".Seeprofiling.

v:prognameprogname-variablev:prognameThe name by which Nvim was invoked (with path removed).Read-only.

v:progpathprogpath-variablev:progpathAbsolute path to the current running Nvim.Read-only.

v:registerregister-variablev:registerThe name of the register in effect for the current normal modecommand (regardless of whether that command actually used aregister). 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 seegetreg() andsetreg()

v:relnumrelnum-variablev:relnumRelative line number for the'statuscolumn' expression.Read-only.

v:scrollstartscrollstart-variablev:scrollstartString describing the script or function that caused thescreen to scroll up. It's only set when it is empty, thus thefirst reason is remembered. It is set to "Unknown" for atyped command.This can be used to find out why your script causes thehit-enter prompt.

v:searchforwardsearchforward-variablev:searchforwardSearch direction: 1 after a forward search, 0 after abackward search. It is reset to forward when directly settingthe last search pattern, seequote/.Note that the value is restored when returning from afunction.function-search-undo.Read-write.

v:servernameservername-variablev:servernamePrimary listen-address of Nvim, the first item returned byserverlist(). Usually this is the named pipe created by Nvimatstartup or given by--listen (or the deprecated$NVIM_LISTEN_ADDRESS env var).

See alsoserverstart()serverstop().Read-only.

$NVIM
$NVIM is set to v:servername byterminal andjobstart(),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 toits 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))  endend

v:shell_errorshell_error-variablev:shell_errorResult of the last shell command. When non-zero, the lastshell 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 beexecuted. Read-only.Example:

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

v:stacktracestacktrace-variablev:stacktraceThe stack trace of the exception most recently caught andnot finished. Refer togetstacktrace() for the structure ofstack trace. See alsov:exception,v:throwpoint, andthrow-variables.

v:statusmsgstatusmsg-variablev:statusmsgLast given status message.Modifiable (can be set).

v:stderrstderr-variablev:stderrchannel-id corresponding to stderr. The value is always 2;use this variable to make your code more descriptive.Unlike stdin and stdout (seestdioopen()), stderr is alwaysopen for writing. Example:

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

v:swapchoiceswapchoice-variablev:swapchoiceSwapExists autocommands can set this to the selected choicefor handling an existing swapfile: 'o' Open read-only 'e' Edit anyway 'r' Recover 'd' Delete swapfile 'q' Quit 'a' AbortThe value should be a single-character string. An empty valueresults in the user being asked, as would happen when there isno SwapExists autocommand. The default is empty.

v:swapcommandswapcommand-variablev:swapcommandNormal mode command to be executed after a file has beenopened. Can be used for aSwapExists autocommand to haveanother Vim open the file and jump to the right place. Forexample, when jumping to a tag the value is ":tag tagname\r".For ":edit +cmd file" the value is ":cmd\r".

v:swapnameswapname-variablev:swapnameName of the swapfile found.Only valid duringSwapExists event.Read-only.

v:t_blobt_blob-variablev:t_TYPEv:t_blobValue ofBlob type. Read-only. See:type()

v:t_boolt_bool-variablev:t_boolValue ofBoolean type. Read-only. See:type()

v:t_dictt_dict-variablev:t_dictValue ofDictionary type. Read-only. See:type()

v:t_floatt_float-variablev:t_floatValue ofFloat type. Read-only. See:type()

v:t_funct_func-variablev:t_funcValue ofFuncref type. Read-only. See:type()

v:t_listt_list-variablev:t_listValue ofList type. Read-only. See:type()

v:t_numbert_number-variablev:t_numberValue ofNumber type. Read-only. See:type()

v:t_stringt_string-variablev:t_stringValue ofString type. Read-only. See:type()

v:termrequesttermrequest-variablev:termrequestThe value of the most recent OSC, DCS or APC control sequencesent from a process running in the embeddedterminal.This can be read in aTermRequest event handler to respondto queries from embedded applications.

v:termresponsetermresponse-variablev:termresponseThe value of the most recent OSC or DCS control sequencereceived by Nvim from the terminal. This can be read in aTermResponse event handler after querying the terminal usinganother escape sequence.

v:testingtesting-variablev:testingMust be set before usingtest_garbagecollect_now().

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

v:throwpointthrowpoint-variablev:throwpointThe point where the exception most recently caught and notfinished was thrown. Not set when commands are typed. Seealsov:exception,v:stacktrace, andthrow-variables.Example:

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

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

v:truetrue-variablev:trueSpecial value used to put "true" in JSON and msgpack. Seejson_encode(). This value is converted to "v:true" when usedas a String (e.g. inexpr5 with string concatenationoperator) and to one when used as a Number (e.g. inexpr5 orexpr7 when used with numeric operators). Read-only.

v:valval-variablev:valValue of the current item of aList orDictionary. Onlyvalid while evaluating the expression used withmap() andfilter(). Read-only.

v:versionversion-variablev:versionVim version number: major version times 100 plus minorversion. Vim 5.0 is 500, Vim 5.1 is 501.Read-only.Usehas() to check the Nvim (not Vim) version:

:if has("nvim-0.2.1")

v:versionlongversionlong-variablev:versionlongLike v:version, but also including the patchlevel in the lastfour 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 includedthis will not work well. This can happen if a recent patchwas included into an older version, e.g. for a security fix.Use the has() function to make sure the patch is actuallyincluded.

v:vim_did_entervim_did_enter-variablev:vim_did_enter0 during startup, 1 just beforeVimEnter.Read-only.

v:vim_did_initvim_did_init-variablev:vim_did_init0 during initialization, 1 after sourcingvimrc and justbeforeload-plugins.Read-only.

v:virtnumvirtnum-variablev:virtnumVirtual line number for the'statuscolumn' expression.Negative when drawing the status column for virtual lines, zerowhen drawing an actual buffer line, and positive when drawingthe wrapped part of a buffer line.Read-only.

v:warningmsgwarningmsg-variablev:warningmsgLast given warning message.Modifiable (can be set).

v:windowidwindowid-variablev:windowidApplication-specific window "handle" which may be set by anyattached UI. Defaults to zero.Note: For Nvimwindows usewinnr() orwin_getid(), seewindow-ID.