21.11.5 Finding a Tag

The most important thing that a tags table enables you to do is to find the definition of a specific tag.

M-. tag &optional other-window

Find first definition of tag (find-tag).

C-u M-.

Find next alternate definition of last tag specified.

C-x 4 . tag

Find first definition of tag, but display it in another window (find-tag-other-window).

M-. (find-tag) is the command to find the definition of a specified tag. It searches through the tags table for that tag, as a string, then uses the tags table information to determine the file in which the definition is used and the approximate character position of the definition in the file. Then find-tag visits the file, moves point to the approximate character position, and starts searching ever-increasing distances away for the text that should appear at the beginning of the definition.

If an empty argument is given (by typing RET), the sexp in the buffer before or around point is used as the name of the tag to find. See Lists, for information on sexps.

The argument to find-tag need not be the whole tag name; it can be a substring of a tag name. However, there can be many tag names containing the substring you specify. Since find-tag works by searching the text of the tags table, it finds the first tag in the table that the specified substring appears in. To find other tags that match the substring, give find-tag a numeric argument, as in C-u M-.. This does not read a tag name, but continues searching the tag table’s text for another tag containing the same substring last used. If your keyboard has a real META key, M-0 M-. is an easier alternative to C-u M-..

If the optional second argument other-window is non-nil, it uses another window to display the tag. Multiple active tags tables and completion are supported.

Variables of note include the following:

tag-table-alist

Controls which tables apply to which buffers.

tags-file-name

Stores a default tags table.

tags-build-completion-table

Controls completion behavior.

buffer-tag-table

Specifies a buffer-local table.

make-tags-files-invisible

Sets whether tags tables should be very hidden.

tag-mark-stack-max

Specifies how many tags-based hops to remember.

Like most commands that can switch buffers, find-tag has another similar command that displays the new buffer in another window. C-x 4 . invokes the function find-tag-other-window. (This key sequence ends with a period.)

Emacs comes with a tags table file TAGS (in the directory containing Lisp libraries) that includes all the Lisp libraries and all the C sources of Emacs. By specifying this file with visit-tags-table and then using M-. you can quickly look at the source of any Emacs function.