GTAGS(1)

🎀 GTAGS(1) 🎀

okay bestie, sit down, hydrate, because this is the general commands manual page for gtags and it's a LOT (which is why we're doing it in parts 💅).

---

✨ NAME ✨

gtags — create tag files for global 💖

---

🌸 SYNOPSIS 🌸

gtags [-ciIOqvw][-C dir][-d tag-file][-f file][dbpath]

---

🦋 DESCRIPTION 🦋

So. gtags is the girl who makes tag files for global(1). That's her whole job. She's very good at it. 🫶

gtags recursively collects source files under the current directory, picks up symbols, and writes all that cross-reference data into the tag files — those are GTAGS, GRTAGS and GPATH. Three files, one icon. 👑

By default, gtags picks up C, Yacc, assembly language, Java, C++ and PHP source files. Here's the full vibe check on suffixes, no cap:

• Files whose names end in .c, .h are assumed to be C source files.
• Files whose names end in .y are assumed to be Yacc source files.
• Files whose names end in .s, .S are assumed to be assembly language source files.
• Files whose names end in .java are assumed to be Java source files.
• Files whose names end in .c++, .cc, .hh, .cpp, .cxx, .hxx, .hpp, .C, .H are assumed to be C++ source files.
• Files whose names end in .php, .php3, .phtml are assumed to be PHP source files.

Other files are assumed to be text files. And gtags does not treat binary files. periodt. 🙅‍♀️

If gtags.files exists in the current directory, or a file is specified by the -f option, target files are limited by it. Lines starting with . are comments. 💬

---

✨ OPTIONS ✨

The following options are available:

