28.4.3 Selecting a Tags Table

Emacs has at any time at most one selected tags table. All the commands for working with tags tables use the selected one. To select a tags table, type M-x visit-tags-table, which reads the tags table file name as an argument, with TAGS defaulting to the first directory that contains a file named TAGS encountered when recursively searching upward from the default directory.

Emacs does not actually read in the tags table contents until you try to use them; all visit-tags-table does is store the file name in the variable tags-file-name, and not much more. The variable’s initial value is nil; that value tells all the commands for working with tags tables that they must ask for a tags table file name to use.

Using visit-tags-table when a tags table is already loaded gives you a choice: you can add the new tags table to the current list of tags tables, or start a new list. The tags commands use all the tags tables in the current list. If you start a new list, the new tags table is used instead of others. If you add the new table to the current list, it is used as well as the others.

You can specify a precise list of tags tables by setting the variable tags-table-list to a list of strings, like this:

(setq tags-table-list
      '("~/.emacs.d" "/usr/local/lib/emacs/src"))

This tells the tags commands to look at the TAGS files in your ~/.emacs.d directory and in the /usr/local/lib/emacs/src directory. The order depends on which file you are in and which tags table mentions that file.

Do not set both tags-file-name and tags-table-list.