ETAGS(1)

📦 version 30.2, in opensuse-leap 16.0

🎀 NAME 🎀

okay so this is the GNU ETAGS(1) page, and the main characters are etags and gnuctags — together they generate tag file for Emacs, vi. 💖

🌈 SYNOPSIS 🌈

here’s the whole flag parade, copied exactly so nobody gets lost:

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 ...

gnuctags [-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 💅

okay bestie, the etags program is the one that creates a tag table file, in a format understood by emacs(1); the gnuctags program creates a similar table in a format understood by vi(1). both forms are lowkey polyglots and 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. ✨

both forms read the files specified on the command line, and write a tag table (defaults: TAGS for etags, tags for gnuctags) in the current working directory. files specified with relative file names will be recorded in the tag table with file names relative to the directory where the tag table resides. if the tag table is in /dev or is the standard output, however, the file names are made relative to the working directory. files specified with absolute file names will be recorded with absolute file names. files generated from a source file--like a C file generated from a source Cweb file--will be recorded with the name of the source file. 🫶

compressed files are supported using gzip, bzip2, xz, and zstd. the programs recognize the language used in an input file based on its file name and contents. the --language switch can be used to force parsing of the file names following the switch according to the given language, overriding guesses based on filename extensions. no cap, that’s the whole DESCRIPTION vibe check. 💜

✨ OPTIONS ✨

Okay bestie, listen — some of these options literally only make sense for the vi-style tag files that gnuctags produces, and etags straight up does not recognize them. Also, both programs accept unambiguous abbreviations for long option names, so you can be lazy about typing (within reason 💅).

  • -a, --append — append to the existing tag file instead of clobbering it. (For vi-format tag files, also peep --update below.)
  • -B, --backward-search — tag files written in the format vi expects contain regular expression search instructions, and this option writes them using the delimiter ? so the search goes backwards through files. The default is to use /, which searches forwards. Heads up: only gnuctags accepts this one.
  • --declarations — in C and its derived languages, this makes tags for function declarations, and it makes tags for extern variables unless --no-globals is in play. In Lisp, it creates tags for (defvar foo) declarations. In Mercury, declarations are lines that start with :- and those are always tagged. On top of that, this option tags predicates or functions in the first rules of clauses, like in Prolog.
  • -D, --no-defines — no tag entries for C preprocessor constant definitions and enum constants. If you've got a lot of header files getting tagged, this can make your tags file so much smaller (iconic file-size glow-up).
  • --globals — create tag entries for global variables in Perl and Makefile. This is already the default in C and derived languages.
  • --no-globals — do not tag global variables in C and derived languages. Typically this shrinks the file by a whole fourth, which is kind of a lot ngl.
  • --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 scanned were the one named in the #line directive. This switch hits different when the original file named by #line isn't around 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 a closing brace sitting in the first column is the final brace of a function or structure definition in C and C++. This matters for code that doesn't follow the GNU Coding conventions of only putting top-level braces in column zero. 🫶
  • -l language, --language=language — parse the following files according to the given language. You can sprinkle more than one of these in among the filenames. Use --help to get the list of available languages and their default filename extensions. For example, since Mercury and Objective-C share the filename extension .m, a test based on the file contents tries to detect which language it actually is. If that test fails, use --language=mercury or --language=objc. The "auto" language restores automatic detection based on the file name. The "none" language disables language parsing altogether — in that case only regexp matching happens (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, bestie, literally once) in place of a filename on the command line. etags will read from standard input and mark the tags it produces as belonging to the file FILE.
  • -Q, --class-qualify — qualify tag names with their class name in C++, ObjC, Java, and Perl. You get tag names in the form class::member for C++ and Perl, class(category) for Objective C, and class.member for Java. For Objective C this also produces class methods qualified with their arguments, like foo:bar:baz:more.
  • -o tagfile, --output=tagfile — explicitly name the file for the tag table. For etags only, a filename of - means standard output. This overrides the default TAGS or tags. (But it's ignored with -v or -x, so don't come for it.)
  • -r regexp, --regex=regexp — make tags based on regexp matching for the files that follow this option, in addition to the tags made with standard parsing based on language. You can freely intermix it with filenames and with the -R option. The regexps are cumulative, meaning each one adds to the previous ones. The regexps take one of these forms:
[{language}]/tagregexp/[nameregexp/]modifiers
@regexfile

Here tagregexp is what's used to match the tag. It should not match useless characters. If the match unavoidably grabs more characters than you need, it may be useful to add a nameregexp to narrow down the tag scope. gnuctags ignores regexps that have no nameregexp.

The syntax of regexps is the same as in Emacs, except that backslash escapes work like GNU grep (which means, for example, that shy groups are not supported), and [:ascii:], [:multibyte:], [:nonascii:], [:word:], and [:unibyte:] are not supported either. These 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 — ignore case when matching.
  • m — the tagregexp gets matched against the whole file contents at once instead of line by line, and the matching sequence can span multiple lines.
  • s — implies m, and means the dot character in tagregexp matches the newline char too.

The separator (which is / in the examples) can be any character different from space, tab, braces and @. If you need the separator character inside the regular expression, you have to quote it by putting \ in front of it.

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

In its second form, regexfile is the name of a file containing a number of arguments to the --regex= option, one per line. Lines beginning with a space or tab are assumed to be comments and get 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 get a list of the recognized languages. This feature is especially useful inside regex files. A regex file contains one regex per line. Empty lines, and lines beginning with a space or tab, are ignored. Lines beginning with @ are references to regex files whose name follows the @ sign. Other lines are treated as regular expressions, just like the ones following --regex. For example, this 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 files that follow. You can freely intermix this with filenames and the --regex option.
  • -u, --update — update tag entries for the files named on the command line, while leaving the tag entries for other files in place. Right now this works 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 gnuctags accepts this option.
  • -v, --vgrind — instead of generating a tag file, write an index (in vgrind format) to standard output. Only gnuctags accepts this option.
  • -x, --cxref — instead of generating a tag file, write a cross reference (in cxref format) to standard output. Only gnuctags accepts this option.
  • -h, -H, --help — print usage information. Follow it with one or more --language=LANG to print detailed info about how tags get 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.

okay that's the whole page bestie, you made it to the end 🎀 this little beauty is a GNU Tools situation, dated 2024-12-15, and it's the ETAGS(1) manual — go tag something iconic ✨💜

📦 where this page comes from