This page is about 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 M-x visit-tags-table, you can follow tags (of functions, variables, macros, whatever) to their definitions. These are the basic commands:
‘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
M-,’ (`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
See the Emacs manual, node Tags for more information: Tags.
This function acts like
‘find-tag-other-window’ but lets the point on current buffer:
;;; 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.
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
To load an existing TAGS file by searching parent directories, use this:
(defun find-file-upwards (file-to-find) "Recursively searches each parent directory starting from the default-directory. looking for a file with name file-to-find. Returns the path to it or nil if not found." (labels ((find-file-r (path) (let* ((parent (file-name-directory path)) (possible-file (concat parent file-to-find))) (cond ((file-exists-p possible-file) possible-file) ; Found ;; The parent of ~ is nil and the parent of / is itself. ;; Thus the terminating condition for not finding the file ;; accounts for both. ((or (null parent) (equal parent (directory-file-name parent))) nil) ; Not found (t (find-file-r (directory-file-name parent))))))) ; Continue (find-file-r default-directory))) (let ((my-tags-file (find-file-upwards "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 (ie context free) symbol name Completion. This works like other types of completion in emacs, if there are multiple possibilities a window will be opened showing them all.
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
An article document here how to use incron to generate the tags automatically when a file changed. You can read it here :
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