EmacsTags

This page is about Emacs tags, a facility for recording names and their definitions and later looking up the definitions.

See BuildTags for how to build or update a tags file with a command-line program which records where names of different kinds of entities are defined and where they are referenced. Names that are indexed for quick lookup this way are called tags.

Once you have a tags file and you visit it using command ‘visit-tags-table’, you can follow tags (of functions, variables, macros, whatever) to their definitions.

Using Tags - Basic Functionality

Starting with Emacs 25, the default key bindings for tag navigation were mostly given to Xref, but the tags commands they were previously bound to are still available.

Xref abstracts over multiple identifier-searching backends (one of them being the tags backend). Not all tags functionality has an equivalent in ‘xref’, and vice versa (not all ‘xref’ functionality uses tags).

For more information about Xref, see the Emacs manual, node Xref. For more information about tags and tags tables, see the Emacs manual, node Tags Tables.

Xref Keys

Here are some of the ‘xref’ commands and their default key bindings starting with Emacs 25. Some of them use tags.

Tags Keys

Here are the basic tags commands, together with their default key bindings prior to Emacs 25.

`view-tag-other-window'

Command ‘view-tag-other-window’ acts like ‘find-tag-other-window’, but it doesn’t select the other window:

;;; View tags other window
(defun view-tag-other-window (tagname &optional next-p regexp-p)
  "Same as `find-tag-other-window' but doesn't move the point"
  (interactive (find-tag-interactive "View tag other window: "))
  (let ((window (get-buffer-window)))
    (find-tag-other-window tagname next-p regexp-p)
    (recenter 0)
    (select-window window)))

Choosing Among Multiple Tags for the Same Name

A tags file can have multiple definitions, hence multiple tags, for the same name. The different definitions for the name can be in the same source file or in different source files. And you can have multiple tags files. This means that when you ask to follow a name to its definition there can be some ambiguity.

It’s good to have a way to navigate among different definitions of the same name in such a way that you can tell where each source definition is located before you go to it. The following libraries all help you choose from among multiple tags for the same name in multiple files:

Icicles Helps You Work with Tags

You can use use Icicles multi-commands ‘icicle-search-tag’ and ‘icicle-find-tag’ to do all of what you normally do with a combination of commands `find-tag’, `tags-loop-continue’ (`M-,’), `tags-apropos’, ‘tags-query-replace’, ‘list-tags’, and more. Each of these is a general tags browser. Being multi-commands, you can visit any number of tags, in any order, in a single command invocation. You see a list of all tags that match your (reexp) input, and those choices are dynamically updated when you change your minibuffer input. See Icicles - Emacs Tags Enhancements.

In addition, you can use Icicles multi-command ‘icicle-imenu’ as an alternative to using tags. Like tags, it lets you navigate among definitions in multiple files – and also multiple saved regions and non-file buffers. Like ImenuMode, you need not build a tags file.

Since ‘icicle-imenu’ locates definitions using Imenu regexps, you can only navigate among definitions in buffers that you are visiting. This is both an advantage and a disadvantage: you can narrow the search to certain files, but you must know which files to search. And if you want to search all files, then you must open them all (e.g. by matching a project regexp). See Icicles Imenu.

Ido for Fuzzy Tag Selection

Ido can be used to browse tags by name using fuzzy searching, which lets you progressively narrow down potential options. This is similar to Goto Symbol functionality in Visual Studio Code or Sublime’s “Goto Symbol in Project”. See InteractivelyDoThings#CompleteFindTagUsingIdo.

Finding Files in a TAGS File

Directly open the a file referenced in the TAGS file without specifying the path, and share a single TAGS file across work areas of the same project. See find-file-in-tags

Finding Tags Files

See EtagsTable. To load an existing TAGS file by searching parent directories, you can use this:

(let ((my-tags-file (locate-dominating-file default-directory "TAGS")))
  (when my-tags-file
    (message "Loading tags file: %s" my-tags-file)
    (visit-tags-table my-tags-file)))

Revisit Tags Chronologically

You can use EtagsStack to see the history of which tags you have visited (using, for example, `M-.’) and retrace your visits chronologically.

An alternative (similar functionality, but with support for multiple tags types such as gtags, and additional operations such as deleting spurious tags) is http://github.org/markhepburn/tags-view

helm-etags-plus this is another helm interface to select candidates(support multiple tag files) and it support revisiting the history of which tags you have visited.

Use Tags to Complete Symbols

You can use ‘M-x complete-tag’ to get simple (context-free) symbol name completion. This works like other types of completion in Emacs – if there are multiple possibilities they are shown.

Does anybody know where the ‘tag-complete-symbol’ went? – AlexSchroeder

No idea, but try ‘tags-complete-tag’ in etags.el. It does pretty much the same thing. It’s not documented, which is criminal for such an insanely useful thing. – Anonymous

‘complete-tag’ is bound to ‘M-TAB’ by default but because some window managers use this to switch between windows, I tend to use ‘M-RET’ instead. Which tool do you use for context symbol completion? For example, I just want to see the functions accessible from point. – JérômeRadix

Semantic in CEDET has a feature that might fit your needs: “Smart Completion Completes symbols actually available in a given context. Some tools call this intellisense.” – Martin Muggli

Use `incron' (Inotify cron) to Generate Tags Automatically

An article here tells how to use incron to generate the tags automatically when a file changed:

http://blog.chmouel.com/2009/07/03/update-emacsvim-tags-with-inotify/

XEmacs vs GNU Emacs Versions of `etags.el'

etags.el is the Emacs library that defines commands for working with tags. XEmacs and GnuEmacs each have an etags.el file, and they are quite different. This divergence has been a source of frustration on my part over the years. In early 1990’s I started using the XEmacs version of etags.el and grew very fond of it’s configurability especially with regards to specifying which TAGS file to use based on regexp of file names, major modes, etc. It seems like to me that etags.el in GNU Emacs lacks such configurability. Hence, I still use etags.el, lifted from Lucid emacs, that I hacked up to work with Emacs many years ago. Again, if someone knowledgable with Emacs etags.el can correct me, I would appreciate it. – Anonymous

See EtagsTable


CategoryProgrammerUtils CategoryCompletion CategoryNavigation