helphelp.txt ForVim version 9.2. Last change: 2026 Feb 14VIM REFERENCE MANUAL by Bram MoolenaarHelp onhelp fileshelphelp1. Help commandsonline-help2. Translatedhelp fileshelp-translated3. Writinghelp fileshelp-writing==============================================================================1. Help commandsonline-helphelp<Help>:h:help<F1>i_<F1>i_<Help><Help>or:h[elp]Openawindow and display thehelp file in read-onlymode. If thereisahelpwindow open already, usethat one. Otherwise, if the currentwindow uses thefull width of the screen orisat least 80 characterswide, thehelpwindow will appear just above thecurrent window. Otherwise the newwindowisputatthe very top.The'helplang' optionis used to selecta language, ifthe mainhelp fileis available in several languages.{subject}E149E661:h[elp]{subject}Like ":help", additionally jump to thetag{subject}.For example::help options{subject} can includewildcards suchas "*", "?" and"[a-z]"::help z?jump tohelp for any "z" command:helpz.jump to thehelp for "z."But whenatag existsitis taken literally::help:?jump tohelp for ":?"If thereis no full match for the pattern, or thereare several matches, the "best" match will be used.A sophisticated algorithmis used to decide whichmatchis better than another one. These items areconsidered in the computation:-A match with samecaseis much better thana match with different case.-A match that starts aftera non-alphanumeric characteris better thana match in the middle ofa word.-A matchat or near the beginning of thetagis better thana match further on.- The more alphanumeric characters match, the better.- The shorter the length of the match, the better.The'helplang' optionis used to selecta language, ifthe{subject}is available in several languages.To findatag ina specific language, append "@ab",where "ab"is the two-letter language code. Seehelp-translated.Note that the longer the{subject} you give, thelessmatches will be found. You can get an idea how thisall works by using commandline completion (typeCTRL-Dafter ":help subject"c_CTRL-D).If there are several matches, you can have them listedby hittingCTRL-D. Example::help cont<Ctrl-D>Instead of typing ":helpCTRL-V" to search forhelpforCTRL-V you can type::help ^VThis also works together with other characters, forexample to findhelp forCTRL-V inInsert mode::help i^VItis also possible to firstdo ":help" and thenuse ":tag{pattern}" in thehelp window. The":tnext" command can then be used to jump to othermatches, "tselect" tolist matches and choose one.:help index:tselect /.*modeWhen thereis no argument you will see matches for"help", to avoid listing all possible matches (thatwould be very slow).The number of matches displayedis limited to 300.The:help command can be followed by'|' and anothercommand, but you don't need toescape the'|' insideahelp command. So these both work::help |:help k| onlyNote thataspace before the'|'is seenas part ofthe ":help" argument.You can also use<NL> or<CR> to separate thehelpcommand froma following command. You need to typeCTRL-V first toinsert the<NL> or<CR>. Example::help so<C-V><CR>only:h[elp]![subject]Like ":help", but in non-Englishhelp files prefer tofindatag ina file with the same languageas thecurrent file. Seehelp-translated.:helpc:helpclose:helpc[lose]Close onehelp window, if thereis one.Vim will try to restore thewindow layout (includingcursor position) to the same layoutit was beforeopening thehelpwindow initially. This might causetriggering several autocommands.:helpg:helpgrep:helpg[rep]{pattern}[@xx]Search allhelp text files and makealist of linesin which{pattern} matches. Jumps to the first match.The optional [@xx]specifies that only matches in the"xx" language are to be found.You can navigate through the matches with thequickfix commands, e.g.,:cnext to jump to thenext one. Or use:cwindow to get thelist ofmatches in thequickfix window.{pattern}is usedasa Vimregexppattern.'ignorecase'is not used, add "\c" to ignore case.Example forcase sensitive search::helpgrep UgandaExample forcase ignoring search::helpgrep uganda\cExample for searching in French help::helpgrep backspace@frThepattern does not support line breaks,itmustmatch within one line. You can use:grep instead,but then you need to get thelist ofhelp files inacomplicated way.Cannot be followed by another command, everythingisusedas part of the pattern. But you can use:execute when needed.Compressedhelp files will not be searched (Fedoracompresses thehelp files).:lh:lhelpgrep:lh[elpgrep]{pattern}[@xx]Sameas ":helpgrep", except the locationlistis usedinstead of thequickfix list. If thehelpwindowisalready opened, then the locationlist for thatwindowis used. Otherwise,a newhelpwindowis opened andthe locationlist for thatwindowis set. Thelocationlist for the currentwindowis not changedthen.:exu:exusage:exu[sage]Showhelp onEx commands. Added to simulate theNvicommand.:viu:viusage:viu[sage]Showhelp onNormal mode commands. Added to simulatetheNvi command.When no argumentis given to:help the file given with the'helpfile' optionwill be opened. Otherwise the specifiedtagis searched for in all "doc/tags"files in the directories specified in the'runtimepath' option.The initial height of thehelpwindow can be set with the'helpheight' option(default 20).If you want to openhelp on{subject} in the current window, the helpcurwinoptional package can be used. Seepackage-helpcurwin.help-buffer-optionsWhen thehelp bufferis created, several localoptions are set to make surethehelp textis displayedasit was intended:'iskeyword'nearly all ASCII chars except' ','*','"' and'|''foldmethod'"manual"'tabstop'8'arabic'off'binary'off'buflisted'off'cursorbind'off'diff'off'foldenable'off'list'off'modifiable'off'number'off'relativenumber'off'rightleft'off'scrollbind'off'spell'offJump to specific subjects by using tags. This can be done in two ways:- Use the "CTRL-]" command while standing on the name ofa command or option. This only works when thetagisa keyword. "<C-Leftmouse>" and "g<LeftMouse>" work just like "CTRL-]".- use the ":ta{subject}" command. This also works with non-keyword characters.UseCTRL-T orCTRL-O to jump back.Use ":q" to close thehelp window.If there are several matches for an item you are looking for, thisis how youcan jump to each one of them:1. Openahelpwindow2. Use the ":tag" command witha slash prepended to the tag. E.g.::tag /min3. Use ":tnext" to jump to the next matching tag.Itis possible to addhelp files for plugins and other items. You don't needto change the distributedhelp files for that. Seeadd-local-help.To writea localhelp file, seewrite-local-help.Note that the title lines from the localhelp files are automagically added tothe "LOCAL ADDITIONS"section in the "help.txt"help filelocal-additions.Thisis done when viewing the file in Vim, the file itselfis not changed. Itis done by going through allhelp files and obtaining the first line of eachfile. The files in $VIMRUNTIME/doc are skipped.help-xterm-windowIf you want to have thehelp in another xterm window, you could use thiscommand::!xterm -e vim +help &:helpfind:helpf:helpf[ind]Like:help, but useadialog to enter the argument.Only for backwards compatibility. It now executes theToolBar.FindHelp menu entry instead of usinga builtindialog.{only when compiled with |+GUI_GTK|}:helpt:helptagsE150E151E152E153E154E670:helpt[ags] [++t]{dir}Generate thehelptags file(s) for directory{dir}.When{dir}is ALL then all "doc" directories in'runtimepath' will be used.All "*.txt" and "*.??x" files in the directory andsub-directories are scanned forahelptag definitionin between stars. The "*.??x" files are fortranslated docs, they generate the "tags-??" file, seehelp-translated. The generatedtags files aresorted.When there are duplicates an error messageis given.An existingtags fileis silently overwritten.The optional "++t" argument forces adding the"help-tags" tag. Thisis also done when the{dir}isequal to $VIMRUNTIME/doc.To rebuild thehelptags in the runtime directory(requires write permission there)::helptags $VIMRUNTIME/doc:HelpTochelp-TOChelp-toc-installpackage-helptocIf you want to access an interactive table of contents, from any position inthe file, you can use the helptoc plugin. Load theplugin with: packadd helptocHelpToc-mappingsThen you can use the:HelpToc command to openapopup menu.The latter supports the following normal commands:key | effect----+---------------------------------------------------------c | select nearest entry from cursor position in main bufferg | select first entryG | select last entryH | collapse one levelj | select next entryJ | same as j, and jump to corresponding line in main bufferk | select previous entryK | same as k, and jump to corresponding line in main bufferL | expand one levelp | print current entry on command-lineP | same as p but automatically, whenever selection changes | press multiple times to toggle feature on/offq | quit menus | split window, and jump to selected entryz | redraw menu with current entry at center+ | increase width of popup menu- | decrease width of popup menu? | show/hide a help window/ | search for pattern<C-D> | scroll down half a page<C-U> | scroll up half a page<PageUp> | scroll down a whole page<PageDown> | scroll up a whole page<Home> | select first entry<End> | select last entryTheplugin can also providea table of contents inbuffers of the followingfiletypes: asciidoc, html, man, markdown, tex, vim, and xhtml. In additionit also providea table of contents foraterminal buffer, which producesentries that are the past executed shell commands. To find those, by default,the followingpatternis used:^\w\+@\w\+:\f\+\$\sThisis meant to matcha default bash prompt. Ifit doesn't match yourprompt, you can change the regex with theshell_prompt key from theg:helptoc dictionary variable:let g:helptoc = {'shell_prompt': 'regex matching your shell prompt'}Tip: Afterinsertingapattern to look for with the/ command, if you press<Esc> instead of<CR>, you can then get more context for each remaining entryby pressingJ orK.Refer tohelptoc.txt for more details about helptoc, particularly aboutusingit withfiletypes other than help, and configuring its options.Note: You need to `packadd helptoc` before you can jump tohelptoc.txt.==============================================================================2. Translatedhelp fileshelp-translatedItis possible to add translatedhelp files, next to the original Englishhelpfiles. Vim will search for allhelp in "doc" directories in'runtimepath'.Thisis only available when compiled with the+multi_lang feature.At this moment translations are available for:Chinese- multiple authorsFrench- translated by David BlanchetItalian- translated by Antonio ColomboJapanese- multiple authorsPolish- translated by Mikolaj MachowskiRussian- translated by Vassily RagosinSwedish- translated by Daniel NylanderSee the Vim website to find them:http://www.vim.org/translations.phpA set of translatedhelp files consists of these files:help.abxhowto.abx...tags-ab"ab"is the two-letter language code. Thus for Italian the names are:help.itxhowto.itx...tags-itThe'helplang' option can be set to the preferred language(s). The defaultisset according to the environment. Vim will first try to finda matchingtagin the preferred language(s). Englishis used whenit cannot be found.To findatag ina specific language, append "@ab" toa tag, where "ab"is thetwo-letter language code. Example::he user-manual@it:he user-manual@enThe first one finds the Italian user manual, even when'helplang'is empty.The second one finds the English user manual, even when'helplang'is set to"it".When using command-line completion for the ":help" command, the "@en"extensionis only shown whenatag exists for multiple languages. When thetag only exists for English "@en"is omitted. When the first candidate has an"@ab" extension andit matches the first language in'helplang' "@ab"is alsoomitted.When usingCTRL-] or ":help!" ina non-Englishhelp file Vim will try tofind thetag in the same language. If not found then'helplang' will be usedto selecta language.Help filesmust use latin1 orutf-8 encoding. Vim assumes the encodingisutf-8 when finding non-ASCII characters in the first line. Thus youmusttranslate the header with "For Vim version".The same encodingmust be used for thehelp files of one language in onedirectory. You can usea different encoding for different languages and usea different encoding forhelp files of the same language but ina differentdirectory.Hints for translators:- Do not translate the tags. This makesit possible to use'helplang' to specify the preferred language. You may add newtags in your language.- When youdo not translatea part ofa file, addtags to the English version, using the "tag@en" notation.- Makea package with all the files and thetags file available for download. Users can dropit in one of the "doc" directories and start use it. Report to thedevelopment team, so they can adda link on www.vim.org.- Use the:helptags command to generate thetags files. It will find all languages in the specified directory.==============================================================================3. Writinghelp fileshelp-writingFor ease of use,a Vimhelp file foraplugin should follow the format of thestandard Vimhelp files, except for the first line. If you arewritinga newhelp file it's best to copy one of the existing files and useitasatemplate.Vimhelp files generally use 2 spaces afterasentence (since they are writtenusinga fixed-width font and that was the preferred style in the 70s/80s),like whatis described here:https://english.stackexchange.com/a/2602The first line inahelp file should have the following format:plugin_name.txt{short description of the plugin}The first fieldisahelptag where ":help plugin_name" will jump to. Theremainder of the line, aftera Tab, describes theplugin purpose ina shortway. This will show up in the "LOCAL ADDITIONS"section of the mainhelpfile. Check there thatit shows up properly:local-additions.If you want to adda version number or last modification date,putit in thesecond line, right aligned.At the bottom of thehelp file, placea Vimmodeline to set the'textwidth'and'tabstop'options and the'filetype' to "help". Never seta global optionin sucha modeline, that can have undesired consequences.STYLEIf your Vim has'modeline' enabled, Vim should follow the preferred styleautomatically when editing built-inhelp files.Vimhelp files should be formatted fora'textwidth' of 78 characters (with'conceal' enabled), so they look good ina typical 80x 24terminal window;use `:set colorcolumn=+0`asa visual guide.Use two spaces between the final dot ofasentence of the firstletter of thenext sentence. Like this.Usetab characters for aligning content, witha'tabstop' setting of 8.This also helps reduce the file size.Always use:retab after you have finished editing. Don't blindly use:retab!, always review what will be changed to avoid unwanted changes.TAGSTo defineahelp tag, place the name between asterisks("*tag-name*"). Thetag-name should be different from all the Vimhelptag names and ideallyshould begin with the name of the Vim plugin. Thetag nameis usually rightaligned ona line.When referring to an existinghelptag and to createa hot-link, place thename between twobars(|) eg.help-writing.When referring toa Vim command and to createa hot-link, place thename between two backticks, eg. inside:filetype. You will see thisishighlightedasa command, likea code block (see below).When referring toa Vim option in thehelp file, place the option name betweentwo single quotes, eg.'statusline'HIGHLIGHTINGTo definea column heading, usea tilde characterat theend of the line.This will highlight the column heading ina different color. E.g.Column headingTo separate sections inahelp file, placea series of '=' characters inalinestarting from the first column. Thesection separator lineishighlighted differently.Toquotea block of ex-commands verbatim, placea greater than (>) characterat theend of the line before the block andaless than (<) characteras thefirst non-blank ona line following the block. Any linestarting in column 1also implicitly stops the block of ex-commands before it. E.g.function Example_Func() echo "Example"endfunctionTo enablesyntax highlighting fora block of code, placea language nameannotation (e.g. "vim") aftera greater than (>) character. E.g.function Example_Func() echo "Example"endfunctiong:help_example_languagesBy default,help files only support Vimscript highlighting. If you needsyntax highlighting for other languages, add to yourvimrc::let g:help_example_languages = #{ \vim: "vim", vim9: "vim", bash: "sh" }The key represents the annotation marker name, and the valueis the'syntax'name.Note: If youdo not include "vim" in "g:help_example_languages", itssyntaxhighlighting will not be enabled. If you set "g:help_example_languages" to anempty value,syntax highlighting for embedded languages will be disabled.Furthernote: Including arbitrarysyntax languages intohelp files may notalways work perfectly, if the included'syntax'script does not account forsuch an import.help-notationThe following are highlighted differently ina Vimhelp file:-a special key name expressed either in<>notationas in<PageDown>, orasa Ctrl characteras inCTRL-X- anything between{braces}, e.g.{lhs} and{rhs}Theword "Note", "Notes" and similar automagically receive distinctivehighlighting. Sodo these:*Todosomething todo*Errorsomething wrongYou can find the details in $VIMRUNTIME/syntax/help.vimFILETYPE COMPLETIONft-help-omniTo get completion forhelptags whenwritingatag reference, you can use thei_CTRL-X_CTRL-O command.GENDER NEUTRAL LANGUAGEgender-neutralinclusionVimis for everybody, no matter race, gender or anything. For new or updatedhelp text, gender neutral languageis recommended. Some of thehelp textismany years old and thereis no need to change it. Wedo not make anyassumptions about the gender of the user, no matter how the textis phrased.The goalis that the reader understands how Vim works, the exact wordingissecondary.Many online technical style guides include sections about gender neutrallanguage. Here area few:https://developers.google.com/style/pronounshttps://techwhirl.com/gender-neutral-technical-writing/https://www.skillsyouneed.com/write/gender-neutral-language.htmlhttps://ualr.edu/writingcenter/avoid-sexist-language/Note: gender neutral language does not require using singular "they". vim:tw=78:ts=8:noet:ft=help:norl: