How to Use Vim’s Built-in Help

Vim has a comprehensive built-in manual. Unfortunately you need some help to know how to use the help. This post is a quick reference and tutorial for Vim’s :help files.

Opening the help window

:help (or just :h) opens the “main help file” (the front page of the help manual, help.txt) in a new window. F1 does the same thing. The Help key on your keyboard might also work if it has one. Use :vert help to open it in a vertical split instead of a horizontal one, or :tab help to open it in a new tab. I don’t think it’s possible to open a help file in or in-place-of the current non-help window. If there’s already a help window open :help will use that window instead of opening a new window (even if the cursor is currently in a different window).

:help {subject} (or just :h {subject}) opens the help tag {subject}. {subject} can be lots of different types of thing:

• Topics, e.g. :help deleting or :help options

• Normal-mode commands: :help x or :help cc.

  Use ctrl- for commands that’re prefixed with Ctrl, e.g. :help ctrl-a.

  Use _ for multi-key commands, e.g. :help ctrl-w_w.

  ^ also works insead of ctrl, e.g. :help ^p is the same as :help ctrl-p.

  Names of special keys need to be wrapped in angle brackets, e.g. :help ctrl-w_<Up>. See :help keycodes for the names of all the special keys.

• Insert-mode commands have an i_ prefix, e.g. :help i_ctrl-r

• Visual-mode commands have a v_ prefix, e.g. :help v_o

• Ex commands start with :, e.g. :help :substitute

• Keyboard commands that you can use when in Vim’s command-line mode start with c_, for example :help c_ctrl-r.

  Special characters for use in Ex commands also use c_, for example: :help c_%.

• Vim command-line arguments start with -, e.g. :help -t

• The names of settings have to be wrapped in single quotes, e.g. :help 'number'

• Error messages have their own help tags, e.g. :help E37

• And more! See :help help-summary for the complete list of help tag types

Closing the help window

:q or ZZ will close a help window like any other window if the cursor is in the help window.

:helpclose or :helpc will close the help window even if the cursor isn’t in it.

Navigating in the help window

Vim’s help files are peppered with highlighted “tags” that’re links to other locations in the help files. The tags work as links for jumping back and forth:

• [Ctrl-]](https://vimhelp.org/tagsrch.txt.html#CTRL-]) goes to the help tag under the cursor.

  [Ctrl-]](https://vimhelp.org/tagsrch.txt.html#CTRL-]) is Vim’s general “jump to definition” command, it can be used to jump to the definitions of things in code too.

  If you have mouse mode enabled (:set mouse=a) then double-clicking on a tag also follows it.

• Ctrl-t or Ctrl-o go back to the previous location (repeat to keep going back to prior locations).

  These are Vim’s general commands for going back to older positions in the tag stack (Ctrl-t) or jump list (Ctrl-o).

  :tag and Ctrl-i go forward again.

Searching for help topics

:help {subject} (or just :h {subject}) opens the help tag {subject}. {subject} can include wildcards like *, ? or [a-z].

If there are multiple help tags matching the given subject then when you press Enter Vim opens the “best” match. See :help {subject} (literally) for details of the algorithm Vim uses to decide which match is best.

You can use Ctrl + d or Tab to search for tag names. For example type :help buffer and then instead of Enter press Ctrl + d or Tab to see a list of all help tags matching “buffer”. This doesn’t just list all tags that start with “buffer”, it lists all tags that match “buffer” according to the matching algorithm Vim uses. It includes all tags that have “buffer” anywhere in the tag name.

Searching the full text of help files with :helpgrep

:helpgrep {pattern} or :helpg {pattern} does a full-text search of all help files for pattern and opens the first match. It populates the quickfix list with all the matches so you can use quickfix commands like :cn to go to the next match, :cp to go to the previous match, :copen to open the quickfix window with the list of all matches. See :help quickfix for how to use the quickfix window.

Patterns are case-sensitive, regardless of the ignorecase setting, unless you append \c to the end of the pattern.

:lhelpgrep (or just :lh) does the same but uses the help window’s location list, so it doesn’t mess up your quickfix list.

You can also use Google to search the full text of vimhelp.org: google.com/search?q=quickfix site:vimhelp.org. Or Duck Duck Go: duckduckgo.com/?q=quickfix site:vimhelp.org.