ETAGS(1)

📦 version 30.2, in fedora 44

💖 ETAGS(1) — the GNU one, bestie 💖

aka etags, ctags — generate tag file for Emacs, vi ✨

okay so. picture this: you're in a giant codebase, you wanna jump to a definition, and your editor is like "girl idk where that is". enter these two. they build the tag table. your editor eats it up. we love a supportive icon 🫶

🌸 NAME 🌸

etags, ctags — generate tag file for Emacs, vi

✨ SYNOPSIS ✨

etags [-aCDGIQRVh] [-i file] [-l language]
[-o tagfile] [-r regexp] [--parse-stdin=file]
[--append] [--no-defines] [--globals] [--no-globals]
[--no-line-directive] [--include=file] [--ignore-indentation]
[--language=language] [--members] [--no-members] [--output=tagfile]
[--class-qualify] [--regex=regexp] [--no-regex] [--help] [--version]
file ...
ctags [-aCdgIQRVh] [-BtTuvwx] [-l language]
[-o tagfile] [-r regexp] [--parse-stdin=file]
[--append] [--backward-search] [--cxref] [--no-defines] [--globals]
[--no-globals] [--no-line-directive] [--ignore-indentation]
[--language=language] [--members] [--no-members] [--class-qualify]
[--output=tagfile] [--regex=regexp] [--update] [--help] [--version] file
...

🦋 DESCRIPTION 🦋

so here's the whole vibe.

The etags program makes a tag table file, in a format that emacs(1) understands 💜. The ctags program makes basically the same kind of table, but in a format vi(1) gets 💙. Two siblings, one job, different love languages.

Both forms of the program understand the syntax of C, Objective C, C++, Java, Fortran, Ada, Cobol, Erlang, Forth, Go, HTML, LaTeX, Emacs Lisp/Common Lisp, Lua, Makefile, Mercury, Pascal, Perl, Ruby, Rust, PHP, PostScript, Python, Prolog, Scheme, and most assembler-like syntaxes. yes bestie, it really said "all of them" and meant it 💅

Both forms read the files you list on the command line, and write out a tag table in the current working directory. The defaults:

  • etags → TAGS
  • ctags → tags

Files you give with relative file names get recorded in the tag table with file names relative to the directory where the tag table lives 📁. But — and this is the plot twist — if the tag table is in /dev or is the standard output, the file names get made relative to the working directory instead. ok noted 📝

Files you give with absolute file names get recorded with absolute file names. periodt.

Files generated from a source file — like a C file generated from a source Cweb file — get recorded with the name of the source file 🧚 (the original, not the glow-up).

🗜️ Compressed files are supported, using gzip, bzip2, xz, and zstd. no need to decompress first, we're not doing extra steps in this house.

The programs figure out which language an input file is in based on its file name and contents 🔍. And if the guessing is giving wrong answers? The --language switch forces parsing of the file names that come after the switch according to the language you named, overriding whatever it would've guessed from the filename extensions. you're the main character, you decide 😌

✨ more of this page is coming, don't you dare close the tab ✨

✨ OPTIONS ✨

