commit 39e27d64ad69ac4a33c1c34915110991405af337
parent 30634f63e26da1ecfd8642eec4a53f4c220247d7
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Sat, 15 Nov 2025 22:11:57 -0800
Merge #36322 docs
Diffstat:
24 files changed, 435 insertions(+), 392 deletions(-)
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
@@ -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
diff --git a/runtime/doc/dev_arch.txt b/runtime/doc/dev_arch.txt
@@ -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
diff --git a/runtime/doc/dev_test.txt b/runtime/doc/dev_test.txt
@@ -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|.
diff --git a/runtime/doc/dev_tools.txt b/runtime/doc/dev_tools.txt
@@ -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
diff --git a/runtime/doc/faq.txt b/runtime/doc/faq.txt
@@ -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
diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt
@@ -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*
-
-|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
+About Nvim *reference_toc* *Q_ct*
+
+- |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
-
-|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
+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
------------------------------------------------------------------------------
-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
+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
------------------------------------------------------------------------------
-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 (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
------------------------------------------------------------------------------
-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
+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
------------------------------------------------------------------------------
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.
diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt
@@ -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
diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt
@@ -122,117 +122,8 @@ memory however you may see fit.
- Say Farewell: https://github.com/vim/vim/discussions/12737
==============================================================================
-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.
-
- *key-notation* *key-codes* *keycodes*
+Keycodes *key-notation* *key-codes* *keycodes*
+
These names for keys are used in the documentation. They can also be used
with the ":map" command.
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
@@ -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
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
@@ -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: ~
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
@@ -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*
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
@@ -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
diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt
@@ -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
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
@@ -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
diff --git a/runtime/lua/vim/filetype.lua b/runtime/lua/vim/filetype.lua
@@ -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')
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
@@ -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
diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua
@@ -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.
diff --git a/src/gen/gen_help_html.lua b/src/gen/gen_help_html.lua
@@ -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,
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
@@ -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
diff --git a/src/nvim/mark.c b/src/nvim/mark.c
@@ -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; \
diff --git a/test/functional/testnvim.lua b/test/functional/testnvim.lua
@@ -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)
diff --git a/test/old/testdir/test_normal.vim b/test/old/testdir/test_normal.vim
@@ -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-]>"
diff --git a/test/old/testdir/test_visual.vim b/test/old/testdir/test_visual.vim
@@ -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:')
diff --git a/test/old/testdir/test_window_cmd.vim b/test/old/testdir/test_window_cmd.vim
@@ -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('.'))
