mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-08-30 02:51:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge #36322 docs

Browse Source
This commit is contained in:
Justin M. Keyes
2025-11-15 22:11:57 -08:00
committed by GitHub
parent 30634f63e2 f01c212e37
commit 39e27d64ad
24 changed files with 429 additions and 386 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
runtime/doc/autocmd.txt
View File

@@ -382,9 +382,10 @@ CmdUndefined When a user command is used but it isn't
always define the user command and have it
invoke an autoloaded function. See |autoload|.
*CmdlineChanged*
CmdlineChanged After a change was made to the text inside
command line. Be careful not to mess up the
command line, it may cause Vim to lock up.
CmdlineChanged After EVERY change inside command line. Also
triggered during mappings! Use |<Cmd>| instead
of ":" in mappings, to avoid that.
<afile> expands to the |cmdline-char|.
*CmdlineEnter*
CmdlineEnter After entering the command-line (including

16
runtime/doc/dev_arch.txt
View File

@@ -144,19 +144,17 @@ asynchronous events, which can include:
Nvim implements this functionality by entering another event loop while
waiting for characters, so instead of: >py
def state_enter(state_callback, data):
def state_enter(on_state, data):
do
key = readkey() # read a key from the user
while state_callback(data, key) # invoke the callback for the current state
<
key = readkey() # Read a key from the user
while on_state(data, key) # Invoke callback for the current state
The Nvim program loop is more like: >py
the Nvim program loop is more like: >py
def state_enter(state_callback, data):
def state_enter(on_state, data):
do
event = read_next_event() # read an event from the operating system
while state_callback(data, event) # invoke the callback for the current state
<
event = read_next_event() # Read an event from the OS
while on_state(data, event) # Invoke callback for current state
where `event` is something the operating system delivers to us, including (but
not limited to) user input. The `read_next_event()` part is internally

2
runtime/doc/dev_test.txt
View File

@@ -33,7 +33,7 @@ Tests are broadly divided into unit tests (`test/unit/`), functional tests
opposed to Lua). They are essentially "integration" tests, they test the
full system. But they are fast.
You can learn the [Lua concepts 15 minutes](https://learnxinyminutes.com/docs/lua/),
You can learn [Lua concepts 15 minutes](https://learnxinyminutes.com/docs/lua/),
see also |lua-guide|. Use any existing test as a template to start writing new
tests, or see |dev-quickstart|.

9
runtime/doc/dev_tools.txt
View File

@@ -93,6 +93,8 @@ TUI INSPECT
Use the Ghostty https://ghostty.org/ inspector tool to observe and query the
output and events from any terminal application such as Nvim.
From the Ghostty inspector you can click the "Terminal IO" tab to get a trace.
TERMINFO LOGGING
At 'verbose' level 3, Nvim logs its internal terminfo state, so you can see
@@ -139,9 +141,10 @@ region is repainted internally. To also highlight excess internal redraws, use >
TUI TRACE
In the rare case that you want to collect a trace of terminal output, the
ancient `script` command is still the "state of the art". The libvterm
`vterm-dump` utility formats the result for human-readability.
From the Ghostty inspector you can click the "Terminal IO" tab to get a trace.
Alternatively, the ancient `script` command is the "state of the art". The
libvterm `vterm-dump` utility formats the result for human-readability.
Record a Nvim terminal session and format it with `vterm-dump`: >sh

1
runtime/doc/faq.txt
View File

@@ -120,7 +120,6 @@ manage the cursor style:
Alternatively, consider setting the desired cursor shape in your shell (e.g.
with PROMPT_COMMAND in bash).
<
------------------------------------------------------------------------------
CURSOR SHAPE DOESN'T CHANGE IN TMUX

243
runtime/doc/help.txt
View File

@@ -1,179 +1,142 @@
*help.txt* Nvim
NVIM - help
k
Move around: Use the cursor keys, or "h" to go left, h l
"j" to go down, "k" to go up, "l" to go right. j
Close this window: Use ":q<Enter>".
Get out of Vim: Use ":qa!<Enter>" (careful, all changes are lost!).
Jump to a subject: Position the cursor on a tag (e.g. |bars|) and hit CTRL-].
With the mouse: Double-click the left mouse button on a tag, e.g. |bars|.
Jump back: Type CTRL-O. Repeat to go further back.
Get specific help: It is possible to go directly to whatever you want help
on, by giving an argument to the |:help| command.
Prepend something to specify the context: *help-context*
WHAT PREPEND EXAMPLE ~
Normal mode command :help x
Visual mode command v_ :help v_u
Insert mode command i_ :help i_<Esc>
Command-line command : :help :quit
Command-line editing c_ :help c_<Del>
Vim command argument - :help -r
Option ' :help 'textwidth'
Regular expression / :help /[
See |help-summary| for more contexts and an explanation.
See |notation| for an explanation of the help syntax.
Search for help: Type ":help word", then hit CTRL-D to see matching
help entries for "word".
Or use ":helpgrep word". |:helpgrep|
Getting started: Do the Vim tutor, a 30-minute interactive course for the
basic commands, see |vimtutor|.
Read the user manual from start to end: |usr_01.txt|
Vim stands for Vi IMproved. Most of Vim was made by Bram Moolenaar, but only
through the help of many others. See |credits|.
==============================================================================
NVIM DOCUMENTATION
Nvim documentation
If you are new to Nvim, see |nvim-intro|. (To go to a help link, move the
cursor to it and hit CTRL-], or ctrl-click with mouse. Try it here: |bars|.)
------------------------------------------------------------------------------
ABOUT NVIM *reference_toc* *doc-file-list* *Q_ct*
About Nvim *reference_toc* *Q_ct*
|news| News since the previous release
|nvim| Transitioning from Vim
|vim-differences| Nvim compared to Vim
|faq| Frequently Asked Questions
|user-manual| User manual: How to accomplish editing tasks.
|quickref| Overview of common commands
|tutor| 30-minute interactive course for beginners
|copying| About copyrights
|Kuwasha| Helping poor children in Uganda
|sponsor| Sponsor Vim development, become a registered Vim user
|www| Vim on the World Wide Web
|bugs| Where to send bug reports
|support| Supported platforms
- |news| News since the previous release
- |nvim| Getting start with Nvim
- |tutor| 30-minute interactive course for beginners
- |vim-differences| Nvim compared to Vim
- |faq| Frequently Asked Questions
- |tips| Various tips
- |bugs| Where to send bug reports
- |support| Supported platforms
- |copying| About copyrights
------------------------------------------------------------------------------
GENERAL
Usage
|intro| Introduction to Vim; notation used in help files
|helphelp| Using the :help files
|index| Index of all commands
|tips| Various tips on using Vim
|message.txt| (Error) messages and explanations
|uganda.txt| Vim distribution and what to do with your money
- |helphelp| Using the `:help` files
- |intro| Introduction to Vim
- |quickref| Overview of common commands
- |index| Index of all commands
- |user-manual| User manual: How to accomplish editing tasks.
- |message.txt| (Error) messages and explanations
- |Kuwasha| Helping poor children in Uganda
------------------------------------------------------------------------------
BASIC EDITING
Basic editing
|starting| Starting Vim, Vim command arguments, initialisation
|edit-files| Editing and writing files
|motion.txt| Commands for moving around
|scrolling| Scrolling the text in the window
|insert.txt| Insert and Replace mode
|change.txt| Deleting and replacing text
|undo-redo| Undo and Redo
|repeat.txt| Repeating commands, Vim scripts and debugging
|visual-mode| Using Visual mode (selecting text)
|various| Various other commands
|crash-recovery| Recovering from a crash
- |starting| Starting Vim, Vim command arguments, initialisation
- |edit-files| Editing and writing files
- |motion.txt| Commands for moving around
- |scrolling| Scrolling the text in the window
- |insert.txt| Insert and Replace mode
- |change.txt| Deleting and replacing text
- |undo-redo| Undo and Redo
- |repeat.txt| Repeating commands, Vim scripts and debugging
- |visual-mode| Using Visual mode (selecting text)
- |various| Various other commands
- |crash-recovery| Recovering from a crash
------------------------------------------------------------------------------
ADVANCED EDITING
Advanced editing
|cmdline| Command-line editing
|options| Description of all options
|pattern-searches| Vim regexp patterns and search commands
|key-mapping| Key mapping (shortcuts), abbreviations
|tags| Tags and special searches
|windows| Commands for using windows and buffers
|tabpage| Commands for using tabpages
|spell| Spell checking
|diff| Comparing files
|folding| Hide (fold) ranges of lines
|terminal| Embedded terminal emulator
- |cmdline| Command-line editing
- |options| Description of all options
- |pattern-searches| Vim regexp patterns and search commands
- |key-mapping| Key mapping (shortcuts), abbreviations
- |tags| Tags and special searches
- |windows| Commands for using windows and buffers
- |tabpage| Commands for using tabpages
- |spell| Spell checking
- |diff| Comparing files
- |folding| Hide (fold) ranges of lines
- |terminal| Embedded terminal emulator
------------------------------------------------------------------------------
API (EXTENSIBILITY/SCRIPTING/PLUGINS)
API (extensibility/scripting/plugins)
|api| Nvim API via RPC, Lua and Vimscript
|ui| Nvim UI protocol
|lua-guide| Nvim Lua guide
|lua| Lua API
|luaref| Lua reference manual
|luvref| Luv (|vim.uv|) reference manual
|autocmd| Event handlers
|job-control| Spawn and control multiple processes
|channel| Nvim asynchronous IO
|vimscript| Vimscript reference
|vimscript-functions| Vimscript functions
|remote-plugin| Nvim remote plugins
|health| Health checking
- |api| Nvim API via RPC, Lua and Vimscript
- |ui| Nvim UI protocol
- |lua-guide| Nvim Lua guide
- |lua| Lua API
- |luaref| Lua reference manual
- |luvref| Luv (|vim.uv|) reference manual
- |autocmd| Event handlers
- |job-control| Spawn and control multiple processes
- |channel| Nvim asynchronous IO
- |vimscript| Vimscript reference
- |vimscript-functions| Vimscript functions
- |remote-plugin| Nvim remote plugins
- |health| Health checking
------------------------------------------------------------------------------
PROGRAMMING LANGUAGE SUPPORT
Programming language support
|lsp| Language Server Protocol (LSP)
|diagnostic-api| Diagnostic framework
|treesitter| Incremental syntax parsing
|indent.txt| automatic indenting for C and other languages
|syntax| syntax highlighting
|filetype| Settings for specific types of files
|quickfix| Commands for a quick edit-compile-fix cycle
|ft_ada.txt| Ada filetype plugin
|ft_hare.txt| Filetype plugin for Hare
|ft_ps1.txt| PowerShell filetype plugin
|ft_raku.txt| Raku filetype plugin
|ft_rust.txt| Rust filetype plugin
|ft_sql.txt| SQL filetype plugin
- |lsp| Language Server Protocol (LSP)
- |diagnostic-api| Diagnostic framework
- |treesitter| Incremental syntax parsing
- |indent.txt| automatic indenting for C and other languages
- |syntax| syntax highlighting
- |filetype| Settings for specific types of files
- |quickfix| Commands for a quick edit-compile-fix cycle
- |ft_ada.txt| Ada filetype plugin
- |ft_hare.txt| Filetype plugin for Hare
- |ft_ps1.txt| PowerShell filetype plugin
- |ft_raku.txt| Raku filetype plugin
- |ft_rust.txt| Rust filetype plugin
- |ft_sql.txt| SQL filetype plugin
------------------------------------------------------------------------------
UI
|tui| Builtin UI
|gui| External (graphical) UIs
|signs| Signs displayed as window decorations (the "gutter")
- |tui| Builtin UI
- |gui| External (graphical) UIs
- |signs| Signs displayed as window decorations (the "gutter")
------------------------------------------------------------------------------
LANGUAGE SUPPORT
Multilingual support
|digraph| List of available digraphs
|mbyte.txt| Multibyte text support
|mlang.txt| Non-English language support
|rileft.txt| Right-to-left editing mode
|l10n-arabic.txt| Arabic language support and editing
|l10n-hebrew.txt| Hebrew language support and editing
|l10n-russian.txt| Russian language support and editing
|l10n-vietnamese.txt| Vietnamese language support and editing
- |digraph| List of available digraphs
- |mbyte.txt| Multibyte text support
- |mlang.txt| Non-English language support
- |rileft.txt| Right-to-left editing mode
- |l10n-arabic.txt| Arabic language support and editing
- |l10n-hebrew.txt| Hebrew language support and editing
- |l10n-russian.txt| Russian language support and editing
- |l10n-vietnamese.txt| Vietnamese language support and editing
------------------------------------------------------------------------------
INTEROP
Interop
|provider| Builtin remote plugin hosts
|if_perl| Perl interface
|if_pyth| Python interface
|if_ruby| Ruby interface
- |provider| Builtin remote plugin hosts
- |if_perl| Perl interface
- |if_pyth| Python interface
- |if_ruby| Ruby interface
------------------------------------------------------------------------------
VERSIONS
Versions
|deprecated| Deprecated features that will be removed
|vi-differences| Differences between Vim and Vi
- |deprecated| Deprecated features that will be removed
- |vi-differences| Differences between Vim and Vi
------------------------------------------------------------------------------
DEVELOPING NVIM
Developing nvim
|dev| Development of Nvim
|dev-arch| Internal architecture, modules, data structures
|dev-style| Development style guidelines
|dev-theme| Design guidelines (colorschemes etc.)
|dev-tools| Tools and techniques for developing Nvim
|dev-vimpatch| Merging patches from Vim
- |dev| Development of Nvim
- |dev-arch| Internal architecture, modules, data structures
- |dev-style| Development style guidelines
- |dev-test| Writing and running tests
- |dev-theme| Design guidelines (colorschemes etc.)
- |dev-tools| Tools and techniques for developing Nvim
- |dev-vimpatch| Merging patches from Vim
Standard plugins ~
@@ -189,7 +152,7 @@ Now that you've jumped here with CTRL-] or a double mouse click, you can use
CTRL-T, CTRL-O, g<RightMouse>, or <C-RightMouse> to go back to where you were.
Note that tags are within | characters, but when highlighting is enabled these
characters are hidden. That makes it easier to read a command.
characters are hidden (for aesthetics).
You can use CTRL-] on any word (even if it is not within "|") and Nvim will
try to find help for it. Especially for options in single quotes, e.g.

