Ubuntu Manpage: gtags - create tag files for global

NAME

       gtags - create tag files for global

SYNOPSIS

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

DESCRIPTION

       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.

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.

-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. Additionally, you can refer to the directory name where the system is installed as 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.

EXAMPLES

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

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´.

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

DIAGNOSTICS

       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.

BUG

       ´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.

AUTHOR

       Shigio YAMAGUCHI, Hideki IWAMOTO and others.

HISTORY

       The gtags command appeared in FreeBSD 2.2.2.

GNU Project                                       February 2021                                         GTAGS(1)

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

EXAMPLES

FILES

ENVIRONMENT

CONFIGURATION

EXAMPLES

DIAGNOSTICS

SEE ALSO

BUG

AUTHOR

HISTORY