• --accept-dotfiles — Accept files and directories whose names begin with a dot. By default, gtags ignores them. 🙈
• -c, --compact — Make GTAGS in compact format. This option does not influence GRTAGS, because that is always made in compact format. (she's born compact, she stays compact 💅)
• -C, --directory dir — Change the directory before doing all the work including parameter analysis. This option is ignored in GTAGS_OPTIONS. Please specify it on the command line directly. like, directly directly. 🫵
• --config[=name] — Print the value of config variable name. If name is not specified then print all names and values. Additionally, you can refer to the directory name where the system is installed as read only variables: bindir, libdir, datadir, localstatedir and sysconfdir. peek behind the curtain, bestie ✨
• -d, --dump tag-file — Dump a tag file as text to the standard output. Output format is 'key<tab>data'. This is for debugging. 🔍
• --explain — Explain handling files. she'll tell you exactly what she's doing with each one, very transparent, we love that 💖
• -f, --file file — Give a list of candidates of target files. Files which are not on the list are ignored. The argument file can be set to - to accept a list of files from the standard input. File names must be separated by newline. To make the list you may use find(1), which has rich options for selecting files. 🧺
• --gtagsconf file — Set environment variable GTAGSCONF to file.
• --gtagslabel label — Set environment variable GTAGSLABEL to label. 🏷️
• --help — Print a usage message.
• -I, --idutils — In addition to tag files, make ID database for idutils(1). overachiever behavior 🔥
• -i, --incremental — Update tag files incrementally. It's better to use global(1) with the -u command.
• -O, --objdir — Use BSD-style obj directory as the location of tag files. If GTAGSOBJDIRPREFIX is set and $GTAGSOBJDIRPREFIX directory exists, gtags creates $GTAGSOBJDIRPREFIX/<current directory> directory and makes tag files in it. Though you can use MAKEOBJDIRPREFIX instead of GTAGSOBJDIRPREFIX, it is deprecated. If dbpath is specified, this option is ignored. 📦
• --single-update file — Update tag files for a single file. It is considered that file was added, updated or deleted, and there is no change in other files. This option implies the -i option. just one file, one little file, main character energy 🎀
• --skip-unreadable — Skip unreadable files. This option was deprecated. Any file that cannot be read is skipped with a warning message, regardless of whether this option is used. so like. it does nothing now. we still list her though 💀
• --skip-symlink [=type] — Skip symbolic links. If type is 'f' then skip only symbolic links for file, else if 'd' then skip only symbolic links for directory. The default value of type is 'a' (all symbolic links). If you configure this program with --with-fts, the type value is ignored, and always treated as if 'a' were specified. 🔗
• --sqlite3 — Use Sqlite 3 API to make tag files. By default, BSD/DB 1.85 API is used. To use this option, you need to invoke configure script with --with-sqlite3 in the build phase. 🗄️
• --statistics — Print statistics information. numbers!! give me the numbers 📊
• -q, --quiet — Quiet mode. 🤫
• -v, --verbose — Verbose mode. 🗣️
• --version — Show version number.
• -w, --warning — Print warning messages. ⚠️
• dbpath — The directory in which tag files are generated. The default is the current directory. 📁

---

💫 EXAMPLES 💫

$ ls -F
Makefile      src/    lib/
$ gtags -v
$ global -x main
main              10 src/main.c  main (argc, argv) {

see how easy that was? ate. 💅

---

🌸 FILES 🌸

• GTAGS — Tag file for definitions.
• GRTAGS — Tag file for references.
• GPATH — Tag file for source files.
• gtags.conf, $HOME/.globalrc — Configuration data for GNU Global. See gtags.conf(5).
• gtags.files — The list of candidates of target files.
• .notfunction — The list of symbols which is not a definition. If this file exists in the project root directory, gtags does not regard the symbols listed in this file as definitions. Lines starting with ';' are comment lines.

---

🌈 ENVIRONMENT 🌈

The following environment variables affect the execution of gtags:

• GTAGSCACHE — The size of the B-tree cache. The default is 50000000 (bytes). 🧠
• GTAGSCONF — Configuration file.
• GTAGSFORCECPP — If this variable is set, each file whose suffix is .h is forcibly parsed by the built-in C++ parser. Do not set this variable if you are using plug-in parsers. This variable and the built-in C++ parser are deprecated. 🚫
• GTAGSFORCEENDBLOCK — If this variable is set, each } at the first column brings end of block of 0 level.
• GTAGSLABEL — Configuration label. The default is 'default'.
• GTAGSLOGGING — If this variable is set, $GTAGSLOGGING is used as the path name of a log file. There is no default value. 📝
• GTAGS_COMMANDLINE — This variable can only be referenced from the hook (see gtags_hook). gtags sets its own effective command line to this variable before calling the hook. Each argument is separated by whitespace, and real whitespace is represented as '%20'. This is read only. 👀
• GTAGS_OPTIONS — The value of this variable is inserted in the head of arguments.
• GTAGSOBJDIR — If this variable is set, it is used as the name of BSD-style objdir. The default is 'obj'. Though you can use MAKEOBJDIR instead of GTAGSOBJDIR, it is deprecated.
• GTAGSOBJDIRPREFIX — If this variable is set, it is used as the prefix of BSD-style objdir. The default is '/usr/obj'. Though you can use MAKEOBJDIRPREFIX instead of GTAGSOBJDIRPREFIX, it is deprecated.
• TMPDIR — The location used to stored temporary files. The default is '/tmp'.

y'all the deprecated ones are deprecated for a reason, please stop using them, i'm begging 🙏

---

✨ CONFIGURATION ✨

The following configuration variables affect the execution of gtags. You can see the default value for each variable with the --config option. 🎛️

• gtags_parser (comma separated list) — Specify the mapping of language names and plug-in parsers. Each part delimited by the comma consists of a language name, a colon, the shared object path, an optional colon followed by a function name. If the function name is not specified, 'parser' is assumed. As a special exception, gtags collects values from multiple gtags_parser variables. For these mappings, the first match is adopted.
• gtags_hook (command line) — Specify a command line which should be executed at the beginning of gtags after loading configuration file. You can use this hook to update gtags.files dynamically. "./" in it always means the project root directory, since gtags is always invoked there.

This hook is ignored when the following options are specified: --version, --help, --config, --dump.

• icase_path (boolean) — Ignore case distinctions in the path. Suffixes check is affected by this capability.
• langmap (comma separated list) — Language mapping. Each comma-separated map consists of a language name, a colon, and a list of file extensions. You can specify a glob pattern surrounded by parentheses instead of an extension for the files without extensions (e.g. Make:([Mm]akefile).mak.mk). As a special exception, gtags collects values from multiple langmap variables. For these mappings, the first match is adopted. Default mapping is: 'c:.c.h,yacc:.y,asm:.s.S,java:.java,cpp:.c++.cc.hh.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml'. 🗺️
• skip (comma separated list) — gtags skips files and directories which are given in this list. As a special exception, gtags collects values from multiple skip variables. If the value ends with '/', it is assumed as a directory and gtags skips all files under it. The value may include glob patterns (*, ?, [...], [!...], [^...]).

If the value starts with '/', it is assumed a relative path name from the root directory of the project. You cannot use glob patterns for a path name. However, this direction is out-of-date, and is not recommended. Instead, you can use -f option which can be combined with find(1). Since find(1) has rich options to select files, you can do everything. Additionally, this technique can also be applied to any other tagging systems like ctags(1), cscope(1), etc.

Skip list is also effective when you use the -f or gtags.files.

---

💫 EXAMPLES 💫

#
# There are several ways to use Universal Ctags plug-in parser.
#
$ gtags --gtagsconf=/usr/local/share/gtags/gtags.conf --gtagslabel=universal-ctags
$ gtags --explain
or
$ export GTAGSCONF=/usr/local/share/gtags/gtags.conf
$ export GTAGSLABEL=universal-ctags
$ gtags --explain
or
# In your project
$ cp /usr/local/share/gtags/gtags.conf .
$ vi gtags.conf          # default:tc=native => default:tc=universal-ctags
$ gtags --explain

three ways to serve the same look, we love options 🎀

💀 DIAGNOSTICS 💀

okay so here's the tea on whether it worked or not, bestie:

• gtags exits with a non-0 value if an error occurred, and 0 if everything was chill. no in-between, no vibes-based ambiguity.
• heads up tho: any files that gtags created while it had a non-zero exit code? consider those corrupted. fr fr. don't trust them, don't build on them, just yeet them and re-run. 🫶

---

👀 SEE ALSO 👀

your little friend group of manpages, go say hi:

• global(1) — the main character of querying, lowkey iconic
• htags(1) — makes the pretty HTML version, serving looks
• gtags.conf(5) — where all the config drama lives

and if you wanna go deeper down the rabbit hole: GNU Global source code tag system at http://www.gnu.org/software/global/. that's the source, bestie. 🌐✨

---

🚨 BUG 🚨

real talk, no filter:

• GTAGS and GRTAGS are very large. like, alarming. before you run this command, please please please check the space on your disk. do the vibe check on your df first, i'm begging 😭
• Assembly language support is far from complete. it only extracts ENTRY() and ALTENTRY() from the source file — that's it, that's the whole bag. and honestly it's probably only valid for FreeBSD and Linux kernel source anyway. 🤷‍♀️
• C++ support is deprecated. letting you know gently but firmly. 💀
• there is no concurrency control about tag files. nope. none. so don't have two things writing to them at once unless you enjoy chaos. 🙈

---

👑 AUTHOR 👑

Shigio YAMAGUCHI, Hideki IWAMOTO and others. absolute legends, we stan. 🫶✨

---

📜 HISTORY 📜

the gtags command appeared in FreeBSD 2.2.2. it's been serving cunt since the 90s, periodt. 💅🎀

---

and that's a wrap on the GTAGS(1) page, bestie!! 🦋 this was the GNU Project's very own manpage, dated February 2021, and you now know it inside out. go tag some code, hydrate, and remember: no concurrency control, no cap. 💖🌸⭐