142
runtime/doc/helphelp.txt
View File

@@ -9,7 +9,143 @@ Help on help files *helphelp*
Type |gO| to see the table of contents.
==============================================================================
1. Help commands *online-help*
Help tag conventions *help-context*
Get specific help: It is possible to go directly to whatever you want help
on, by giving an argument to the |:help| command. Prepend something to specify
the context: >
WHAT PREPEND EXAMPLE
Normal mode command :help x
Visual mode command v_ :help v_u
Insert mode command i_ :help i_<Esc>
Command-line command : :help :quit
Command-line editing c_ :help c_<Del>
Vim command argument - :help -r
Option ' :help 'textwidth'
Regular expression / :help /[
See |help-summary| for more contexts and an explanation.
See |notation| for an explanation of the help syntax.
SEARCH FOR HELP
Type ":help word", then hit CTRL-D to see matching help entries for "word". Or
use ":helpgrep word". |:helpgrep|
==============================================================================
Notation *notation*
When syntax highlighting is used to read this, text that is not typed
literally is often highlighted with the Special group. These are items in [],
{} and <>, and CTRL-X.
Note that Vim uses all possible characters in commands. Sometimes the [], {}
and <> are part of what you type, the context should make this clear.
- [] Characters in square brackets are optional.
*count* *[count]*
- [count] An optional number that may precede the command to multiply
or iterate the command. If no number is given, a count of one
is used, unless otherwise noted. Note that in this manual the
[count] is not mentioned in the description of the command,
but only in the explanation. This was done to make the
commands easier to look up. If the 'showcmd' option is on,
the (partially) entered count is shown at the bottom of the
window. You can use <Del> to erase the last digit (|N<Del>|).
*[quotex]*
- ["x] An optional register designation where text can be stored.
See |registers|. The x is a single character between 'a' and
'z' or 'A' and 'Z' or '"', and in some cases (with the put
command) between '0' and '9', '%', '#', or others. The
uppercase and lowercase letter designate the same register,
but the lowercase letter is used to overwrite the previous
register contents, while the uppercase letter is used to
append to the previous register contents. Without the ""x" or
with """" the stored text is put into the unnamed register.
*{}*
- {} Curly braces denote parts of the command which must appear,
but which can take a number of different values. The
differences between Vim and Vi are also given in curly braces
(this will be clear from the context).
*{char1-char2}*
- {char1-char2} A single character from the range char1 to char2. For
example: {a-z} is a lowercase letter. Multiple ranges may be
concatenated. For example, {a-zA-Z0-9} is any alphanumeric
character.
*{motion}* *movement*
- {motion} A command that moves the cursor. These are explained in
|motion.txt|.
- Examples:
- `w` to start of next word
- `b` to begin of current word
- `4j` four lines down
- `/The<CR>` to next occurrence of "The"
- This is used after an |operator| command to move over the
text that is to be operated upon.
- If the motion includes a count and the operator also has
a count, the two counts are multiplied. For example:
"2d3w" deletes six words.
- The motion can be backwards, e.g. "db" to delete to the
start of the word.
- The motion can also be a mouse click. The mouse is not
supported in every terminal though.
- The ":omap" command can be used to map characters while an
operator is pending.
- Ex commands can be used to move the cursor. This can be
used to call a function that does some complicated motion.
The motion is always charwise exclusive, no matter what
":" command is used. This means it's impossible to
include the last character of a line without the line
break (unless 'virtualedit' is set). If the Ex command
changes the text before where the operator starts or jumps
to another buffer the result is unpredictable. It is
possible to change the text further down. Jumping to
another buffer is possible if the current buffer is not
unloaded.
*{Visual}*
- {Visual} A selected text area. It is started with the "v", "V", or
CTRL-V command, then any cursor movement command can be used
to change the end of the selected text.
This is used before an |operator| command to highlight the
text that is to be operated upon.
See |Visual-mode|.
*<character>*
- <character> A special character from the table below, optionally with
modifiers, or a single ASCII character with modifiers.
*'character'*
- 'c' A single ASCII character.
*CTRL-{char}*
- CTRL-{char} {char} typed as a control character; that is, typing {char}
while holding the CTRL key down. The case of {char} is
ignored; thus CTRL-A and CTRL-a are equivalent. But in
some terminals and environments, using the SHIFT key will
produce a distinct code (e.g. CTRL-SHIFT-a); in these
environments using the SHIFT key will not trigger commands
such as CTRL-A.
*'option'*
- 'option' An option, or parameter, that can be set to a value, is
enclosed in single quotes. See |options|.
*quotecommandquote*
- "command" A reference to a command that you can type is enclosed in
double quotes.
- `command` New style command, this distinguishes it from other quoted
text and strings.
==============================================================================
Help commands *online-help*
*help* *<Help>* *:h* *:help* *<F1>* *i_<F1>* *i_<Help>*
<Help> or
@@ -240,7 +376,7 @@ file. The files in $VIMRUNTIME/doc are skipped.
==============================================================================
2. Translated help files *help-translated*
Translated help files *help-translated*
It is possible to add translated help files, next to the original English help
files. Vim will search for all help in "doc" directories in 'runtimepath'.
@@ -311,7 +447,7 @@ Hints for translators:
languages in the specified directory.
==============================================================================
3. Writing help files *help-writing*
Writing help files *help-writing*
For ease of use, a Vim help file for a plugin should follow the format of the
standard Vim help files, except for the first line. If you are writing a new

111
runtime/doc/intro.txt
View File

@@ -122,117 +122,8 @@ memory however you may see fit.
- Say Farewell: https://github.com/vim/vim/discussions/12737
==============================================================================
Notation *notation*
Keycodes *key-notation* *key-codes* *keycodes*
When syntax highlighting is used to read this, text that is not typed
literally is often highlighted with the Special group. These are items in [],
{} and <>, and CTRL-X.
Note that Vim uses all possible characters in commands. Sometimes the [], {}
and <> are part of what you type, the context should make this clear.
- [] Characters in square brackets are optional.
*count* *[count]*
- [count] An optional number that may precede the command to multiply
or iterate the command. If no number is given, a count of one
is used, unless otherwise noted. Note that in this manual the
[count] is not mentioned in the description of the command,
but only in the explanation. This was done to make the
commands easier to look up. If the 'showcmd' option is on,
the (partially) entered count is shown at the bottom of the
window. You can use <Del> to erase the last digit (|N<Del>|).
*[quotex]*
- ["x] An optional register designation where text can be stored.
See |registers|. The x is a single character between 'a' and
'z' or 'A' and 'Z' or '"', and in some cases (with the put
command) between '0' and '9', '%', '#', or others. The
uppercase and lowercase letter designate the same register,
but the lowercase letter is used to overwrite the previous
register contents, while the uppercase letter is used to
append to the previous register contents. Without the ""x" or
with """" the stored text is put into the unnamed register.
*{}*
- {} Curly braces denote parts of the command which must appear,
but which can take a number of different values. The
differences between Vim and Vi are also given in curly braces
(this will be clear from the context).
*{char1-char2}*
- {char1-char2} A single character from the range char1 to char2. For
example: {a-z} is a lowercase letter. Multiple ranges may be
concatenated. For example, {a-zA-Z0-9} is any alphanumeric
character.
*{motion}* *movement*
- {motion} A command that moves the cursor. These are explained in
|motion.txt|.
- Examples:
- `w` to start of next word
- `b` to begin of current word
- `4j` four lines down
- `/The<CR>` to next occurrence of "The"
- This is used after an |operator| command to move over the
text that is to be operated upon.
- If the motion includes a count and the operator also has
a count, the two counts are multiplied. For example:
"2d3w" deletes six words.
- The motion can be backwards, e.g. "db" to delete to the
start of the word.
- The motion can also be a mouse click. The mouse is not
supported in every terminal though.
- The ":omap" command can be used to map characters while an
operator is pending.
- Ex commands can be used to move the cursor. This can be
used to call a function that does some complicated motion.
The motion is always charwise exclusive, no matter what
":" command is used. This means it's impossible to
include the last character of a line without the line
break (unless 'virtualedit' is set). If the Ex command
changes the text before where the operator starts or jumps
to another buffer the result is unpredictable. It is
possible to change the text further down. Jumping to
another buffer is possible if the current buffer is not
unloaded.
*{Visual}*
- {Visual} A selected text area. It is started with the "v", "V", or
CTRL-V command, then any cursor movement command can be used
to change the end of the selected text.
This is used before an |operator| command to highlight the
text that is to be operated upon.
See |Visual-mode|.
*<character>*
- <character> A special character from the table below, optionally with
modifiers, or a single ASCII character with modifiers.
*'character'*
- 'c' A single ASCII character.
*CTRL-{char}*
- CTRL-{char} {char} typed as a control character; that is, typing {char}
while holding the CTRL key down. The case of {char} is
ignored; thus CTRL-A and CTRL-a are equivalent. But in
some terminals and environments, using the SHIFT key will
produce a distinct code (e.g. CTRL-SHIFT-a); in these
environments using the SHIFT key will not trigger commands
such as CTRL-A.
*'option'*
- 'option' An option, or parameter, that can be set to a value, is
enclosed in single quotes. See |options|.
*quotecommandquote*
- "command" A reference to a command that you can type is enclosed in
double quotes.
- `command` New style command, this distinguishes it from other quoted
text and strings.
*key-notation* *key-codes* *keycodes*
These names for keys are used in the documentation. They can also be used
with the ":map" command.

32
runtime/doc/lsp.txt
View File

@@ -73,20 +73,21 @@ listed below, if (1) the language server supports the functionality and (2)
the options are empty or were set by the builtin runtime (ftplugin) files. The
options are not restored when the LSP client is stopped or detached.
GLOBAL DEFAULTS
*gra* *gri* *grn* *grr* *grt* *i_CTRL-S* *v_an* *v_in*
GLOBAL DEFAULTS *gra* *gri* *grn* *grr* *grt* *i_CTRL-S* *v_an* *v_in*
These GLOBAL keymaps are created unconditionally when Nvim starts:
- "gra" is mapped in Normal and Visual mode to |vim.lsp.buf.code_action()|
- "gri" is mapped in Normal mode to |vim.lsp.buf.implementation()|
- "grn" is mapped in Normal mode to |vim.lsp.buf.rename()|
- "grr" is mapped in Normal mode to |vim.lsp.buf.references()|
- "grt" is mapped in Normal mode to |vim.lsp.buf.type_definition()|
- "gO" is mapped in Normal mode to |vim.lsp.buf.document_symbol()|
- CTRL-S is mapped in Insert mode to |vim.lsp.buf.signature_help()|
- "an" and "in" are mapped in Visual mode to outer and inner incremental
- "gra" (Normal and Visual mode) is mapped to |vim.lsp.buf.code_action()|
- "gri" is mapped to |vim.lsp.buf.implementation()|
- "grn" is mapped to |vim.lsp.buf.rename()|
- "grr" is mapped to |vim.lsp.buf.references()|
- "grt" is mapped to |vim.lsp.buf.type_definition()|
- "gO" is mapped to |vim.lsp.buf.document_symbol()|
- CTRL-S (Insert mode) is mapped to |vim.lsp.buf.signature_help()|
- "an" and "in" (Visual mode) are mapped to outer and inner incremental
selections, respectively, using |vim.lsp.buf.selection_range()|
BUFFER-LOCAL DEFAULTS
- 'omnifunc' is set to |vim.lsp.omnifunc()|, use |i_CTRL-X_CTRL-O| to trigger
completion.
- 'tagfunc' is set to |vim.lsp.tagfunc()|. This enables features like
@@ -101,6 +102,7 @@ BUFFER-LOCAL DEFAULTS
- To opt out call `vim.lsp.document_color.enable(false, args.buf)` on |LspAttach|.
DISABLING DEFAULTS *lsp-defaults-disable*
You can remove GLOBAL keymaps at any time using |vim.keymap.del()| or
|:unmap|. See also |gr-default|.
@@ -130,7 +132,7 @@ Use |vim.lsp.config()| to define or modify LSP configurations, and
|vim.lsp.start()| which allows you to share and merge configs (provided by
Nvim, plugins, and your local config).
*lsp-new-config*
NEW CONFIG *lsp-new-config*
To create a new config you can either use `vim.lsp.config()` or create
a `lsp/<config-name>.lua` file.
@@ -155,7 +157,7 @@ EXAMPLE: DEFINE A CONFIG AS A FILE ~
:lua vim.lsp.enable('foo')
5. Run `:checkhealth vim.lsp`, check "Enabled Configurations". 🌈
*lsp-config-merge*
HOW CONFIGS ARE MERGED *lsp-config-merge*
When an LSP client starts, it resolves its configuration by merging the
following sources (merge semantics defined by |vim.tbl_deep_extend()| with
"force" behavior), in order of increasing priority:
@@ -166,6 +168,7 @@ following sources (merge semantics defined by |vim.tbl_deep_extend()| with
3. Configurations defined anywhere else.
Example: given the following configs... >lua
-- Defined in init.lua
vim.lsp.config('*', {
capabilities = {
@@ -177,20 +180,19 @@ Example: given the following configs... >lua
},
root_markers = { '.git' },
})
-- Defined in <rtp>/lsp/clangd.lua
return {
cmd = { 'clangd' },
root_markers = { '.clangd', 'compile_commands.json' },
filetypes = { 'c', 'cpp' },
}
-- Defined in init.lua
vim.lsp.config('clangd', {
filetypes = { 'c' },
})
<
...the merged result is: >lua
{
-- From the clangd configuration in <rtp>/lsp/clangd.lua
cmd = { 'clangd' },
@@ -213,7 +215,7 @@ Example: given the following configs... >lua
}
}
<
*lsp-attach*
CONFIGURE ON ATTACH *lsp-attach*
To use LSP features beyond those provided by Nvim (see |lsp-buf|), you can set
keymaps and options on |Client:on_attach()| or |LspAttach|. Not all language
servers provide the same capabilities; check `supports_method()` in your

35
runtime/doc/lua.txt
View File

@@ -2410,15 +2410,13 @@ vim.filetype.match({args}) *vim.filetype.match()*
Mutually exclusive with {buf}.
Return (multiple): ~
(`string?`) If a match was found, the matched filetype.
(`function?`) A function that modifies buffer state when called (for
example, to set some filetype specific buffer variables). The function
accepts a buffer number as its only argument.
(`boolean?`) Return true if a match was found by falling back to a
generic configuration file (i.e., ".conf"). If true, the filetype
should be set with `:setf FALLBACK conf`, which enables a later
|:setf| command to override the filetype. See `:help setf` for more
information.
(`string?`) The matched filetype, if any.
(`function?`) A function `fun(buf: integer)` that modifies buffer
state when called (for example, to set some filetype specific buffer
variables).
(`boolean?`) true if a match was found by falling back to a generic
filetype (i.e., ".conf"), which indicates the filetype should be set
with `:setf FALLBACK conf`. See |:setfiletype|.
==============================================================================
@@ -2434,6 +2432,13 @@ Example: >lua
end
<
*vim.fs.read()*
You can use |readblob()| to get a file's contents without explicitly opening/closing it.
Example: >lua
vim.print(vim.fn.readblob('.git/config'))
<
vim.fs.abspath({path}) *vim.fs.abspath()*
Convert path to an absolute path. A tilde (~) character at the beginning
@@ -3438,6 +3443,18 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()*
end, { expr = true })
-- Map "[%%" to a <Plug> mapping:
vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')
-- Use `getregionpos(getpos('v'))` to get the "current visual selection":
vim.keymap.set('x', 'M', function()
local region = vim.fn.getregionpos(vim.fn.getpos('v'), vim.fn.getpos('.'), {
type = 'v',
exclusive = false,
eol = false,
})
local line1 = region[1][1][2]
local line2 = region[#region][1][2]
vim.print({ line1, line2 })
end)
<
Parameters: ~

9
runtime/doc/map.txt
View File

@@ -326,9 +326,8 @@ be seen as a special key.
*<Cmd>* *:map-cmd*
The <Cmd> pseudokey begins a "command mapping", which executes the command
directly without changing modes. Where you might use ":...<CR>" in the
{rhs} of a mapping, you can instead use "<Cmd>...<CR>".
Example: >
directly without changing modes. Where you might use ":…<CR>" in the {rhs} of
a mapping, you can instead use "<Cmd>…<CR>". Example: >
noremap x <Cmd>echo mode(1)<CR>
<
This is more flexible than `:<C-U>` in Visual and Operator-pending mode, or
@@ -348,7 +347,7 @@ Note:
|CmdlineEnter| and |CmdlineLeave| events. This helps performance.
- For the same reason, |keycodes| like <C-R><C-W> are interpreted as plain,
unmapped keys.
- The command is not echo'ed, no need for <silent>.
- The command is not echo'd, no need for <silent>.
- The {rhs} is not subject to abbreviations nor to other mappings, even if the
mapping is recursive.
- In Visual mode you can use `line('v')` and `col('v')` to get one end of the
@@ -357,7 +356,7 @@ Note:
*E1255* *E1136*
<Cmd> commands must terminate, that is, they must be followed by <CR> in the
{rhs} of the mapping definition. |Command-line| mode is never entered. To use
a literal <CR> in the {rhs}, use |<lt>|.
a literal "<" in the {rhs}, use |<lt>|.
1.3 MAPPING AND MODES *:map-modes*

4
runtime/doc/news.txt
View File

@@ -71,8 +71,8 @@ EDITOR
- |i_CTRL-R| inserts named/clipboard registers (A-Z,a-z,0-9+) literally, like
pasting instead of like user input. Improves performance, avoids broken
formatting. To get the old behavior you can use `<C-R>=@x`.
- Buffer names now follow RFC3986 for detecting a scheme, meaning
"svn+ssh", "ed2k", and "iris.xpc" are now treated as URI schemes
- Buffer name URI scheme parsing more closely follows RFC3986, so for example
"svn+ssh:", "ed2k:", and "iris.xpc:" are recognized as URI schemes.
EVENTS

49
runtime/doc/vimfn.txt
View File

@@ -3931,33 +3931,30 @@ getpid() *getpid()*
(`integer`)
getpos({expr}) *getpos()*
Get the position for String {expr}.
The accepted values for {expr} are:
. The cursor position.
$ The last line in the current buffer.
Gets a position, where {expr} is one of:
. Cursor position.
$ Last line in the current buffer.
'x Position of mark x (if the mark is not set, 0 is
returned for all values).
w0 First line visible in current window (one if the
display isn't updated, e.g. in silent Ex mode).
w$ Last line visible in current window (this is one
less than "w0" if no lines are visible).
v When not in Visual mode, returns the cursor
position. In Visual mode, returns the other end
of the Visual area. A good way to think about
this is that in Visual mode "v" and "." complement
each other. While "." refers to the cursor
position, "v" refers to where |v_o| would move the
cursor. As a result, you can use "v" and "."
together to work on all of a selection in
characterwise Visual mode. If the cursor is at
the end of a characterwise Visual area, "v" refers
to the start of the same Visual area. And if the
cursor is at the start of a characterwise Visual
area, "v" refers to the end of the same Visual
area. "v" differs from |'<| and |'>| in that it's
updated right away.
Note that a mark in another file can be used. The line number
then applies to another buffer.
v End of the current Visual selection (unlike |'<|
|'>| which give the previous, not current, Visual
selection), or the cursor position if not in Visual
mode.
To get the current selected region: >vim
let region = getregionpos(getpos('v'), getpos('.'))
<
Explanation: in Visual mode "v" and "." complement each
other. While "." refers to the cursor position, "v"
refers to where |v_o| would move the cursor. So you can
use "v" and "." together to get the selected region.
Note that if a mark in another file is used, the line number
applies to that buffer.
The result is a |List| with four numbers:
[bufnum, lnum, col, off]
@@ -4249,8 +4246,14 @@ getregionpos({pos1}, {pos2} [, {opts}]) *getregionpos()*
the offset of the character's first cell not included in the
selection, otherwise all its cells are included.
Apart from the options supported by |getregion()|, {opts} also
supports the following:
To get the current visual selection: >vim
let region = getregionpos(getpos('v'), getpos('.'))
<
The {opts} Dict supports the following items:
type See |getregion()|.
exclusive See |getregion()|.
eol If |TRUE|, indicate positions beyond
the end of a line with "col" values

49
runtime/lua/vim/_meta/vimfn.lua generated
View File

@@ -3530,33 +3530,30 @@ function vim.fn.getmousepos() end
--- @return integer
function vim.fn.getpid() end
--- Get the position for String {expr}.
--- The accepted values for {expr} are:
--- . The cursor position.
--- $ The last line in the current buffer.
--- Gets a position, where {expr} is one of:
--- . Cursor position.
--- $ Last line in the current buffer.
--- 'x Position of mark x (if the mark is not set, 0 is
--- returned for all values).
--- w0 First line visible in current window (one if the
--- display isn't updated, e.g. in silent Ex mode).
--- w$ Last line visible in current window (this is one
--- less than "w0" if no lines are visible).
--- v When not in Visual mode, returns the cursor
--- position. In Visual mode, returns the other end
--- of the Visual area. A good way to think about
--- this is that in Visual mode "v" and "." complement
--- each other. While "." refers to the cursor
--- position, "v" refers to where |v_o| would move the
--- cursor. As a result, you can use "v" and "."
--- together to work on all of a selection in
--- characterwise Visual mode. If the cursor is at
--- the end of a characterwise Visual area, "v" refers
--- to the start of the same Visual area. And if the
--- cursor is at the start of a characterwise Visual
--- area, "v" refers to the end of the same Visual
--- area. "v" differs from |'<| and |'>| in that it's
--- updated right away.
--- Note that a mark in another file can be used. The line number
--- then applies to another buffer.
--- v End of the current Visual selection (unlike |'<|
--- |'>| which give the previous, not current, Visual
--- selection), or the cursor position if not in Visual
--- mode.
---
--- To get the current selected region: >vim
--- let region = getregionpos(getpos('v'), getpos('.'))
--- <
--- Explanation: in Visual mode "v" and "." complement each
--- other. While "." refers to the cursor position, "v"
--- refers to where |v_o| would move the cursor. So you can
--- use "v" and "." together to get the selected region.
---
--- Note that if a mark in another file is used, the line number
--- applies to that buffer.
---
--- The result is a |List| with four numbers:
--- [bufnum, lnum, col, off]
@@ -3839,8 +3836,14 @@ function vim.fn.getregion(pos1, pos2, opts) end
--- the offset of the character's first cell not included in the
--- selection, otherwise all its cells are included.
---
--- Apart from the options supported by |getregion()|, {opts} also
--- supports the following:
--- To get the current visual selection: >vim
--- let region = getregionpos(getpos('v'), getpos('.'))
--- <
--- The {opts} Dict supports the following items:
---
--- type See |getregion()|.
---
--- exclusive See |getregion()|.
---
--- eol If |TRUE|, indicate positions beyond
--- the end of a line with "col" values

14
runtime/lua/vim/filetype.lua
View File

@@ -3101,14 +3101,12 @@ end
---
---@param args vim.filetype.match.args Table specifying which matching strategy to use.
--- Accepted keys are:
---@return string|nil # If a match was found, the matched filetype.
---@return function|nil # A function that modifies buffer state when called (for example, to set some
--- filetype specific buffer variables). The function accepts a buffer number as
--- its only argument.
---@return boolean|nil # Return true if a match was found by falling back to a generic configuration
--- file (i.e., ".conf"). If true, the filetype should be set with
--- `:setf FALLBACK conf`, which enables a later |:setf| command to override the
--- filetype. See `:help setf` for more information.
---@return string|nil # The matched filetype, if any.
---@return function|nil # A function `fun(buf: integer)` that modifies buffer state when called (for
--- example, to set some filetype specific buffer variables).
---@return boolean|nil # true if a match was found by falling back to a generic filetype
--- (i.e., ".conf"), which indicates the filetype should be set with
--- `:setf FALLBACK conf`. See |:setfiletype|.
function M.match(args)
vim.validate('arg', args, 'table')

