ctags

Generate tags for a single file, and output them to a file named "tags" in the current directory, overwriting the file if it exists

$ ctags [path/to/file]

$ ctags -f [path/to/file] *

$ ctags --recurse

$ ctags --fields=+ne --output-format=json [path/to/file]

ctags [options] [file(s)]

-a, --append
    Append tags to an existing tags file instead of overwriting it.

-f file, --output-file=file
    Write tags to the specified file instead of the default 'tags'.

-R, --recursive
    Recursively process files in subdirectories.

-x, --cxref
    Print a verbose cross-reference (cxref) file to standard output, rather than a tag file.

--exclude=pattern
    Exclude files or directories matching the specified shell pattern from tag generation.

--languages=list
    Restrict the languages for which tags are generated to those specified in the comma-separated list.

--list-languages
    List the programming languages supported by ctags.

--sort={yes|no}
    Determines whether the tag file entries are sorted. `yes` is the default; `no` can speed up generation for very large projects.

-u, --update
    Update tags for the specified files. Existing tags for those files are updated, and new tags are added.

-V, --version
    Display the version information for ctags and exit.

--help
    Display a brief usage summary and exit.

The ctags command is a powerful programming tool used to generate an index (or "tag") file of identifiers found in source code files. This index file contains a list of language objects such as functions, variables, classes, macros, and structures, along with their locations within the source files. Programmers commonly use these tag files with text editors and integrated development environments (IDEs) like Vim, Emacs, or VS Code to enable rapid navigation through large codebases. Features such as "jump to definition," symbol browsing, and intelligent auto-completion are powered by the information within the tags file.

ctags supports a wide array of programming languages, including C, C++, Java, Python, JavaScript, Ruby, and many others, making it an indispensable utility for software development. By providing a structured overview of the code's components, it significantly enhances productivity and code comprehension for developers.

It's important to note that there are different implementations of ctags, primarily Exuberant Ctags (the most widely distributed historical version) and Universal Ctags (an actively developed successor). While their core functionality is similar, Universal Ctags offers significantly enhanced language support and parsing capabilities. Users should be aware of which version they are using, as options and feature sets can differ.

Generating tags for extremely large codebases can be time-consuming and result in large tag files. While ctags is highly effective, it's typically a lexical scanner rather than a full-fledged parser, meaning it might occasionally misinterpret complex code constructs, although Universal Ctags has made significant strides in this area.

A very common way to generate tags for an entire project is to navigate to the project's root directory and run: ctags -R . This command recursively scans all files in the current directory and its subdirectories, creating a 'tags' file.

Text editors like Vim and Emacs leverage the 'tags' file for powerful navigation. For instance, in Vim, placing the cursor over a symbol (e.g., function name) and pressing Ctrl-] will jump directly to its definition, while Ctrl-t will return to the previous location. This dramatically speeds up code exploration.

ctags can be configured using a file named .ctags in your home directory or in the project root. This file can contain default options, language-specific settings, and regular expressions for custom tag patterns, allowing users to tailor tag generation to their specific needs.

The concept of ctags originated in the early days of Unix at AT&T Bell Labs and was a standard utility in the Berkeley Software Distribution (BSD). The original ctags primarily supported C and Pascal. Later, Exuberant Ctags emerged, significantly expanding language support to include many other programming languages, and became the de-facto standard implementation used across various Unix-like systems. More recently, Universal Ctags was forked from Exuberant Ctags to provide continued development, enhanced language parsing, and support for an even broader range of modern programming languages and features.

etags(1), grep(1), find(1), vim(1), emacs(1), gtags(1)