*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,
    })
<
                                                                       *netrw*
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:
