gtags - create tag files for global
gtags [-ciIOqvw][-C dir][-d tag-file][-f
file][dbpath]
Gtags is used to create tag files for global(1).
Gtags recursively collects source files under the current
directory, picks up symbols and writes the cross-reference data into the tag
files (´GTAGS´, ´GRTAGS´ and
´GPATH´).
By default, gtags picks up C, Yacc, assembly language,
Java, C++ and PHP source files. 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. Gtags does not treat binary
files.
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.
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.
- -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.
- --config[=name]
- Print the value of config variable name. If name is not
specified then print all names and values. In addition to the variables
listed in the ENVIRONMENT section, you can refer to install directories by
read only variables: bindir, libdir, datadir,
localstatedir and sysconfdir.
- -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.
- -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).
- -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.
- --skip-unreadable
- Skip unreadable files.
- --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).
- --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.
- -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.
$ ls -F
Makefile src/ lib/
$ gtags -v
$ global -x main
main 10 src/main.c main (argc, argv) {
- ´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.
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´.
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´.
Gtags exits with a non-0 value if an error occurred, 0
otherwise.
Note that files created by gtags with a non-zero exit code
should be considered corrupted.
´GTAGS´ and ´GRTAGS´ are very large.
In advance of using this command, check the space of your disk.
Assembly language support is far from complete. It extracts only
ENTRY() and ALTENTRY() from source file. Probably valid only for FreeBSD and
Linux kernel source.
C++ support is deprecated.
There is no concurrency control about tag files.
Shigio YAMAGUCHI, Hideki IWAMOTO and others.
The gtags command appeared in FreeBSD 2.2.2.