On Unix-like operating systems, the ctags command creates tag files for source code.

Description

The ctags and etags programs (hereafter collectively referred to as ctags, except where distinguished) generate an index (or “tag”) file for a variety of language objects found in the specified file(s). This tag file allows these items to be quickly and easily located by a text editor or other utility. A “tag” signifies a language object for which an index entry is available (or the index entry created for that object).

  • Description
  • Source files
  • Syntax
  • Options
  • Operational Details
  • Tag File Format
  • How To Use With Vi
  • How To Use With Gnu Emacs
  • How to use with NEdit
  • Caveats
  • Known bugs
  • Environment variables
  • Files
  • Examples
  • Related commands
  • Linux commands help

Alternatively, ctags can generate a cross reference file which lists, in human-readable form, information about the various source objects found in a set of language files.

Tag index files are supported by numerous editors, which allow the user to locate the object associated with a name appearing in a source file and jump to the file and line which defines the name. These include:

  • vi and its derivatives (e.g., Elvis, Vim, Vile, Lemmy)
  • CRiSP
  • Emacs
  • FTE (Folding Text Editor)
  • JED
  • jEdit
  • Mined
  • NEdit (Nirvana Edit)
  • TSE (The SemWare Editor)
  • UltraEdit
  • WorkSpace
  • X2
  • Zeus

ctags is capable of generating different kinds of tags for each of many different languages. For a complete list of supported languages, the names by which they are recognized, and the kinds of tags that are generated for each, see the –list-languages and –list-kinds options.

Source files

Unless the –language-force option is specified, the language of each source file is automatically selected based upon a mapping of file names to languages. The mappings in effect for each language may be display using the –list-maps option and may be changed using the –langmap option. On platforms which support it, if the name of a file is not mapped to a language and the file is executable, the first line of the file is checked to see if the file is a “#!” script for a recognized language.

By default, all other file names are ignored. This permits running ctags on all files in either a single directory (e.g., “ctags *”), or on all files in an entire source directory tree (e.g., “ctags -R”), since only those files whose names are mapped to languages are scanned.

The reason that .h extensions are mapped to C++ files rather than C files is because it is common to use .h extensions in C++, and no harm results in treating them as C++ files.

Syntax

ctags [options] [file(s)]

etags [options] [file(s)]

Options

Despite the wealth of available options, defaults are set so that ctags is most commonly executed without any options (e.g., “ctags *”, or “ctags -R”), which creates a tag file in the current directory for all recognized source files. The options described below are provided merely to allow custom tailoring to meet special needs.

Note that spaces separating the single-letter options from their parameters are optional.

Note also that the boolean parameters to the long form options (those beginning with “–” and that take a “[=yes|no]” parameter) may be omitted, in which case “=yes” is implied. (e.g., –sort is equivalent to –sort=yes). Note also that “=1” and “=on” are considered synonyms for “=yes”, and that “=0” and “=off” are considered synonyms for “=no”.

Some options are either ignored or useful only when used while running in etags mode (see -e option). Such options are noted.

Most options may appear anywhere on the command line, affecting only those files which follow the option. A few options, however, must appear before the first file name and are noted as such.

Options taking language names accept those names in either upper or lowercase. See the –list-languages option for a complete list of the built-in language names.

Options are:

Operational Details

As ctags considers each file name in turn, it tries to determine the language of the file by applying the following three tests in order: if the file extension is mapped to a language, if the file name matches a shell pattern mapped to a language, and finally if the file is executable and its first line specifies an interpreter using the Unix-style “#!” specification (if supported on the platform). If a language was identified, the file is opened and then the appropriate language parser is called to operate on the currently open file. The parser parses through the file and adds an entry to the tag file for each language object it is written to handle. See Tag File Format, below, for details on these entries.

int foo ARGDECL4(void *, ptr, long int, nbytes)

/* creates an RCS version string in module */ MODULE_VERSION("$Revision: 690 $")

