{tag}	the identifier
{separator}	one or more <Tab> or space characters
{filename}	the file that contains the definition of {tag}
{command}	the Ex command that positions the cursor on the tag.

The identifier normally is the name of a function, but it can be any identifier. There is one special form for local (static) functions: {filename}:{identifier}. Some ctags programs make use of this to separate local (static) functions from global functions. (Detail: Vim compares only the last part of the filename and ignores any path before it).

The command can be any Ex command, but normally it is a search command like

In Vi the ":tag" command sets the last search pattern when the tag is searched for. In Vim this is not done, the previous search pattern is still remembered, unless the 't' flag is present in 'cpoptions'. The search pattern is always put in the search history.

Emacs style tag files are supported if Vim was compiled with EMACS_TAGS defined. Check the output of ":version", if it contains "+emacs_tags" then it was. Sorry, there is no explanation about Emacs tag files here, it is only supported for backwards compatibility :-).

The 'tags' option is a list of file names. Each of these files is searched for the tag. This can be used to use a different file than the default file "tags". It can also be used to access a common tags file. The next file in the list is not used when: - A matching static tag for the current buffer has been found. - A matching global tag has been found. This also depends on the 'ignorecase' option. If it is off, and the tags file only has a match without matching case, the next tags file is searched for a match with matching case. If no tag with matching case is found, the first match without matching case is used. If 'ignorecase' is on, and a matching global tag with or without matching case is found, this one is used, no further tags files are searched. When a tag file name starts with "./", the '.' is replaced with the path of the current file. This makes it possible to use a tags file in the directory where the current file is (no matter what the current directory is). If the current directory is equal to the directory where the current file is, the tag file names that start with "./" are skipped. You should normally always have the name both with and without the "./". When using "./tags" the "tags" file will not be found when editing a file in the current directory. The idea of using "./" is that you can define which tag file is searched first: In the current directory ("tags,./tags") or in the directory of the current file ("./tags,tags"). For example: :set tags=./tags,tags,/home/user/commontags

In this example the tag will first be searched for in the file "tags" in the directory where the current file is. Next the "tags" file in the current directory. If it is not found there, then the file "/home/user/commontags" will be searched for the tag.

Instead of the comma a space may be used. Then a backslash is required for the space to be included in the string option:

To include a space in a file name use three backslashes. To include a comma in a file name use two backslashes. For example, use:

for the files "tag file" and "/home/user/common,tags". The 'tags' option will have the value "tag\ file,/home/user/common\,tags".

If the 'tagrelative' option is on (which is the default) and using a tag file in another directory, file names in that tag file are relative to the directory where the tag file is.

The tags that you use are remembered in the tag stack. You can print this stack with the ":tags" command. The result looks like this:

#	TO tag	FROM line	in file
1	main	1	harddisk2:text/vim/test
> 2	FuncA	58	-current-
3	FuncC	357	harddisk2:text/vim/src/amiga.c

This list shows the tags that you jumped to and the cursor position before that jump. The older tags are at the top, the newer at the bottom.

The '>' points to the active entry. This is the tag that will be used by the next ":tag" command. The CTRL-T and ":pop" command will use the position above the active entry.

The line number and file name are remembered to be able to get back to where you were before the tag command. The line number will be correct, also when deleting/inserting lines, unless this was done by another program (e.g. another instance of Vim).

You can jump to previously used tags with several commands. Some examples:

	main  --->  FuncA  --->  FuncC
	      --->  FuncB

If you issue a ":ta {ident}" or CTRL-] command, this tag is inserted at the current position in the stack. If the stack was full (it can hold up to 20 entries), the oldest entry is deleted and the older entries shift one position up (their index number is decremented by one). If the last used entry was not at the bottom, the entries below the last used one are deleted. This means that an old branch in the call graph is lost. After the commands explained above the tag stack will look like this:

#	TO tag	FROM line	in file
1	main	1	harddisk2:text/vim/test
2	FuncB	59	harddisk2:text/vim/src/main.c
>

8.2 Include file searches

