mirror of
https://github.com/neovim/neovim.git
synced 2026-08-15 11:59:31 +00:00
0af3b9827b
Problem: Directory listing entries cannot be customized (filtered, reordered). Listings are read by a BufReadCmd, which suppresses BufReadPost, so they are the only buffers with no post-read event to hook. Solution: Introduce a post-render User autocmd `DirReadPost`, marking the dir buffer writable for the duration and before the cursor is placed, so handlers can sort or filter it with ordinary commands. Document common recipes
414 lines
17 KiB
Plaintext
414 lines
17 KiB
Plaintext
*plugins.txt* Nvim
|
|
|
|
|
|
NVIM REFERENCE MANUAL
|
|
|
|
Type |gO| to see the table of contents.
|
|
|
|
==============================================================================
|
|
Plugins and modules included with Nvim *standard-plugin*
|
|
|
|
Nvim includes various Lua and Vim plugins or modules which may provide
|
|
commands (such as :TOhtml) or modules that you can optionally require() or
|
|
:packadd. The Lua ones are not part of the |lua-stdlib|, that is, they are not
|
|
available from the global `vim` module namespace. Some of the plugins are
|
|
loaded by default while others are not loaded until requested by |:packadd|.
|
|
|
|
==============================================================================
|
|
Standard plugins *standard-plugin-list*
|
|
|
|
Help-link Loaded Short description ~
|
|
|dir| Yes Directory listing for |:edit|
|
|
|difftool| No Compares directories (and files) side-by-side
|
|
|editorconfig| Yes Detect and interpret editorconfig
|
|
|ft-shada| Yes Allows editing binary |shada| files
|
|
|man.lua| Yes View manpages in Nvim
|
|
|matchit| Yes Extended |%| matching
|
|
|matchparen| Yes Highlight matching pairs
|
|
|netrw| No Reading and writing files over a network
|
|
|zip| Yes Read-only zip archive browser
|
|
|package-cfilter| No Filtering quickfix/location list
|
|
|package-justify| No Justify text
|
|
|package-nohlsearch| No Automatically run :nohlsearch
|
|
|package-spellfile| Yes Install spellfile if missing
|
|
|package-termdebug| No Debug inside Nvim with gdb
|
|
|package-tohtml| No Convert buffer to html, syntax included
|
|
|package-undotree| No Interactive textual undotree
|
|
|pi_gzip.txt| Yes Reading and writing compressed files
|
|
|pi_msgpack.txt| No msgpack utilities
|
|
|pi_paren.txt| Yes Highlight matching parens
|
|
|pi_spec.txt| Yes Filetype plugin to work with rpm spec files
|
|
|pi_swapmouse| No Swap meaning of left and right mouse buttons
|
|
|pi_tar.txt| Yes Tar file explorer
|
|
|pi_tutor.txt| Yes Interactive tutorial
|
|
|old-zip| No Legacy zip archive explorer
|
|
|
|
==============================================================================
|
|
Builtin plugin: dir *dir*
|
|
|
|
Nvim opens a directory listing when you |:edit| a directory path, handled by
|
|
the builtin "dir" plugin. The listing is read-only, dir.lua does not provide
|
|
actions which modify the filesystem.
|
|
|
|
Each "dir" buffer is initialized as follows:
|
|
- Sets 'filetype' to "directory".
|
|
- Sets |current-directory| via |:bcd|, so |gf|, |:!| and friends work as
|
|
expected.
|
|
- Keeps |alternate-file|, so |CTRL-^| returns to the buffer you came from.
|
|
|
|
*g:loaded_nvim_dir_plugin*
|
|
To disable the built-in directory browser, set this before startup: >lua
|
|
vim.g.loaded_nvim_dir_plugin = 1
|
|
<
|
|
|
|
GLOBAL MAPPINGS *dir-mappings*
|
|
|
|
• - opens the parent directory of the current file or directory.
|
|
• {count}- is like -, but a count of 1 opens the global working directory,
|
|
and a higher count goes up that many levels.
|
|
|
|
BUFFER-LOCAL MAPPINGS *dir-buffer-mappings*
|
|
|
|
• <CR> opens the file or directory under the cursor.
|
|
• - opens the parent directory.
|
|
• R reloads the directory listing.
|
|
|
|
These keys map to <Plug>(nvim-dir-open), <Plug>(nvim-dir-up), and
|
|
<Plug>(nvim-dir-reload); map those to use different keys. Default mappings are
|
|
skipped when the target <Plug> mapping is already mapped. The default global and
|
|
directory-buffer "-" mappings are also skipped when "-" is already mapped.
|
|
|
|
*dir-config*
|
|
Directory buffers follow the global 'hidden' option by default. To delete them
|
|
after use: >vim
|
|
autocmd FileType directory setlocal bufhidden=delete
|
|
<
|
|
A discarded listing is rebuilt on the next visit, so the cursor starts at the
|
|
first entry instead of the one it was left on. "wipe" discards the buffer
|
|
itself, leaving no |alternate-file|; see 'bufhidden'.
|
|
|
|
|
|
Reshaping the listing *dir-render*
|
|
|
|
*DirReadPost*
|
|
A |User| autocommand fired after each listing is rendered, including reloads.
|
|
The buffer is writable for the duration, so a handler can sort or filter it
|
|
with ordinary commands, and the cursor is placed afterwards.
|
|
|
|
Handlers may reorder or remove lines, but each remaining line must still be an
|
|
entry name: |dir-buffer-mappings| resolve the line under the cursor against the
|
|
buffer name, so rewriting line text makes <CR> open a nonexistent path.
|
|
|
|
Sort directories last: >vim
|
|
autocmd User DirReadPost silent keeppatterns sort r /\/$/
|
|
<
|
|
Hide dot-prefixed entries: >vim
|
|
autocmd User DirReadPost silent keeppatterns g/^\./d _
|
|
<
|
|
Sort by modification time, newest first: >lua
|
|
vim.api.nvim_create_autocmd('User', {
|
|
pattern = 'DirReadPost',
|
|
callback = function(args)
|
|
local dir = vim.api.nvim_buf_get_name(args.buf)
|
|
local names = vim.api.nvim_buf_get_lines(args.buf, 0, -1, true)
|
|
local mtime = {} --- @type table<string, integer>
|
|
for _, name in ipairs(names) do
|
|
local stat = vim.uv.fs_stat(vim.fs.joinpath(dir, name))
|
|
mtime[name] = stat and stat.mtime.sec or 0
|
|
end
|
|
table.sort(names, function(a, b)
|
|
return mtime[a] > mtime[b]
|
|
end)
|
|
vim.api.nvim_buf_set_lines(args.buf, 0, -1, true, names)
|
|
end,
|
|
})
|
|
<
|
|
|
|
Replacing the directory browser *dir-disable*
|
|
|
|
To use another directory browser for the current session, delete the
|
|
`nvim.dir` autocommand group on or after |VimEnter| and handle |FileType| "directory".
|
|
This clears the built-in directory-opening autocommands. >lua
|
|
|
|
vim.api.nvim_del_augroup_by_name('nvim.dir')
|
|
vim.api.nvim_create_autocmd('FileType', {
|
|
pattern = 'directory',
|
|
callback = function(args)
|
|
require('my_browser').open(args.buf, vim.api.nvim_buf_get_name(args.buf))
|
|
end,
|
|
})
|
|
<
|
|
To enable the legacy "netrw" plugin: >vim
|
|
|
|
:packadd netrw
|
|
|
|
The plugin and its mappings remain loaded (it is a core component used by
|
|
other features such as |zip|). Define replacement keymaps explicitly, for
|
|
example: >lua
|
|
|
|
vim.keymap.set('n', '-', function()
|
|
require('my_browser').open_parent()
|
|
end)
|
|
<
|
|
|
|
==============================================================================
|
|
Builtin plugin: difftool *difftool*
|
|
|
|
:DiffTool {left} {right} *:DiffTool*
|
|
Compares two directories or files side-by-side.
|
|
Supports directory diffing, rename detection, and highlights changes
|
|
in quickfix list. Replaces the built-in `nvim -d` diff mode with this interface.
|
|
|
|
The plugin is not loaded by default; use `:packadd` to activate it: >
|
|
:packadd nvim.difftool
|
|
<
|
|
|
|
Example `git difftool -d` integration using `nvim -d` replacement: >ini
|
|
[difftool "nvim_difftool"]
|
|
cmd = nvim -c \"packadd nvim.difftool\" -d \"$LOCAL\" \"$REMOTE\"
|
|
[diff]
|
|
tool = nvim_difftool
|
|
<
|
|
|
|
|
|
open({left}, {right}, {opt}) *difftool.open()*
|
|
Diff two files or directories
|
|
|
|
Parameters: ~
|
|
• {left} (`string`)
|
|
• {right} (`string`)
|
|
• {opt} (`table?`)
|
|
• {rename.detect} (`boolean`, default: `false`) Whether to
|
|
detect renames
|
|
• {rename.similarity} (`number`, default: `0.5`) Minimum
|
|
similarity for rename detection (0 to 1)
|
|
• {rename.chunk_size} (`number`, default: `4096`) Maximum
|
|
chunk size to read from files for similarity calculation
|
|
• {ignore} (`string[]`, default: `{}`) List of file patterns
|
|
to ignore (for example: `'.git', '*.log'`)
|
|
• {method} (`'auto'|'builtin'|'diffr'`, default: `auto`) Diff
|
|
method to use
|
|
• {rename} (`table`) Controls rename detection
|
|
|
|
|
|
==============================================================================
|
|
Builtin plugin: editorconfig *editorconfig*
|
|
|
|
EditorConfig is like 'modeline' for an entire (recursive) directory. When a
|
|
file is opened, after running |ftplugin|s and |FileType| autocommands, the
|
|
EditorConfig feature searches all parent directories of that file for
|
|
`.editorconfig` files, parses them, and applies their properties. For more
|
|
information see https://editorconfig.org/.
|
|
|
|
Example `.editorconfig` file: >ini
|
|
root = true
|
|
|
|
[*]
|
|
charset = utf-8
|
|
end_of_line = lf
|
|
indent_size = 4
|
|
indent_style = space
|
|
max_line_length = 42
|
|
trim_trailing_whitespace = true
|
|
|
|
[*.{diff,md}]
|
|
trim_trailing_whitespace = false
|
|
<
|
|
|
|
*g:editorconfig* *b:editorconfig*
|
|
|
|
EditorConfig is enabled by default. To disable it, add to your config: >lua
|
|
vim.g.editorconfig = false
|
|
<
|
|
|
|
(Vimscript: `let g:editorconfig = v:false`). It can also be disabled
|
|
per-buffer by setting the |b:editorconfig| buffer-local variable to `false`.
|
|
|
|
Nvim stores the applied properties in |b:editorconfig| if it is not `false`.
|
|
|
|
*editorconfig-custom-properties*
|
|
|
|
New properties can be added by adding a new entry to the "properties" table.
|
|
The table key is a property name and the value is a callback function which
|
|
accepts the number of the buffer to be modified, the value of the property in
|
|
the `.editorconfig` file, and (optionally) a table containing all of the other
|
|
properties and their values (useful for properties which depend on other
|
|
properties). The value is always a string and must be coerced if necessary.
|
|
Example: >lua
|
|
|
|
require('editorconfig').properties.foo = function(bufnr, val, opts)
|
|
if opts.charset and opts.charset ~= "utf-8" then
|
|
error("foo can only be set when charset is utf-8", 0)
|
|
end
|
|
vim.b[bufnr].foo = val
|
|
end
|
|
<
|
|
|
|
*editorconfig-properties*
|
|
|
|
The following properties are supported by default:
|
|
|
|
|
|
charset *editorconfig.charset*
|
|
One of `"utf-8"`, `"utf-8-bom"`, `"latin1"`, `"utf-16be"`, or
|
|
`"utf-16le"`. Sets the 'fileencoding' and 'bomb' options.
|
|
|
|
end_of_line *editorconfig.end_of_line*
|
|
One of `"lf"`, `"crlf"`, or `"cr"`. These correspond to setting
|
|
'fileformat' to "unix", "dos", or "mac", respectively.
|
|
|
|
indent_size *editorconfig.indent_size*
|
|
A number indicating the size of a single indent. Alternatively, use the
|
|
value "tab" to use the value of the tab_width property. Sets the
|
|
'shiftwidth' and 'softtabstop' options. If this value is not "tab" and the
|
|
tab_width property is not set, 'tabstop' is also set to this value.
|
|
|
|
indent_style *editorconfig.indent_style*
|
|
One of `"tab"` or `"space"`. Sets the 'expandtab' option.
|
|
|
|
insert_final_newline *editorconfig.insert_final_newline*
|
|
`"true"` or `"false"` to ensure the file always has a trailing newline as
|
|
its last byte. Sets the 'fixendofline' and 'endofline' options.
|
|
|
|
max_line_length *editorconfig.max_line_length*
|
|
A number indicating the maximum length of a single line. Sets the
|
|
'textwidth' option.
|
|
|
|
root *editorconfig.root*
|
|
If "true", then stop searching for `.editorconfig` files in parent
|
|
directories. This property must be at the top-level of the `.editorconfig`
|
|
file (i.e. it must not be within a glob section).
|
|
|
|
spelling_language *editorconfig.spelling_language*
|
|
A code of the format ss or ss-TT, where ss is an ISO 639 language code and
|
|
TT is an ISO 3166 territory identifier. Sets the 'spelllang' option.
|
|
|
|
tab_width *editorconfig.tab_width*
|
|
The display size of a single tab character. Sets the 'tabstop' option.
|
|
|
|
trim_trailing_whitespace *editorconfig.trim_trailing_whitespace*
|
|
When `"true"`, trailing whitespace is automatically removed when the
|
|
buffer is written.
|
|
|
|
|
|
==============================================================================
|
|
Builtin plugin: spellfile *package-spellfile*
|
|
|
|
Asks the user to download missing spellfiles. The spellfile is written to
|
|
`stdpath('data') .. 'site/spell'` or the first writable directory in the
|
|
'runtimepath'.
|
|
|
|
The plugin can be disabled by setting `g:loaded_spellfile_plugin = 1`.
|
|
|
|
|
|
*nvim.spellfile.Opts*
|
|
A table with the following fields:
|
|
|
|
Fields: ~
|
|
• {confirm}? (`boolean`, default: `true`) Whether to ask user to
|
|
confirm download.
|
|
• {timeout_ms}? (`integer`, default: 15000) Number of milliseconds
|
|
after which the |vim.net.request()| times out.
|
|
• {url}? (`string`) The base URL from where the spellfiles are
|
|
downloaded. Uses `g:spellfile_URL` if it's set,
|
|
otherwise https://ftp.nluug.nl/pub/vim/runtime/spell.
|
|
|
|
|
|
config({opts}) *spellfile.config()*
|
|
Configure spellfile download options. For example: >lua
|
|
require('nvim.spellfile').config({ url = '...' })
|
|
<
|
|
|
|
Parameters: ~
|
|
• {opts} (`nvim.spellfile.Opts?`) When omitted or `nil`, retrieve the
|
|
current configuration. Otherwise, a configuration table.
|
|
|
|
Return: ~
|
|
(`nvim.spellfile.Opts?`) Current config if {opts} is omitted.
|
|
|
|
get({lang}) *spellfile.get()*
|
|
Download spellfiles for language {lang} if available.
|
|
|
|
Parameters: ~
|
|
• {lang} (`string`) Language code.
|
|
|
|
Return: ~
|
|
(`table?`) A table with the following fields:
|
|
• {dir} (`string`)
|
|
• {encoding} (`string`)
|
|
• {files} (`string[]`)
|
|
• {key} (`string`)
|
|
• {lang} (`string`)
|
|
|
|
|
|
==============================================================================
|
|
Builtin plugin: tohtml *package-tohtml*
|
|
|
|
:[range]TOhtml {file} *:TOhtml*
|
|
Converts the buffer shown in the current window to HTML, opens the generated
|
|
HTML in a new split window, and saves its contents to {file}. If {file} is not
|
|
given, a temporary file (created by |tempname()|) is used.
|
|
|
|
The plugin is not loaded by default; use `:packadd` to activate it: >
|
|
:packadd nvim.tohtml
|
|
<
|
|
|
|
|
|
tohtml({winid}, {opt}) *tohtml.tohtml()*
|
|
Converts the buffer shown in the window {winid} to HTML and returns the
|
|
output as a list of string.
|
|
|
|
Parameters: ~
|
|
• {winid} (`integer?`) Window to convert (defaults to current window)
|
|
• {opt} (`table?`) Optional parameters.
|
|
• {font}? (`string[]|string`, default: `guifont`) Fonts to
|
|
use.
|
|
• {number_lines}? (`boolean`, default: `false`) Show line
|
|
numbers.
|
|
• {range}? (`integer[]`, default: entire buffer) Range of
|
|
rows to use.
|
|
• {title}? (`string|false`, default: buffer name) Title tag
|
|
to set in the generated HTML code.
|
|
• {width}? (`integer`, default: 'textwidth' if non-zero or
|
|
window width otherwise) Width used for items which are
|
|
either right aligned or repeat a character infinitely.
|
|
|
|
Return: ~
|
|
(`string[]`)
|
|
|
|
|
|
==============================================================================
|
|
Builtin plugin: undotree *package-undotree*
|
|
|
|
open({opts}) *undotree.open()*
|
|
Open a window that displays a textual representation of the |undo-tree|,
|
|
or closes the window if it is already open. Can also be shown with
|
|
`:Undotree`. *:Undotree*
|
|
|
|
While in the window, moving the cursor changes the undo.
|
|
|
|
The plugin is not loaded by default; use `:packadd` to activate it: >
|
|
:packadd nvim.undotree
|
|
<
|
|
|
|
Parameters: ~
|
|
• {opts} (`table?`) A table with the following fields:
|
|
• {bufnr} (`integer?`) Buffer to draw the tree into. If
|
|
omitted, a new buffer is created.
|
|
• {command} (`string?`) Vimscript command to create the
|
|
window. Default value is "30vnew". Only used when {winid} is
|
|
nil.
|
|
• {title} (`(string|fun(bufnr:integer):string?)?`) Title of
|
|
the window. If a function, it accepts the buffer number of
|
|
the source buffer as its only argument and should return a
|
|
string.
|
|
• {winid} (`integer?`) Window id to display the tree buffer
|
|
in. If omitted, a new window is created with {command}.
|
|
|
|
Return: ~
|
|
(`boolean?`) Returns true if the window was already open, nil
|
|
otherwise
|
|
|
|
|
|
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
|