Fork me on GitHub

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.

See also

  • :help opens Vim’s “main help file” (help.txt). There’s a short tutorial on how to use the help files at the top.

  • :help helphelp opens helphelp.txt, which is the full documentation for the :help commands and how to use the help files.

  • The Getting Started pages of the docs also have a Finding Help section (:help 02.8 from within Vim)

  • You can browse and search all of the help pages online at https://vimhelp.org/ (you don’t want to use the copy at http://vimdoc.sourceforge.net/, it’s hopelessly out of date)

  • The quickref (:help quickref) and index (:help index) are two handy help pages.

    vimhelp.org also has the VIM FAQ (which I don’t think is available from inside Vim).

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:

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.

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-] goes to the help tag under the cursor.

    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.

All posts tagged “vim”: