gtags
Generate tags for source code
SYNOPSIS
gtags [-v] [-q] [-f file] [-i lang] [-O] [-o] [-C] [directory]
PARAMETERS
-v, --verbose
Verbose mode.
Prints processing details to stderr.
-q, --quiet
Quiet mode.
Suppresses all non-error messages.
-f file, --file=file
Read newline-separated file list from file instead of directory scan.
-i lang
Force input language (e.g., C, C++, java, python); overrides auto-detection.
-O
Generate GTAGS only (skip GRTAGS, GPATH); faster for symbol lookup.
-o
Generate gtags.cscope only; for cscope tool compatibility.
-C
Follow symbolic links during scan.
DESCRIPTION
gtags is a key utility in the GNU Global suite for creating tag files that enable fast source code searching and cross-referencing. It recursively scans files in a directory (current by default), detects languages automatically, and parses symbols like functions, variables, typedefs, classes, and macros.
It produces three core files:
• GTAGS: Maps symbol names to file locations and line numbers.
• GRTAGS: Maps locations to referencing sites (reverse lookup for usages).
• GPATH: Maps canonical file paths to compact IDs.
Optionally generates gtags.cscope for cscope compatibility. These text-based databases allow global queries (e.g., find definition, references, files) without re-parsing, scaling to millions of lines. Supports C/C++, Java, Python, PHP, Ruby, Go, Rust, and 20+ languages via plugins.
Run gtags in project root for initial setup; integrates with editors like Vim, Emacs via plugins.
CAVEATS
Generation can be slow and disk-intensive for huge projects (>1GB source). No incremental updates; typically rm GTAGS GPATH GRTAGS gtags.cscope; gtags after changes. Ignores VCS dirs (.git) by default.
GENERATED FILES
GTAGS: Symbol → location.
GRTAGS: Location → references.
GPATH: Path → ID.
gtags.cscope: cscope db.
USAGE TIP
Combine with global -u for updates in some configs, or scripts for automation.
HISTORY
Originated in 1992 as htags by Hiroyuki Tamaoka; evolved into GNU Global in 1997. Major releases: v5 (2009, multi-lang), v6 (2014, JSON support), v7 (2023, async parsing). Widely used in embedded, kernel dev.
