28.3.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 RET

Find first definition of tag (find-tag).

C-u M-.

Find next alternate definition of last tag specified.

C-u - M-.

Go back to previous tag found.

C-M-. pattern RET

Find a tag whose name matches pattern (find-tag-regexp).

C-u C-M-.

Find the next tag whose name matches the last pattern used.

C-x 4 . tag RET

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

C-x 5 . tag RET

Find first definition of tag, and create a new frame to select the buffer (find-tag-other-frame).

M-*

Pop back to where you previously invoked M-. and friends.

M-. (find-tag) prompts for a tag name and jumps to its source definition. It works by searching through the tags table for that tag’s file and approximate character position, visiting that file, and searching for the tag definition at ever-increasing distances away from the recorded approximate position.

When entering the tag argument to M-., the usual minibuffer completion commands can be used (see Completion), with the tag names in the selected tags table as completion candidates. If you specify an empty argument, the balanced expression in the buffer before or around point is the default argument. See Expressions.

You don’t need to give M-. the full name of the tag; a part will do. M-. finds tags which contain that argument as a substring. However, it prefers an exact match to a substring match. To find other tags that match the same substring, give find-tag a numeric argument, as in C-u M-. or M-0 M-.; this does not read a tag name, but continues searching the tags table’s text for another tag containing the same substring last used.

Like most commands that can switch buffers, find-tag has a variant that displays the new buffer in another window, and one that makes a new frame for it. The former is C-x 4 . (find-tag-other-window), and the latter is C-x 5 . (find-tag-other-frame).

To move back to previous tag definitions, use C-u - M-.; more generally, M-. with a negative numeric argument. Similarly, C-x 4 . with a negative argument finds the previous tag location in another window.

As well as going back to places you’ve found tags recently, you can go back to places from where you found them, using M-* (pop-tag-mark). Thus you can find and examine the definition of something with M-. and then return to where you were with M-*.

Both C-u - M-. and M-* allow you to retrace your steps to a depth determined by the variable find-tag-marker-ring-length.

The command C-M-. (find-tag-regexp) visits the tags that match a specified regular expression. It is just like M-. except that it does regexp matching instead of substring matching.