When a line is encountered that includes another file, that file is searched before continuing in the current buffer. Files included by included files are also searched. When an include file could not be found it is silently ignored. Use the ":checkpath" command to discover which files could not be found, possibly your 'path' option is not set up correctly. Note: the included file is searched, not a buffer that may be editing that file. Only for the current file the lines in the buffer are used. The string can be any keyword or a defined macro. For the keyword any match will be found. For defined macros only lines that match with the 'define' option will be found. The default is "\^#[ \t]*define", which is for C programs. Also, when a match is found for a defined macro, the displaying of lines continues with the next line when a line ends in a backslash. The commands that start with "[" start searching from the start of the current file. The commands that start with "]" start at the current cursor position. The 'include' option is used to define a line that includes another file. The default is "\^#[ \t]*include", which is for C programs. Note: Vim does not recognize C syntax, if the 'include' option matches a line inside "#ifdef/#endif" or inside a comment, it is searched anyway. The 'isfname' option is used to recognize the file name that comes after the matched pattern.

The 'path' option is used to find the directory for the include files that do not have an absolute path.

The 'comments' option is used for the commands that display a single line or jump to a line. It defines patterns that may start a comment. Those lines are ignored for the search, unless [!] is used. One exception: When the line matches the pattern "^# *define" it is not considered to be a comment.

[i

Display the first line that contains the keyword under the cursor. The search starts at the beginning of the file. Lines that look like a comment are ignored (see 'comments' option). If a count is given, the count'th matching line is displayed. {not in Vi}

]i

like "[i", but start at the current cursor position. {not in Vi}

:[range]is[earch][!] [count] [/]pattern[/]

Like "[i" and "]i", but search in [range] lines (default: whole file). Without [!] lines that are recognized as comments are skipped. Without [/] only whole words are matched, using the pattern "\<pattern\>". {not in Vi}

[I

Display all lines that contain the keyword under the cursor. File names and line numbers are displayed for the found lines. The search starts at the beginning of the file. {not in Vi}

]I

like "[I", but start at the current cursor position. {not in Vi}

:[range]il[ist][!] [/]pattern[/]

Like "[I" and "]I", but search in [range] lines (default: whole file). Without [!] lines that are recognized as comments are skipped. Without [/] only whole words are matched, using the pattern "\<pattern\>". {not in Vi}

[ CTRL-I

Jump to the first line that contains the keyword under the cursor. The search starts at the beginning of the file. Lines that look like a comment are ignored (see 'comments' option). If a count is given, the count'th matching line is jumped to. {not in Vi}

] CTRL-I

like "[ CTRL-I", but start at the current cursor position. {not in Vi}

:[range]ij[ump][!] [count] [/]pattern[/]

Like "[ CTRL-I" and "] CTRL-I", but search in [range] lines (default: whole file). Without [!] lines that are recognized as comments are skipped. Without [/] only whole words are matched, using the pattern "\<pattern\>". {not in Vi}

CTRL-W CTRL-I

CTRL-W i

Open a new window, with the cursor on the first line that contains the keyword under the cursor. The search starts at the beginning of the file. Lines that look like a comment line are ignored (see 'comments' option). If a count is given, the count'th matching line is jumped to. {not in Vi}

:[range]isp[lit][!] [count] [/]pattern[/]

Like "CTRL-W i" and "CTRL-W i", but search in [range] lines (default: whole file). Without [!] lines that are recognized as comments are skipped. Without [/] only whole words are matched, using the pattern "\<pattern\>". {not in Vi}

[d

Display the first macro definition that contains the macro under the cursor. The search starts from the beginning of the file. If a count is given, the count'th matching line is displayed. {not in Vi}

]d

like "[d", but start at the current cursor position. {not in Vi}

:[range]ds[earch][!] [count] [/]pattern[/]

Like "[d" and "]d", but search in [range] lines (default: whole file). Without [!] lines that are recognized as comments are skipped. Without [/] only whole words are matched, using the pattern "\<pattern\>". {not in Vi}

[D

Display all macro definitions that contain the macro under the cursor. File names and line numbers are displayed for the found lines. The search starts from the beginning of the file. {not in Vi}

]D

like "[D", but start at the current cursor position. {not in Vi}

:[range]dl[ist][!] [/]pattern[/]

Like "[D" and "]D", but search in [range] lines (default: whole file). Without [!] lines that are recognized as comments are skipped. Without [/] only whole words are matched, using the pattern "\<pattern\>". {not in Vi}

[ CTRL-D

Jump to the first macro definition that contains the keyword under the cursor. The search starts from the beginning of the file. If a count is given, the count'th matching line is jumped to. {not in Vi}

] CTRL-D

like "[ CTRL-D", but start at the current cursor position. {not in Vi}

:[range]dj[ump][!] [count] [/]pattern[/]

Like "[ CTRL-D" and "] CTRL-D", but search in [range] lines (default: whole file). Without [!] lines that are recognized as comments are skipped. Without [/] only whole words are matched, using the pattern "\<pattern\>". {not in Vi}

