From d7d6a6f05a536b443188ff95a45bbd46485f11fb Mon Sep 17 00:00:00 2001 From: Girish Palya Date: Mon, 8 Sep 2025 16:25:42 -0400 Subject: [PATCH] runtime(doc): Improve doc for cmdline-autocompletion - Address https://github.com/vim/vim/pull/18219#issuecomment-3264634710 - Make the cmdline-autocompletion help more user friendly closes: #18245 Signed-off-by: Girish Palya Signed-off-by: Christian Brabandt --- runtime/doc/builtin.txt | 27 +++++-------- runtime/doc/cmdline.txt | 87 +++++++++++++++++++++++++++++++++++++++-- runtime/doc/tags | 4 +- 3 files changed, 96 insertions(+), 22 deletions(-) diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index 1b15246da1..39368435ca 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -1,4 +1,4 @@ -*builtin.txt* For Vim version 9.1. Last change: 2025 Sep 06 +*builtin.txt* For Vim version 9.1. Last change: 2025 Sep 08 VIM REFERENCE MANUAL by Bram Moolenaar @@ -12407,7 +12407,6 @@ wildmenumode() *wildmenumode()* wildtrigger() *wildtrigger()* Start wildcard expansion in the command-line, using the behavior defined by the 'wildmode' and 'wildoptions' settings. - See |cmdline-completion|. This function also enables completion in search patterns such as |/|, |?|, |:s|, |:g|, |:v| and |:vimgrep|. @@ -12415,23 +12414,15 @@ wildtrigger() *wildtrigger()* Unlike pressing 'wildchar' manually, this function does not produce a beep when no matches are found and generally operates more quietly. This makes it suitable for triggering - completion automatically, such as from an |:autocmd|. + completion automatically. + + Note: After navigating command-line history, the first call to + wildtrigger() is a no-op; a second call is needed to start + expansion. This is to support history navigation in + command-line autocompletion. + + See |cmdline-autocompletion|. - *cmdline-autocompletion* - Example: To make the completion menu pop up automatically - while typing on the command line: > - autocmd CmdlineChanged [:/\?] call wildtrigger() - set wildmode=noselect:lastused,full wildoptions=pum -< - To retain normal history navigation with the up/down keys: > - cnoremap wildmenumode() ? "\\" : "\" - cnoremap wildmenumode() ? "\\" : "\" -< - To apply an option only during a search, for example to set - 'pumheight': > - autocmd CmdlineEnter [/\?] set pumheight=8 - autocmd CmdlineLeave [/\?] set pumheight& -< Return value is always 0. Return type: |Number| diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt index e5d932a9da..951532afc0 100644 --- a/runtime/doc/cmdline.txt +++ b/runtime/doc/cmdline.txt @@ -1,4 +1,4 @@ -*cmdline.txt* For Vim version 9.1. Last change: 2025 Aug 08 +*cmdline.txt* For Vim version 9.1. Last change: 2025 Sep 08 VIM REFERENCE MANUAL by Bram Moolenaar @@ -20,6 +20,7 @@ Basic command line editing is explained in chapter 20 of the user manual 5. Ex command-line flags |ex-flags| 6. Ex special characters |cmdline-special| 7. Command-line window |cmdline-window| +8. Command-line autocompletion |cmdline-autocompletion| ============================================================================== 1. Command-line editing *cmdline-editing* @@ -406,6 +407,9 @@ word before the cursor. This is available for: The number of help item matches is limited (currently to 300) to avoid a long delay when there are very many matches. +For automatic completion as you type (without pressing a key like ), +see |cmdline-autocompletion|. + These are the commands that can be used: *c_CTRL-D* @@ -479,8 +483,6 @@ When repeating 'wildchar' or CTRL-N you cycle through the matches, eventually ending up back to what was typed. If the first match is not what you wanted, you can use or CTRL-P to go straight back to what you typed. -See also |wildtrigger()|. - The 'wildmenu' option can be set to show the matches just above the command line. @@ -1340,4 +1342,83 @@ The character used for the pattern indicates the type of command-line: @ string for |input()| - text for |:insert| or |:append| +============================================================================== +8. Command-line autocompletion *cmdline-autocompletion* + +Autocompletion makes the command-line more efficient and easier to navigate by +automatically showing a popup menu of suggestions as you type, whether +searching (/ or ?) or entering commands (:). + +A basic setup is: > + autocmd CmdlineChanged [:/\?] call wildtrigger() + set wildmode=noselect:lastused,full + set wildoptions=pum + +With this configuration, suggestions appear immediately, and you can +move through them with or the arrow keys. + +To retain normal command-line history navigation with /: > + cnoremap wildmenumode() ? "\\" : "\" + cnoremap wildmenumode() ? "\\" : "\" + +Options can also be applied only for specific command-lines. For +example, to use a shorter popup menu height only during search: > + autocmd CmdlineEnter [/\?] set pumheight=8 + autocmd CmdlineLeave [/\?] set pumheight& + +EXTRAS *fuzzy-file-picker* *live-grep* + +Command-line autocompletion can also be extended for advanced uses. +For example, you can turn the native |:find| command into a fuzzy, interactive +file picker: > + + set findfunc=Find + func Find(arg, _) + if get(s:, 'filescache', []) == [] + let s:filescache = systemlist( + \ 'find . -path "*/.git" -prune -o -type f -print') + endif + return a:arg == '' ? s:filescache : matchfuzzy(s:filescache, a:arg) + endfunc + autocmd CmdlineEnter : let s:filescache = [] + +The `:Grep` command searches for lines matching a pattern and updates the +results dynamically as you type (triggered after two characters; note: needs +the `CmdlineLeavePre` autocmd from the next section): > + + command! -nargs=+ -complete=customlist,Grep + \ Grep call VisitFile() + + func s:Grep(arglead, cmdline, cursorpos) + let cmd = $'grep -REIHns "{a:arglead}" --exclude-dir=.git + \ --exclude=".*"' + return len(a:arglead) > 1 ? systemlist(cmd) : [] + endfunc + + func s:VisitFile() + let item = getqflist(#{lines: [s:selected]}).items[0] + let pos = '[0,\ item.lnum,\ item.col,\ 0]' + exe $':b +call\ setpos(".",\ {pos}) {item.bufnr}' + call setbufvar(item.bufnr, '&buflisted', 1) + endfunc + +Automatically select the first item in the completion list when leaving the +command-line, and for `:Grep`, add the typed pattern to the command-line +history: > + + autocmd CmdlineLeavePre : + \ if get(cmdcomplete_info(), 'matches', []) != [] | + \ let s:info = cmdcomplete_info() | + \ if getcmdline() =~ '^\s*fin\%[d]\s' && s:info.selected == -1 | + \ call setcmdline($'find {s:info.matches[0]}') | + \ endif | + \ if getcmdline() =~ '^\s*Grep\s' | + \ let s:selected = s:info.selected != -1 + \ ? s:info.matches[s:info.selected] : s:info.matches[0] | + \ call setcmdline(s:info.cmdline_orig) | + \ endif | + \ endif + +For autocompletion in insert mode, see |ins-autocompletion|. + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/tags b/runtime/doc/tags index c78a0d934f..b55ee476e5 100644 --- a/runtime/doc/tags +++ b/runtime/doc/tags @@ -6673,7 +6673,7 @@ cmdarg-variable eval.txt /*cmdarg-variable* cmdbang-variable eval.txt /*cmdbang-variable* cmdcomplete_info() builtin.txt /*cmdcomplete_info()* cmdline-arguments vi_diff.txt /*cmdline-arguments* -cmdline-autocompletion builtin.txt /*cmdline-autocompletion* +cmdline-autocompletion cmdline.txt /*cmdline-autocompletion* cmdline-changed version5.txt /*cmdline-changed* cmdline-completion cmdline.txt /*cmdline-completion* cmdline-editing cmdline.txt /*cmdline-editing* @@ -7680,6 +7680,7 @@ function-range-example userfunc.txt /*function-range-example* function-search-undo userfunc.txt /*function-search-undo* function_key intro.txt /*function_key* functions eval.txt /*functions* +fuzzy-file-picker cmdline.txt /*fuzzy-file-picker* fuzzy-matching pattern.txt /*fuzzy-matching* fvwm.vim syntax.txt /*fvwm.vim* fvwm2rc syntax.txt /*fvwm2rc* @@ -8829,6 +8830,7 @@ listener_remove() builtin.txt /*listener_remove()* lite.vim syntax.txt /*lite.vim* literal-Dict eval.txt /*literal-Dict* literal-string eval.txt /*literal-string* +live-grep cmdline.txt /*live-grep* lnum-variable eval.txt /*lnum-variable* load-plugins starting.txt /*load-plugins* load-vim-script repeat.txt /*load-vim-script*