CLASS Example { // your content here };

Newer implementations of ctags impose no formatting requirements on C code as do legacy implementations. Older implementations of ctags tended to rely upon certain formatting assumptions to help it resolve coding dilemmas caused by preprocessor conditionals.

In general, ctags tries to be smart about conditional preprocessor directives. If a preprocessor conditional is encountered within a statement which defines a tag, ctags follows only the first branch of that conditional (except in the special case of “#if 0”, in which case it follows only the last branch). The reason for this is that failing to pursue only one branch can result in ambiguous syntax, as in the following example:

#ifdef TWO_ALTERNATIVES struct { #else union { #endif short a; long b; }

Both branches cannot be followed, or braces become unbalanced and ctags would be unable to make sense of the syntax. If the application of this heuristic fails to properly parse a file, generally due to complicated and inconsistent pairing in the conditionals, ctags retries the file using a different heuristic which does not selectively follow conditional preprocessor branches, but instead falls back to relying upon a closing brace ("}") in column 1 as indicating the end of a block once any brace imbalance results from following a #if conditional branch.

ctags also tries to specially handle arguments lists enclosed in double sets of parentheses to accept the following conditional construct:

extern void foo __ARGS((int one, char two));

Any name immediately preceding the “((” is automatically ignored and the previous name is used. C++ operator definitions are specially handled. For consistency with all types of operators (overloaded and conversion), the operator name in the tag file is always preceded by the string “operator " (i.e., even if the actual operator definition was written as “operator«”).

After creating or appending to the tag file, it is sorted by the tag name, removing identical tag lines.

Tag File Format

When not running in etags mode, each entry in the tag file consists of a separate line, each looking like this in the most general case:

tag_namefile_nameex_cmd;"extension_fields

The fields and separators of these lines are specified as follows:

  • tag name;
  • single tab character;
  • name of the file in which the object associated with the tag is located;
  • single tab character;
  • EX command used to locate the tag in the file; generally a search pattern (either /pattern/ or ?pattern?) or line number (see –excmd). Tag file format 2 (see –format) extends this EX command under certain circumstances to include a set of extension fields (described below) embedded in an EX comment immediately appended to the EX command, which leaves it backward-compatible with original vi implementations.

A few special tags are written into the tag file for internal purposes. These tags are composed in such a way that they always sort to the top of the file. Therefore, the first two characters of these tags are used a magic number to detect a tag file for purposes of determining whether a valid tag file is being overwritten rather than a source file.

Note that the name of each source file is recorded in the tag file exactly as it appears on the command line. Therefore, if the path you specified on the command line was relative to the current directory, then it is recorded in that same manner in the tag file. See, however, the –tag-relative option for how this behavior can be modified.

Extension fields are tab-separated key-value pairs appended to the end of the EX command as a comment, as described above. These key value pairs appear in the general form “key:value”. Their presence in the lines of the tag file are controlled by the –fields option. The possible keys and the meaning of their values are as follows:

Also, information on the scope of the tag definition may be available, with the key portion equal to some language-dependent construct name and its value the name declared for that construct in the program. This scope entry indicates the scope in which the tag was found. For example, a tag generated for a C structure member would have a scope that looked like “struct:myStruct”.

How To Use With Vi

By default, vi expects a tag file by the name “tags” in the current directory. Once the tag file is built, the following commands exercise the tag indexing feature:

vi -t tag

Start vi and position the cursor at the file and line where “tag” is defined.

:ta tag

Find a tag.

Ctrl-]

Find the tag under the cursor.

Ctrl-T

Return to previous location before jump to tag (not widely implemented).

How To Use With Gnu Emacs

By default, Emacs expect a tag file by the name “TAGS” in the current directory. Once the tag file is built, the following commands exercise the tag indexing feature:

M-x visit-tags-table FILE

Select the tag file, “FILE”, to use.

M-. [TAG]

Find the first definition of TAG. The default tag is the identifier under the cursor.

M-*

Pop back to where you previously invoked “M-.”.

C-u M-.

Find the next definition for the last tag.

How to use with NEdit

NEdit version 5.1 and later can handle the new extended tag file format (see –format). To make NEdit use the tag file, select “File->Load Tags File”. To jump to the definition for a tag, highlight the word, then press Ctrl+D. NEdit 5.1 can read multiple tag files from different directories. Setting the X resource nedit.tagFile to the name of a tag file instructs NEdit to automatically load that tag file at startup time.

Caveats

Because ctags is neither a preprocessor nor a compiler, use of preprocessor macros can fool ctags into either missing tags or improperly generating inappropriate tags. Although ctags is designed to handle certain common cases, this is the single biggest cause of reported problems. In particular, the use of preprocessor constructs which alter the textual syntax of C can fool ctags. You can work around many such problems using the -I option.

Note that since ctags generates patterns for locating tags (see the –excmd option), it is entirely possible that the wrong line may be found by your editor if there exists another source line that is identical to the line containing the tag. The following example demonstrates this condition:

int variable; /* … / void foo(variable) int variable; { / … */ }

Depending on what editor you use and where in the code you happen to be, the search pattern may locate the local parameter declaration in foo() before it finds the actual global variable definition, as the lines (and therefore their search patterns are identical). This can be avoided by use of the –excmd=n option.

Known bugs

When parsing a C++ member function definition (e.g., “className::function”), ctags cannot determine whether the scope specifier is a class name or a namespace specifier and always lists as a class name in the scope portion of the extension fields. Also, if a C++ function is defined outside of the class declaration (the usual case), the access specification (i.e., public, protected, or private) and implementation information (e.g., virtual, pure virtual) contained in the function declaration are not known when the tag is generated for the function definition. It is, however, available for prototypes (e.g –c++-kinds=+p).

No qualified tags are generated for language objects inherited into a class.

Environment variables

Files

  • /ctags.cnf (on MS-DOS and Microsoft Windows only)
  • /etc/ctags.conf
  • /usr/local/etc/ctags.conf
  • $HOME/.ctags
  • $HOME/ctags.cnf (on MS-DOS, Microsoft Windows only)
  • .ctags
  • ctags.cnf (on MS-DOS, Microsoft Windows only)

If any of these configuration files exist, each is expected to contain a set of default options that are read in the order listed when ctags starts, but before the CTAGS environment variable is read or any command line options are read. This makes it possible to set up site-wide, personal or project-level defaults. It is possible to compile ctags to read an additional configuration file before any of those shown above, which is indicated if the output produced by the –version option lists the “custom-conf” feature. Options appearing in the CTAGS environment variable or on the command line override options specified in these files. Only options are read from these files. Note that the option files are read in line-oriented mode in which spaces are significant (since shell quoting is not possible). Each line of the file is read as one command line parameter (as if it were quoted with single quotes). Therefore, use new lines to indicate separate command-line arguments.

  • tags (The default tag file created by ctags.)
  • TAGS (The default tag file created by etags.)

Examples

ctags -R *

Create a tags file for every source file in the current directory and in all subdirectories.

ex — Line-editor mode of the vi text editor.lex — Generate programs for performing lexical tasks.vgrind — “Grind” nice program listings.vi — Text editor based on the visual mode of ex.yacc — “Yet another compiler-compiler.”