okay bestie, quick heads up before we dive in: some of these options only make sense for the vi-style tag files that ctags produces, and etags literally does not recognize them. also both programs accept unambiguous abbreviations for long option names, so you can be lazy (respectfully) and type less. 💅

  • -a, --append — append to an existing tag file instead of making a new one. (for vi-format tag files, also peep --update.)
  • -B, --backward-search — so tag files written in the format vi expects contain regex search instructions, right? -B writes those using the delimiter "?", which searches backwards through files. the default is to use the delimiter "/", which searches forwards. only ctags accepts this option. 👑
  • --declarations — in C and languages derived from it, this creates tags for function declarations, and creates tags for extern variables unless --no-globals is used. in Lisp, it creates tags for (defvar foo) declarations. in Mercury, declarations start a line with ":-" and are always tagged. on top of all that, this option tags predicates or functions in the first rules of clauses, just like in Prolog.
  • -D, --no-defines — do NOT create tag entries for C preprocessor constant definitions or enum constants. if you've got a ton of header files being tagged, this can make your tags file way smaller. 🍓
  • --globals — create tag entries for global variables in Perl and Makefile. this is the default in C and its derived languages.
  • --no-globals — don't tag global variables in C and derived languages. typically this shrinks the file size by like a fourth. 😭
  • --no-line-directive — ignore #line preprocessor directives in C and derived languages. the default is to honor those directives and record the tags as if the file being scanned was the one named in the #line directive. this switch is a lifesaver when the original file named by #line isn't available anymore.
  • -i file, --include=file — drop a note in the tag file saying that when you're searching for a tag, you should also consult the tags file file after checking the current file. only etags accepts this option. 💖
  • -I, --ignore-indentation — don't lean on indentation as much as we normally do. right now that means: don't assume that a closing brace in the first column is the final brace of a function or structure definition in C and C++. this matters big time for code that doesn't follow the GNU Coding conventions of putting only top-level braces in column zero.
  • -l language, --language=language — parse the following files according to the given language. more than one of these can be intermixed with filenames. use --help to get a list of the available languages and their default filename extensions. for example, since Mercury and Objective-C both use the filename extension .m, a test based on contents tries to detect which language it is. if that test fails, use --language=mercury or --language=objc. the "auto" language restores automatic detection of language based on the file name. and the "none" language disables language parsing altogether — only regexp matching gets done in that case (see the --regex option).
  • --members — create tag entries for variables that are members of structure-like constructs in PHP. this is the default for C and derived languages.
  • --no-members — do not tag member variables.
  • --packages-only — only tag packages in Ada files.
  • --parse-stdin=file — may be used (only once!) in place of a file name on the command line. etags will read from standard input and mark the produced tags as belonging to the file FILE.
  • -Q, --class-qualify — qualify tag names with their class name in C++, ObjC, Java, and Perl. this gives you tag names of the form class::member for C++ and Perl, class(category) for Objective C, and class.member for Java. for Objective C, it also produces class methods qualified with their arguments, like foo:bar:baz:more. iconic honestly.
  • -o tagfile, --output=tagfile — explicit name of the file for the tag table. for etags only, a file name of - means standard output. this overrides the default TAGS or tags. (but it's ignored with -v or -x.)
  • -r regexp, --regex=regexp — make tags based on regexp matching for the files following this option, in addition to the tags made with the standard parsing based on language. may be freely intermixed with filenames and the -R option. the regexps are cumulative, meaning each one of these options adds to the previous ones. the regexps take one of these forms:
[{language}]/tagregexp/[nameregexp/]modifiers
@regexfile

where tagregexp is used to match the tag. it should not match useless characters. if the match unavoidably grabs more characters than needed via tagregexp, it may be useful to add a nameregexp to narrow down the tag scope. ctags ignores regexps without a nameregexp. the syntax of regexps is the same as in Emacs, except that backslash escapes are the same as GNU grep (which means, for example, that shy groups are not supported), and [:ascii:], [:multibyte:], [:nonascii:], [:word:], and [:unibyte:] are not supported. the following character escape sequences are supported: \a, \b, \d, \e, \f, \n, \r, \t, \v, which respectively stand for the ASCII characters BEL, BS, DEL, ESC, FF, NL, CR, TAB, VT.

the modifiers are a sequence of 0 or more characters among i, which means to ignore case when matching; m, which means that the tagregexp will be matched against the whole file contents at once rather than line by line, and the matching sequence can match multiple lines; and s, which implies m and means that the dot character in tagregexp matches the newline char as well.

the separator, which is / in the examples, can be any character different from space, tab, braces and @. if the separator character is needed inside the regular expression, it must be quoted by preceding it with \.

the optional {language} prefix means that the tag should be created only for files of language language, and ignored otherwise. this is especially useful when you're storing lots of predefined regexps in a file.

in its second form, regexfile is the name of a file that contains a number of arguments to the --regex= option, one per line. lines beginning with a space or tab are assumed to be comments, and ignored.

here are some examples. all the regexps are quoted to protect them from shell interpretation. 🐚

tag the DEFVAR macros in the emacs source files:

--regex='/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'

tag VHDL files (this example is a single long line, broken here for formatting reasons):

--language=none --regex='/[ \t]*\(ARCHITECTURE\|\ CONFIGURA‐
TION\) +[^ ]* +OF/' --regex='/[ \t]*\ \(ATTRIBUTE\|ENTITY\|FUNC‐
TION\|PACKAGE\( BODY\)?\ \|PROCE‐
DURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'

tag Tcl files (this last example shows the usage of a tagregexp):

--lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/'

a regexp can be preceded by {lang}, which restricts it to matching lines of files of the specified language. use etags --help to obtain a list of the recognized languages. this feature is particularly useful inside regex files. a regex file contains one regex per line. empty lines, and those lines beginning with space or tab, are ignored. lines beginning with @ are references to regex files whose name follows the @ sign. other lines are considered regular expressions like those following --regex. for example, the command

etags --regex=@regex.file *.c

reads the regexes contained in the file regex.file.

  • -R, --no-regex — don't do any more regexp matching on the following files. may be freely intermixed with filenames and the --regex option.
  • -u, --update — update tag entries for the files specified on the command line, leaving tag entries for other files in place. currently this is implemented by deleting the existing entries for the given files and then rewriting the new entries at the end of the tags file. honestly it's often faster to just rebuild the whole tag file than to use this. only ctags accepts this option.
  • -v, --vgrind — instead of generating a tag file, write an index (in vgrind format) to standard output. only ctags accepts this option.
  • -x, --cxref — instead of generating a tag file, write a cross reference (in cxref format) to standard output. only ctags accepts this option.
  • -h, -H, --help — print usage information. if it's followed by one or more --language=LANG, it prints detailed information about how tags are created for LANG. 🫶
  • -V, --version — print the current version of the program (same as the version of the emacs etags it ships with).

👀 SEE ALSO 👀

📜 COPYING 📜

Copyright 1992, 1999, 2001–2025 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this document under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this document into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.

and that's the whole page bestie, you made it to the end 🎀 this one's from GNU Tools, version dated 2024-12-15, and it's the ETAGS(1) manual. go tag something, you absolute legend 💜✨
📦 where this page comes from