commit 52be3b14e37fc357d512c51e1aa8172ce6d03acb
parent 2f8fb4f28ab92d62e07d1d64a6dd89e0b6eb7253
Author: zeertzjq <zeertzjq@outlook.com>
Date: Sun, 13 Apr 2025 08:06:07 +0800
vim-patch:eded336: runtime(doc): Improve 'wildmode' setting desciption
closes: vim/vim#17100
https://github.com/vim/vim/commit/eded33621be29b9fdc51466efdc946fa8d3e756f
Co-authored-by: Girish Palya <girishji@gmail.com>
Diffstat:
3 files changed, 150 insertions(+), 120 deletions(-)
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
@@ -7103,55 +7103,65 @@ A jump table for the options with a short description can be found at |Q_op|.
*'wildmode'* *'wim'*
'wildmode' 'wim' string (default "full")
global
- Completion mode that is used for the character specified with
- 'wildchar'. It is a comma-separated list of up to four parts. Each
- part specifies what to do for each consecutive use of 'wildchar'. The
- first part specifies the behavior for the first use of 'wildchar',
- The second part for the second use, etc.
-
- Each part consists of a colon separated list consisting of the
- following possible values:
- "" Complete only the first match.
- "full" Complete the next full match. After the last match,
- the original string is used and then the first match
- again. Will also start 'wildmenu' if it is enabled.
- "longest" Complete till longest common string. If this doesn't
- result in a longer string, use the next part.
- "list" When more than one match, list all matches.
- "lastused" When completing buffer names and more than one buffer
- matches, sort buffers by time last used (other than
- the current buffer).
- "noselect" Do not pre-select first menu item and start 'wildmenu'
- if it is enabled.
- When there is only a single match, it is fully completed in all cases
- except when "noselect" is present.
-
- Examples of useful colon-separated values:
- "longest:full" Like "longest", but also start 'wildmenu' if it is
- enabled. Will not complete to the next full match.
- "list:full" When more than one match, list all matches and
- complete first match.
- "list:longest" When more than one match, list all matches and
- complete till longest common string.
- "list:lastused" When more than one buffer matches, list all matches
- and sort buffers by time last used (other than the
- current buffer).
+ Completion mode used for the character specified with 'wildchar'.
+ This option is a comma-separated list of up to four parts,
+ corresponding to the first, second, third, and fourth presses of
+ 'wildchar'. Each part is a colon-separated list of completion
+ behaviors, which are applied simultaneously during that phase.
+
+ The possible behavior values are:
+ "" Only complete (insert) the first match. No further
+ matches are cycled or listed.
+ "full" Complete the next full match. Cycles through all
+ matches, returning to the original input after the
+ last match. If 'wildmenu' is enabled, it will be
+ shown.
+ "longest" Complete to the longest common substring. If this
+ doesn't extend the input, the next 'wildmode' part is
+ used.
+ "list" If multiple matches are found, list all of them.
+ "lastused" When completing buffer names, sort them by most
+ recently used (excluding the current buffer). Only
+ applies to buffer name completion.
+ "noselect" If 'wildmenu' is enabled, show the menu but do not
+ preselect the first item.
+ If only one match exists, it is completed fully—unless "noselect" is
+ specified.
+
+ Some useful combinations of colon-separated values:
+ "longest:full" Start with the longest common string and show
+ 'wildmenu' (if enabled). Does not cycle
+ through full matches.
+ "list:full" List all matches and complete first match.
+ "list:longest" List all matches and complete till the longest
+ common prefix.
+ "list:lastused" List all matches. When completing buffers,
+ sort them by most recently used (excluding the
+ current buffer).
+ "noselect:lastused" Do not preselect the first item in 'wildmenu'
+ if it is active. When completing buffers,
+ sort them by most recently used (excluding the
+ current buffer).
Examples: >vim
set wildmode=full
-< Complete first full match, next match, etc. (the default) >vim
+< Complete full match on every press (default behavior) >vim
set wildmode=longest,full
-< Complete longest common string, then each full match >vim
+< First press: longest common substring
+ Second press: cycle through full matches >vim
set wildmode=list:full
-< List all matches and complete each full match >vim
+< First press: list all matches and complete the first one >vim
set wildmode=list,full
-< List all matches without completing, then each full match >vim
+< First press: list matches only
+ Second press: complete full matches >vim
set wildmode=longest,list
-< Complete longest common string, then list alternatives >vim
+< First press: longest common substring
+ Second press: list all matches >vim
set wildmode=noselect:full
-< Display 'wildmenu' without completing, then each full match >vim
+< Show 'wildmenu' without completing or selecting on first press
+ Cycle full matches on second press >vim
set wildmode=noselect:lastused,full
-< Same as above, but sort buffers by time last used.
+< Same as above, but buffer matches are sorted by last used
More info here: |cmdline-completion|.
*'wildoptions'* *'wop'*
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
@@ -7756,76 +7756,86 @@ vim.o.wmnu = vim.o.wildmenu
vim.go.wildmenu = vim.o.wildmenu
vim.go.wmnu = vim.go.wildmenu
---- Completion mode that is used for the character specified with
---- 'wildchar'. It is a comma-separated list of up to four parts. Each
---- part specifies what to do for each consecutive use of 'wildchar'. The
---- first part specifies the behavior for the first use of 'wildchar',
---- The second part for the second use, etc.
----
---- Each part consists of a colon separated list consisting of the
---- following possible values:
---- "" Complete only the first match.
---- "full" Complete the next full match. After the last match,
---- the original string is used and then the first match
---- again. Will also start 'wildmenu' if it is enabled.
---- "longest" Complete till longest common string. If this doesn't
---- result in a longer string, use the next part.
---- "list" When more than one match, list all matches.
---- "lastused" When completing buffer names and more than one buffer
---- matches, sort buffers by time last used (other than
---- the current buffer).
---- "noselect" Do not pre-select first menu item and start 'wildmenu'
---- if it is enabled.
---- When there is only a single match, it is fully completed in all cases
---- except when "noselect" is present.
----
---- Examples of useful colon-separated values:
---- "longest:full" Like "longest", but also start 'wildmenu' if it is
---- enabled. Will not complete to the next full match.
---- "list:full" When more than one match, list all matches and
---- complete first match.
---- "list:longest" When more than one match, list all matches and
---- complete till longest common string.
---- "list:lastused" When more than one buffer matches, list all matches
---- and sort buffers by time last used (other than the
---- current buffer).
+--- Completion mode used for the character specified with 'wildchar'.
+--- This option is a comma-separated list of up to four parts,
+--- corresponding to the first, second, third, and fourth presses of
+--- 'wildchar'. Each part is a colon-separated list of completion
+--- behaviors, which are applied simultaneously during that phase.
+---
+--- The possible behavior values are:
+--- "" Only complete (insert) the first match. No further
+--- matches are cycled or listed.
+--- "full" Complete the next full match. Cycles through all
+--- matches, returning to the original input after the
+--- last match. If 'wildmenu' is enabled, it will be
+--- shown.
+--- "longest" Complete to the longest common substring. If this
+--- doesn't extend the input, the next 'wildmode' part is
+--- used.
+--- "list" If multiple matches are found, list all of them.
+--- "lastused" When completing buffer names, sort them by most
+--- recently used (excluding the current buffer). Only
+--- applies to buffer name completion.
+--- "noselect" If 'wildmenu' is enabled, show the menu but do not
+--- preselect the first item.
+--- If only one match exists, it is completed fully—unless "noselect" is
+--- specified.
+---
+--- Some useful combinations of colon-separated values:
+--- "longest:full" Start with the longest common string and show
+--- 'wildmenu' (if enabled). Does not cycle
+--- through full matches.
+--- "list:full" List all matches and complete first match.
+--- "list:longest" List all matches and complete till the longest
+--- common prefix.
+--- "list:lastused" List all matches. When completing buffers,
+--- sort them by most recently used (excluding the
+--- current buffer).
+--- "noselect:lastused" Do not preselect the first item in 'wildmenu'
+--- if it is active. When completing buffers,
+--- sort them by most recently used (excluding the
+--- current buffer).
---
--- Examples:
---
--- ```vim
--- set wildmode=full
--- ```
---- Complete first full match, next match, etc. (the default)
+--- Complete full match on every press (default behavior)
---
--- ```vim
--- set wildmode=longest,full
--- ```
---- Complete longest common string, then each full match
+--- First press: longest common substring
+--- Second press: cycle through full matches
---
--- ```vim
--- set wildmode=list:full
--- ```
---- List all matches and complete each full match
+--- First press: list all matches and complete the first one
---
--- ```vim
--- set wildmode=list,full
--- ```
---- List all matches without completing, then each full match
+--- First press: list matches only
+--- Second press: complete full matches
---
--- ```vim
--- set wildmode=longest,list
--- ```
---- Complete longest common string, then list alternatives
+--- First press: longest common substring
+--- Second press: list all matches
---
--- ```vim
--- set wildmode=noselect:full
--- ```
---- Display 'wildmenu' without completing, then each full match
+--- Show 'wildmenu' without completing or selecting on first press
+--- Cycle full matches on second press
---
--- ```vim
--- set wildmode=noselect:lastused,full
--- ```
---- Same as above, but sort buffers by time last used.
+--- Same as above, but buffer matches are sorted by last used
--- More info here: `cmdline-completion`.
---
--- @type string
diff --git a/src/nvim/options.lua b/src/nvim/options.lua
@@ -10133,55 +10133,65 @@ local options = {
flags = true,
deny_duplicates = false,
desc = [=[
- Completion mode that is used for the character specified with
- 'wildchar'. It is a comma-separated list of up to four parts. Each
- part specifies what to do for each consecutive use of 'wildchar'. The
- first part specifies the behavior for the first use of 'wildchar',
- The second part for the second use, etc.
-
- Each part consists of a colon separated list consisting of the
- following possible values:
- "" Complete only the first match.
- "full" Complete the next full match. After the last match,
- the original string is used and then the first match
- again. Will also start 'wildmenu' if it is enabled.
- "longest" Complete till longest common string. If this doesn't
- result in a longer string, use the next part.
- "list" When more than one match, list all matches.
- "lastused" When completing buffer names and more than one buffer
- matches, sort buffers by time last used (other than
- the current buffer).
- "noselect" Do not pre-select first menu item and start 'wildmenu'
- if it is enabled.
- When there is only a single match, it is fully completed in all cases
- except when "noselect" is present.
-
- Examples of useful colon-separated values:
- "longest:full" Like "longest", but also start 'wildmenu' if it is
- enabled. Will not complete to the next full match.
- "list:full" When more than one match, list all matches and
- complete first match.
- "list:longest" When more than one match, list all matches and
- complete till longest common string.
- "list:lastused" When more than one buffer matches, list all matches
- and sort buffers by time last used (other than the
- current buffer).
+ Completion mode used for the character specified with 'wildchar'.
+ This option is a comma-separated list of up to four parts,
+ corresponding to the first, second, third, and fourth presses of
+ 'wildchar'. Each part is a colon-separated list of completion
+ behaviors, which are applied simultaneously during that phase.
+
+ The possible behavior values are:
+ "" Only complete (insert) the first match. No further
+ matches are cycled or listed.
+ "full" Complete the next full match. Cycles through all
+ matches, returning to the original input after the
+ last match. If 'wildmenu' is enabled, it will be
+ shown.
+ "longest" Complete to the longest common substring. If this
+ doesn't extend the input, the next 'wildmode' part is
+ used.
+ "list" If multiple matches are found, list all of them.
+ "lastused" When completing buffer names, sort them by most
+ recently used (excluding the current buffer). Only
+ applies to buffer name completion.
+ "noselect" If 'wildmenu' is enabled, show the menu but do not
+ preselect the first item.
+ If only one match exists, it is completed fully—unless "noselect" is
+ specified.
+
+ Some useful combinations of colon-separated values:
+ "longest:full" Start with the longest common string and show
+ 'wildmenu' (if enabled). Does not cycle
+ through full matches.
+ "list:full" List all matches and complete first match.
+ "list:longest" List all matches and complete till the longest
+ common prefix.
+ "list:lastused" List all matches. When completing buffers,
+ sort them by most recently used (excluding the
+ current buffer).
+ "noselect:lastused" Do not preselect the first item in 'wildmenu'
+ if it is active. When completing buffers,
+ sort them by most recently used (excluding the
+ current buffer).
Examples: >vim
set wildmode=full
- < Complete first full match, next match, etc. (the default) >vim
+ < Complete full match on every press (default behavior) >vim
set wildmode=longest,full
- < Complete longest common string, then each full match >vim
+ < First press: longest common substring
+ Second press: cycle through full matches >vim
set wildmode=list:full
- < List all matches and complete each full match >vim
+ < First press: list all matches and complete the first one >vim
set wildmode=list,full
- < List all matches without completing, then each full match >vim
+ < First press: list matches only
+ Second press: complete full matches >vim
set wildmode=longest,list
- < Complete longest common string, then list alternatives >vim
+ < First press: longest common substring
+ Second press: list all matches >vim
set wildmode=noselect:full
- < Display 'wildmenu' without completing, then each full match >vim
+ < Show 'wildmenu' without completing or selecting on first press
+ Cycle full matches on second press >vim
set wildmode=noselect:lastused,full
- < Same as above, but sort buffers by time last used.
+ < Same as above, but buffer matches are sorted by last used
More info here: |cmdline-completion|.
]=],
full_name = 'wildmode',