CTRL-W CTRL-D

CTRL-W d

Open a new window, with the cursor on the first macro definition line that contains the keyword under the cursor. The search starts from the beginning of the file. If a count is given, the count'th matching line is jumped to. {not in Vi}

:[range]dsp[lit][!] [count] [/]pattern[/]

Like "CTRL-W d", but search in [range] lines (default: whole file). Without [!] lines that are recognized as comments are skipped. Without [/] only whole words are matched, using the pattern "\<pattern\>". {not in Vi}

:che[ckpath]

List all the included files that could not be found. {not in Vi}

:che[ckpath]!

List all the included files. {not in Vi}

a

Append text after the cursor [count] times.

A

Append text at the end of the line [count] times.

<Insert> or

i

Insert text before the cursor [count] times.

I

Insert text before the first CHAR on the line [count] times.

gI

Insert text in column 1 [count] times. {not in Vi}

o

Begin a new line below the cursor and insert text, repeat [count] times. {Vi: blank [count] screen lines}

O

Begin a new line above the cursor and insert text, repeat [count] times. {Vi: blank [count] screen lines}

When 'autoindent' is on, the indent for a new line is obtained from the previous line. When 'smartindent' or 'cindent' is on, the indent for a line is automatically adjusted for C programs.

'textwidth' can be set to the maximum width for a line. When a line becomes too long when appending characters a line break is automatically inserted.

:r[ead] [name]

Insert the file [name] (default: current file) below the cursor.

:{range}r[ead] [name]

Insert the file [name] (default: current file) below the specified line.

:r[ead] !{cmd}

Execute {cmd} and insert its standard output below the cursor. A temporary file is used to store the output of the command which is then read into the buffer. 'shellredir' is used to save the output of the command, which can be set to include stderr or not.

The <NL> character is recognized as end-of-line marker. If the 'textmode' option is on, a <CR> in front of an <NL> is ignored and a CTRL-Z at the end of the file is ignored. The 'textmode' option is default on for MS-DOS.

If the 'textauto' option is on Vim tries to recognize the type of end-of-line marker (see 5.2 how this is done). However, the 'textmode' option will not be changed. Only while reading one file the text mode is used or not.

On non-MS-DOS systems the message "[textmode]" is shown if a file is read in text mode, to remind you that something unusual is done. On MS-DOS the message "[notextmode]" is shown if a file is read without text mode.

An example on how to use ":r !":

["x]<Del> or

["x]x

Delete [count] characters under and after the cursor [into register x] (not linewise). Does the same as "dl". See :fixdel if the <Del> key does not do what you want. Also see 'whichwrap'. {<Del> not in Vi}

["x]X

Delete [count] characters before the cursor [into register x] (not linewise). Does the same as "dh". Also see 'whichwrap'.

["x]d{motion}

Delete text that is moved over [into register x]. See below for exception.

["x]dd

Delete [count] lines [into register x] (linewise).

["x]D

Delete the characters under the cursor until the end of the line and [count]-1 more lines [into register x]; synonym for d$ (not linewise).

{Visual}["x]x or

{Visual}["x]d

Delete the highlighted text [into register x] (see the chapter on Visual_mode). {not in Vi}

{Visual}["x]X or

{Visual}["x]D

Delete the highlighted lines [into register x] (see the chapter on Visual_mode). {not in Vi}

:[range]d[elete] [x]

Delete [range] lines (default: current line) [into register x].

:[range]d[elete] [x] {count}

Delete {count} lines, starting with [range] (default: current line, See Command line_ranges) [into register x].

An exception for the d{motion} command: If the motion is not linewise, the start and end of the motion are not in the same line and before the start and after the end are only blanks, the delete becomes linewise. This means that the blank line that would remain is also deleted.

J

Join [count] lines, with a minimum of two lines.

{Visual}J

Join the highlighted lines, with a minimum of two lines. {not in Vi}

:[range]j[oin][!]

Join [range] lines. Same as "J", except when [!] is given, then no spaces will be inserted or deleted. When [range] is given and the start and end of the range are equal, nothing happens. Default is to join two lines.

:[range]j[oin][!] {count}

Join {count} lines, starting with [range] (default: current line, See Command line_ranges). Same as "J", except when [!] is given, then no spaces will be inserted or deleted.

One space is inserted in place of the <NL>, unless the line ended with a space, <Tab> or the next line started with a ')'. If the next line has leading white space it is deleted first. If the 'joinspaces' option is on, two spaces are inserted after a period.