9
runtime/lua/vim/fs.lua
View File

@@ -9,6 +9,15 @@
--- vim.print('file exists')
--- end
--- <
---
--- *vim.fs.read()*
--- You can use |readblob()| to get a file's contents without explicitly opening/closing it.
---
--- Example:
---
--- >lua
--- vim.print(vim.fn.readblob('.git/config'))
--- <
local uv = vim.uv

12
runtime/lua/vim/keymap.lua
View File

@@ -30,6 +30,18 @@ local keymap = {}
--- end, { expr = true })
--- -- Map "[%%" to a <Plug> mapping:
--- vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')
---
--- -- Use `getregionpos(getpos('v'))` to get the "current visual selection":
--- vim.keymap.set('x', 'M', function()
--- local region = vim.fn.getregionpos(vim.fn.getpos('v'), vim.fn.getpos('.'), {
--- type = 'v',
--- exclusive = false,
--- eol = false,
--- })
--- local line1 = region[1][1][2]
--- local line2 = region[#region][1][2]
--- vim.print({ line1, line2 })
--- end)
--- ```
---
---@param mode string|string[] Mode "short-name" (see |nvim_set_keymap()|), or a list thereof.

1
src/gen/gen_help_html.lua
View File

@@ -69,6 +69,7 @@ local new_layout = {
['dev_theme.txt'] = true,
['dev_tools.txt'] = true,
['dev_vimpatch.txt'] = true,
['help.txt'] = true,
['faq.txt'] = true,
['gui.txt'] = true,
['intro.txt'] = true,

49
src/nvim/eval.lua
View File

@@ -4410,33 +4410,30 @@ M.funcs = {
args = 1,
base = 1,
desc = [=[
Get the position for String {expr}.
The accepted values for {expr} are:
. The cursor position.
$ The last line in the current buffer.
Gets a position, where {expr} is one of:
. Cursor position.
$ Last line in the current buffer.
'x Position of mark x (if the mark is not set, 0 is
returned for all values).
w0 First line visible in current window (one if the
display isn't updated, e.g. in silent Ex mode).
w$ Last line visible in current window (this is one
less than "w0" if no lines are visible).
v When not in Visual mode, returns the cursor
position. In Visual mode, returns the other end
of the Visual area. A good way to think about
this is that in Visual mode "v" and "." complement
each other. While "." refers to the cursor
position, "v" refers to where |v_o| would move the
cursor. As a result, you can use "v" and "."
together to work on all of a selection in
characterwise Visual mode. If the cursor is at
the end of a characterwise Visual area, "v" refers
to the start of the same Visual area. And if the
cursor is at the start of a characterwise Visual
area, "v" refers to the end of the same Visual
area. "v" differs from |'<| and |'>| in that it's
updated right away.
Note that a mark in another file can be used. The line number
then applies to another buffer.
v End of the current Visual selection (unlike |'<|
|'>| which give the previous, not current, Visual
selection), or the cursor position if not in Visual
mode.
To get the current selected region: >vim
let region = getregionpos(getpos('v'), getpos('.'))
<
Explanation: in Visual mode "v" and "." complement each
other. While "." refers to the cursor position, "v"
refers to where |v_o| would move the cursor. So you can
use "v" and "." together to get the selected region.
Note that if a mark in another file is used, the line number
applies to that buffer.
The result is a |List| with four numbers:
[bufnum, lnum, col, off]
@@ -4746,8 +4743,14 @@ M.funcs = {
the offset of the character's first cell not included in the
selection, otherwise all its cells are included.
Apart from the options supported by |getregion()|, {opts} also
supports the following:
To get the current visual selection: >vim
let region = getregionpos(getpos('v'), getpos('.'))
<
The {opts} Dict supports the following items:
type See |getregion()|.
exclusive See |getregion()|.
eol If |TRUE|, indicate positions beyond
the end of a line with "col" values

2
src/nvim/mark.c
View File

@@ -1153,7 +1153,7 @@ void ex_changes(exarg_T *eap)
} \
}
// don't delete the line, just put at first deleted line
// "NO DELete": don't delete the line, just put at first deleted line.
#define ONE_ADJUST_NODEL(add) \
{ \
lp = add; \

3
test/functional/testnvim.lua
View File

@@ -1014,6 +1014,9 @@ function M.add_builddir_to_rtp()
end
--- Create folder with non existing parents
---
--- TODO(justinmk): lift this and `t.mkdir()` into vim.fs.
---
--- @param path string
--- @return boolean?
function M.mkdir_p(path)

2
test/old/testdir/test_normal.vim
View File

@@ -1941,7 +1941,7 @@ func Test_normal25_tag()
" Testing for CTRL-] g CTRL-] g]
" CTRL-W g] CTRL-W CTRL-] CTRL-W g CTRL-]
h
help helphelp
" Test for CTRL-]
call search('\<x\>$')
exe "norm! \<c-]>"

8
test/old/testdir/test_visual.vim
View File

@@ -2610,12 +2610,12 @@ endfunc
func Test_getregion_invalid_buf()
new
help
call cursor(5, 7)
help index
call cursor(7, 6)
norm! mA
call cursor(5, 18)
call cursor(7, 18)
norm! mB
call assert_equal(['Move around:'], getregion(getpos("'A"), getpos("'B")))
call assert_equal(['file contains'], getregion(getpos("'A"), getpos("'B")))
" close the help window
q
call assert_fails("call getregion(getpos(\"'A\"), getpos(\"'B\"))", 'E681:')

6
test/old/testdir/test_window_cmd.vim
View File

@@ -599,11 +599,12 @@ func Test_window_jump_tag()
help
/Kuwasha
call assert_match('^|Kuwasha|', getline('.'))
call assert_match('^- |Kuwasha|', getline('.'))
call assert_equal(2, winnr('$'))
norm! fK
2wincmd }
call assert_equal(3, winnr('$'))
call assert_match('^|Kuwasha|', getline('.'))
call assert_match('^- |Kuwasha|', getline('.'))
wincmd k
call assert_match('\*Kuwasha\*', getline('.'))
call assert_equal(2, winheight(0))
@@ -612,6 +613,7 @@ func Test_window_jump_tag()
set previewheight=4
help
/bugs
norm! fb
wincmd }
wincmd k
call assert_match('\*bugs\*', getline('.'))