Nvim :help
pages, generated
from source
using the tree-sitter-vimdoc parser.
.
. Repeat last change, with count replaced with [count].
Also repeat a yank command, when the 'y' flag is
included in 'cpoptions'. Does not repeat a
command-line command.@:
@: Repeat last command-line [count] times.:g
:global
E148
:[range]g[lobal]/{pattern}/[cmd]
Execute the Ex command [cmd] (default ":p") on the
lines within [range] where {pattern}
matches.{pattern}
does NOT match.:g/^Obsolete/d _Using the underscore after
:d
avoids clobbering registers or the clipboard.
This also makes it faster.{pattern}
, you can use any other
single byte character, but not an alphabetic character, '\', '"', '|' or '!'.
This is useful if you want to include a '/' in the search pattern or
replacement string.E147
When the command is used recursively, it only works on one line. Giving a
range is then not allowed. This is useful to find all lines that match a
pattern and do not match another pattern::g/found/v/notfound/{cmd}This first finds all lines containing "found", but only executes
{cmd}
when
there is no match for "notfound".:normal
command::g/pat/normal {commands}Make sure that
{commands}
ends with a whole command, otherwise Vim will wait
for you to type the rest of the command for each match. The screen will not
have been updated, so you don't know what you are doing. See :normal.CTRL-C
twice.q
recording
q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"}
(uppercase to append). The 'q' command is disabled
while executing a register, and it doesn't work inside
a mapping and :normal.@
@{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+}
[count]
times. Note that register '%' (name of the current
file) and '#' (name of the alternate file) cannot be
used.
The register is executed like a mapping, that means
that the difference between 'wildchar' and 'wildcharm'
applies, and undo might not be synced in the same way.
For "@=" you are prompted to enter an expression. The
result of the expression is then executed.
See also @:.v_@-default
{Visual}
@{0-9a-z".=*+} In linewise Visual mode, execute the contents of the
{Visual}
@@ register for each selected line.
See visual-repeat, default-mappings.Q
Q Repeat the last recorded register [count] times.
See reg_recorded().v_Q-default
{Visual}
Q In linewise Visual mode, repeat the last recorded
register for each selected line.
See visual-repeat, default-mappings.:@
:[addr]@{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+}
as an Ex
command. First set cursor at line [addr] (default is
current line). When the last line in the register does
not have a <CR>
it will be added automatically when
the 'e' flag is present in 'cpoptions'.
For ":@=" the last used expression is used. The
result of evaluating the expression is executed as an
Ex command.
Mappings are not recognized in these commands.
When the line-continuation character (\) is present
at the beginning of a line in a linewise register,
then it is combined with the previous line. This is
useful for yanking and executing parts of a Vim
script.:@:
:[addr]@: Repeat last command-line. First set cursor at line
[addr] (default is current line).:@@
:[addr]@@ Repeat the previous :@{register}. First set cursor at
line [addr] (default is current line).:so
:source
load-vim-script
:[range]so[urce] [file] Runs Ex-commands or Lua code (".lua" files) from
[file].
If no [file], the current buffer is used and treated
as Lua code if 'filetype' is "lua" or its filename
ends with ".lua".
Triggers the SourcePre autocommand.
:source!
:[range]so[urce]! {file}
Runs Normal-mode commands from {file}
. When used
after :global, :argdo, :windo, :bufdo, in
a loop or when another command follows the display
won't be updated while executing the commands.:ru
:runtime
:ru[ntime][!] [where] {file}
..
Sources Ex commands or Lua code (".lua" files) read
from {file}
(a relative path) in each directory given
by 'runtimepath' and/or 'packpath'.
Ignores non-existing files.:runtime syntax/c.vim :runtime syntax/c.lua
{file}
arguments. Each {file}
is searched for in the first
directory from 'runtimepath', then in the second
directory, etc.{file}
contains wildcards it is expanded to all
matching files. Example::runtime! plugin/**/*.{vim,lua}
:runtime plugin/**/*.{vim,lua}
{file}
pattern, if two .vim
and .lua
file
names match and differ only in extension, the .vim
file is sourced first.:pa
:packadd
E919
:pa[ckadd][!] {name}
Search for an optional plugin directory in 'packpath'
and source any plugin files found. The directory must
match:
The directory is added to 'runtimepath' if it wasn't
there yet.
If the directory pack/*/opt/{name}/after exists it is
added at the end of 'runtimepath'.{name}
is the directory name, not the name
of the .vim file. All the files matching the pattern
and
will be sourced. This allows for using subdirectories
below "plugin", just like with plugins in
'runtimepath'.syntax enable
or filetype on
command in your vimrc, or automatically during
initialization), and the package was found in
"pack/*/opt/{name}", this command will also look
for "{name}/ftdetect/*.vim" files.:packl
:packloadall
:packl[oadall][!] Load all packages in the "start" directory under each
entry in 'packpath'.:packloadall
a second time will have no effect.
When the optional ! is added this command will load
packages even when done before.:packloadall
in the vimrc
file, the 'runtimepath' option is updated, and later
all plugins in 'runtimepath' will be loaded, which
means they are loaded again. Plugins are expected to
handle that.:scripte
:scriptencoding
E167
Specify the character encoding used in the script.
The following lines will be converted from [encoding]
to the value of the 'encoding' option, if they are
different. Examples:scriptencoding iso-8859-5 scriptencoding cp932
scriptencoding euc-jp ... lines to be converted ... scriptencoding ... not converted ...
:scr
:scriptnames
:scr[iptnames] List all sourced script names, in the order they were
first sourced. The number is used for the script ID
<SID>.
Also see getscriptinfo()
.{scriptId}
:script
Edit script {scriptId}
. Although ":scriptnames name"
works, using ":script name" is recommended.
When the current buffer can't be abandoned and the !
is not present, the command fails.:fini
:finish
E168
:fini[sh] Stop sourcing a script. Can only be used in a Vim
script file. This is a quick way to skip the rest of
the file. If it is used after a :try but before the
matching :finally (if present), the commands
following the ":finally" up to the matching :endtry
are executed first. This process applies to all
nested ":try"s in the script. The outermost ":endtry"
then stops sourcing the script.<Enter>
yourself. But if you ':source!' a file with the line ":!ls" in it,
the next characters from that file are read until a <CR>
is found. You will
not have to type <CR>
yourself, unless ":!ls" was the last line in the file.:source <sfile>:h/other.vimrcIn script files terminal-dependent key codes are represented by terminal-independent two character codes. This means that they can be used in the same way on different kinds of terminals. The first character of a key code is 0x80 or 128, shown on the screen as "~@". The second one can be found in the list key-notation. Any of these codes can also be entered with
CTRL-V
followed by the three digit decimal code.:source_crnl
W15
Windows: Files that are read with ":source" normally have <CR>
<NL>
<EOL>
s.
These always work. If you are using a file with <NL>
<EOL>
s (for example, a
file made on Unix), this will be recognized if 'fileformats' is not empty and
the first line does not end in a <CR>
. This fails if the first line has
something like ":map <F1>
:help^M", where "^M" is a <CR>
. If the first line
ends in a <CR>
, but following ones don't, you will get an error message,
because the <CR>
from the first lines will be lost.<NL>
. These
always work. If you are using a file with <CR>
<NL>
<EOL>
s (for example, a
file made on MS-Windows), all lines will have a trailing <CR>
. This may cause
problems for some commands (e.g., mappings). There is no automatic <EOL>
detection, because it's common to start with a line that defines a mapping
that ends in a <CR>
, which will confuse the automaton.line-continuation
Long lines in a ":source"d Ex command script file can be split by inserting
a line continuation symbol "\" (backslash) at the start of the next line.
There can be white space before the backslash, which is ignored.:set comments=sr:/*,mb:*,el:*/, \://, \b:#, \:%, \n:>, \fb:-are interpreted as if they were given in one line: :set comments=sr:/*,mb:*,el:*/,://,b:#,:%,n:>,fb:-
:syn match Comment \ "very long regexp" \ keependThere is a problem with the ":append" and ":insert" commands:
:1append \asdf .The backslash is seen as a line-continuation symbol, thus this results in the command:
:1appendasdf .To avoid this, add the 'C' flag to the 'cpoptions' option:
:set cpo+=C :1append \asdf . :set cpo-=CNote that when the commands are inside a function, you need to add the 'C' flag when defining the function, it is not relevant when executing it.
:set cpo+=C :function Foo() :1append \asdf . :endfunction :set cpo-=C
line-continuation-comment
To add a comment in between the lines start with '"\ '
. Notice the space
after the backslash. Example:let array = [ "\ first entry comment \ 'first', "\ second entry comment \ 'second', \ ]Rationale: Most programs work with a trailing backslash to indicate line continuation. Using this in Vim would cause incompatibility with Vi. For example for this Vi mapping:
:map xx asdf\
'"\ '
comes closest, even
though it may look a bit weird. Requiring the space after the
backslash is to make it very unlikely this is a normal comment line.runtime-search-path
Nvim searches for :runtime files in:
1. all paths in 'runtimepath'
2. all "pack/*/start/*" dirs" List all runtime dirs and packages with Lua paths. :echo nvim_get_runtime_file("lua/", v:true)
pack-add
To load an optional plugin from a pack use the :packadd
command::packadd foodebugThis searches for "pack/*/opt/foodebug" in 'packpath' and will find ~/.local/share/nvim/site/pack/foo/opt/foodebug/plugin/debugger.vim and source it.
:packadd! foodebugThe extra "!" is so that the plugin isn't loaded if Nvim was started with --noplugin.
:colorscheme
, are found below
"pack/*/start" and "pack/*/opt", you could put them anywhere. We recommend
you put them below "pack/*/opt", for example
"~/.config/nvim/pack/mycolors/opt/dark/colors/very_dark.vim".:packadd
. E.g. depending on the compiler
version:if foo_compiler_version > 34 packadd foo_new else packadd foo_old endifThe "after" directory is most likely not useful in a package. It's not disallowed though.
:packadd
.mkdir ~/.local/share/nvim/site/pack cd ~/.local/share/nvim/site/pack git clone https://github.com/you/foobar.git myfoobarHere "myfoobar" is a name that the user can choose, the only condition is that it differs from other packages.
:packadd! fooextraYou could add this packadd command in one of your plugins, to be executed when the optional plugin is needed.
:helptags
command to generate the doc/tags file. Including this
generated file in the package means that the user can drop the package in the
pack directory and the help command works right away. Don't forget to re-run
the command after changing the plugin help::helptags path/start/foobar/doc :helptags path/opt/fooextra/doc
packload-two-steps
Suppose you have two plugins that depend on the same functionality. You can
put the common functionality in an autoload directory, so that it will be
found automatically. Your package would have these files:call foolib#getit()
call foolib#getit()
func foolib#getit()This works, because start packages will be searched for autoload files, when sourcing the plugins.
vim -D file.txt
:debug
2. Run a command with ":debug" prepended. Debugging will only be done while
this command executes. Useful for debugging a specific script or user
function. And for scripts and functions used by autocommands. Example::debug edit test.txt.gz3. Set a breakpoint in a sourced file or user function. You could do this in the command line:
vim -c "breakadd file */explorer.vim" .
echo idxWhen inside a user function, this will print the value of the local variable "idx". Prepend "g:" to get the value of a global variable:
echo g:idxAll commands are executed in the context of the current function or script. You can also set options, for example setting or resetting 'verbose' will show what happens, but you might want to set it just before executing the lines you are interested in:
:set verbose=20Commands that require updating the screen should be avoided, because their effect won't be noticed until after leaving debug mode. For example:
:helpwon't be very helpful.
>cont
cont Continue execution until the next breakpoint is hit.
>quit
quit Abort execution. This is like using CTRL-C
, some
things might still be executed, doesn't abort
everything. Still stops at the next breakpoint.
>next
next Execute the command and come back to debug mode when
it's finished. This steps over user function calls
and sourced files.
>step
step Execute the command and come back to debug mode for
the next command. This steps into called user
functions and sourced files.
>interrupt
interrupt This is like using CTRL-C
, but unlike ">quit" comes
back to debug mode for the next command that is
executed. Useful for testing :finally and :catch
on interrupt exceptions.
>finish
finish Finish the current script or user function and come
back to debug mode for the command after the one that
sourced or called it.
>bt
>backtrace
>where
backtrace Show the call stacktrace for current debugging session.
bt
where
>frame
frame N Goes to N backtrace level. + and - signs make movement
relative. E.g., ":frame +3" goes three frames up.
>up
up Goes one level up from call stacktrace.
>down
down Goes one level down from call stacktrace.<CR>
will repeat the previous one. When doing another command, this
is reset (because it's not clear what you want to repeat).
:breaka
:breakadd
:breaka[dd] func [lnum] {name}
Set a breakpoint in a function. Example::breakadd func Explore
{name}
Set a breakpoint in a sourced file. Example::breakadd file 43 init.vim:breaka[dd] here Set a breakpoint in the current line of the current file. Like doing:
:breakadd file <cursor-line> <current-file>
{expression}
Sets a breakpoint, that will break whenever the {expression}
evaluates to a different value. Example::breakadd expr g:lnum
:debug-name
{name}
is a pattern that is matched with the file or function name. The
pattern is like what is used for autocommands. There must be a full match (as
if the pattern starts with "^" and ends in "$"). A "*" matches any sequence
of characters. 'ignorecase' is not used, but "\c" can be used in the pattern
to ignore case /\c. Don't include the () for the function name!breakadd file explorer.vimmatches "explorer.vim" in the current directory.
breakadd file *explorer.vimmatches ".../plugin/explorer.vim", ".../plugin/iexplorer.vim", etc.
breakadd file */explorer.vimmatches ".../plugin/explorer.vim" and "explorer.vim" in any other directory.
:breakd
:breakdel
E161
:breakd[el] {nr}
Delete breakpoint {nr}
. Use :breaklist to see the number of
each breakpoint.{name}
Delete a breakpoint in a function.{name}
Delete a breakpoint in a sourced file.{name}
must be exactly the same as what was typed for the ":breakadd"
command. "explorer", "*explorer.vim" and "*explorer*" are different.:debugg
:debuggreedy
:debugg[reedy]
Read debug mode commands from the normal input stream, instead
of getting them directly from the user. Only useful for test
scripts. Example:echo 'q^Mq' | vim -e -s -c debuggreedy -c 'breakadd file script.vim' -S script.vim:0debugg[reedy] Undo ":debuggreedy": get debug mode commands directly from the user, don't use typeahead for debug commands.
:profile start /tmp/one_script_profile :profile file one_script.vim :source one_script.vim :exit:prof[ile] start
{fname}
:prof
:profile
E750
Start profiling, write the output in {fname}
upon exit.
"~/" and environment variables in {fname}
will be expanded.
If {fname}
already exists it will be silently overwritten.
The variable v:profiling is set to one.{pattern}
Profile function that matches the pattern {pattern}
.
See :debug-name for how {pattern}
is used.{pattern}
Profile script file that matches the pattern {pattern}
.
See :debug-name for how {pattern}
is used.
This only profiles the script itself, not the functions
defined in it.
When the [!] is added then all functions defined in the script
will also be profiled.
Note that profiling only starts when the script is loaded
after this command. A :profile command in the script itself
won't work.:profd
:profdel
Stop profiling for the arguments specified. See :breakdel
for the arguments.:if !v:profiling : delfunc MyFunc :endif
context-types
The following Context items are supported:
"jumps" jumplist
"regs" registers
"bufs" buffer-list
"gvars" global-variables
"sfuncs" script-local functions
"funcs" global and script-local functionscontext-dict
Context objects are dictionaries with the following key-value pairs:
context-stack
An initially-empty internal Context stack is maintained by the ctx-family
functions (see ctx-functions).