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.
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).
Here are some of the
‘xref’ commands and their default key bindings starting with Emacs 25. Some of them use tags.
‘xref-find-definitions’) – find a tag, that is, use a tags file to look up a definition. If the backend returns multiple hits with the same name, a window will pop up showing all the hits, use
‘p’to navigate and press
‘RET’to jump to a particular match.
C-x 4 .’ (
‘xref-find-definitions-other-window’) – select the buffer containing a tag’s definition in another window, and move point there.
‘xref-pop-marker-stack’) – jump back
‘xref-find-apropos’) – find all meaningful symbols that match a regexp or word list
‘xref-find-references’) – find all references to the identifier at point
Here are the basic tags commands, together with their default key bindings prior to Emacs 25.
‘find-tag’) – find a tag, that is, use the Tags file to look up a definition. If there are multiple tags in the project with the same name, use `
C-u M-.’ to go to the next match.
‘M-x find-tag-other-window’– selects the buffer containing the tag’s definition in another window, and move point there.
‘pop-tag-mark’) – jump back
‘M-x tags-search’– regexp-search through the source files indexed by a tags file (a bit like
‘M-x tags-query-replace’– query-replace through the source files indexed by a tags file
‘tags-loop-continue’) – resume
‘tags-query-replace’starting at point in a source file
‘M-x tags-apropos’– list all tags in a tags file that match a regexp
‘M-x list-tags’– list all tags defined in a source file
‘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)))
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:
You can use use Icicles multi-commands
‘icicle-find-tag’ to do all of what you normally do with a combination of commands `find-tag’, `tags-loop-continue’ (`
‘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.
‘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 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.
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
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)))
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
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
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
An article here tells how to use incron to generate the tags automatically when a file changed:
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