21.11.4 Selecting a Tags Table

At any time Emacs has one selected tags table, and all the commands for working with tags tables use the selected one. To select a tags table, use the variable tag-table-alist.

The value of tag-table-alist is a list that determines which TAGS files should be active for a given buffer. This is not really an association list, in that all elements are checked. The car of each element of this list is a pattern against which the buffers file name is compared; if it matches, then the cdr of the list should be the name of the tags table to use. If more than one element of this list matches the buffers file name, all of the associated tags tables are used. Earlier ones are searched first.

If the car of elements of this list are strings, they are treated as regular-expressions against which the file is compared (like the auto-mode-alist). If they are not strings, they are evaluated. If they evaluate to non-nil, the current buffer is considered to match.

If the cdr of the elements of this list are strings, they are assumed to name a tags file. If they name a directory, the string tags is appended to them to get the file name. If they are not strings, they are evaluated and must return an appropriate string.

For example:

  (setq tag-table-alist
        '(("/usr/src/public/perl/" . "/usr/src/public/perl/perl-3.0/")
          ("\\.el$" . "/usr/local/emacs/src/")
          ("/jbw/gnu/" . "/usr15/degree/stud/jbw/gnu/")
          ("" . "/usr/local/emacs/src/")
          ))

The example defines the tags table alist in the following way:

• Anything in the directory /usr/src/public/perl/ should use the TAGS file /usr/src/public/perl/perl-3.0/TAGS.
• Files ending in .el should use the TAGS file /usr/local/emacs/src/TAGS.
• Anything in or below the directory /jbw/gnu/ should use the TAGS file /usr15/degree/stud/jbw/gnu/TAGS.

If you had a file called /usr/jbw/foo.el, it would use both TAGS files,
/usr/local/emacs/src/TAGS and /usr15/degree/stud/jbw/gnu/TAGS (in that order), because it matches both patterns.

If the buffer-local variable buffer-tag-table is set, it names a tags table that is searched before all others when find-tag is executed from this buffer.

If there is a file called TAGS in the same directory as the file in question, then that tags file will always be used as well (after the buffer-tag-table but before the tables specified by this list).

If the variable tags-file-name is set, the TAGS file it names will apply to all buffers (for backwards compatibility.) It is searched first.

If the value of the variable tags-always-build-completion-table is t, the tags file will always be added to the completion table without asking first, regardless of the size of the tags file.

The function M-x visit-tags-table, is largely made obsolete by the variable tag-table-alist, tells tags commands to use the tags table file file first. The file should be the name of a file created with the etags program. A directory name is also acceptable; it means the file TAGS in that directory. The function only stores the file name you provide in the variable tags-file-name. Emacs does not actually read in the tags table contents until you try to use them. You can set the variable explicitly instead of using visit-tags-table. The value of the variable tags-file-name is the name of the tags table used by all buffers. This is for backward compatibility, and is largely supplanted by the variable tag-table-alist.