.\" This file is generated automatically by convert.pl from gtags/manual.in.
.TH GTAGS 1 "June 2018" "GNU Project"
.SH NAME
gtags \- create tag files for global
.SH SYNOPSIS
\fBgtags\fP [-ciIOqvw][-C \fIdir\fP][-d \fItag-file\fP][-f \fIfile\fP][\fIdbpath\fP]
.br
.SH DESCRIPTION
\fBGtags\fP is used to create tag files for \fBglobal\fP(1).
.PP
\fBGtags\fP 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\').
.PP
By default, \fBgtags\fP 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.
.PP
If \'gtags.files\' exists in the current directory
or a file is specified by the \fB-f\fP option,
target files are limited by it. Lines starting with \'. \' are comments.
.SH OPTIONS
The following options are available:
.PP
.TP
\fB--accept-dotfiles\fP
Accept files and directories whose names begin with a dot.
By default, \fBgtags\fP ignores them.
.TP
\fB-c\fP, \fB--compact\fP
Make \'GTAGS\' in compact format.
This option does not influence \'GRTAGS\',
because that is always made in compact format.
.TP
\fB-C\fP, \fB--directory\fP \fIdir\fP
Change the directory before doing all the work including parameter analysis.
This option is ignored in \fBGTAGS_OPTIONS\fP.
Please specify it on the command line directly.
.TP
\fB--config\fP[=\fIname\fP]
Print the value of config variable \fIname\fP.
If \fIname\fP 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:
\fBbindir\fP, \fBlibdir\fP, \fBdatadir\fP, \fBlocalstatedir\fP and \fBsysconfdir\fP.
.TP
\fB-d\fP, \fB--dump\fP \fItag-file\fP
Dump a tag file as text to the standard output.
Output format is \'key<tab>data'. This is for debugging.
.TP
\fB--explain\fP
Explain handling files.
.TP
\fB-f\fP, \fB--file\fP \fIfile\fP
Give a list of candidates of target files.
Files which are not on the list are ignored.
The argument \fIfile\fP 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 \fBfind\fP(1), which has rich options
for selecting files.
.TP
\fB--gtagsconf\fP \fIfile\fP
Set environment variable \fBGTAGSCONF\fP to \fIfile\fP.
.TP
\fB--gtagslabel\fP \fIlabel\fP
Set environment variable \fBGTAGSLABEL\fP to \fIlabel\fP.
.TP
\fB--help\fP
Print a usage message.
.TP
\fB-I\fP, \fB--idutils\fP
In addition to tag files, make ID database for \fBidutils\fP(1).
.TP
\fB-i\fP, \fB--incremental\fP
Update tag files incrementally.
It's better to use \fBglobal\fP(1) with the \fB-u\fP command.
.TP
\fB-O\fP, \fB--objdir\fP
Use BSD-style obj directory as the location of tag files.
If \fBGTAGSOBJDIRPREFIX\fP is set and \'$GTAGSOBJDIRPREFIX\' directory exists,
\fBgtags\fP creates \'$GTAGSOBJDIRPREFIX/<current directory>\' directory
and makes tag files in it.
Though you can use \fBMAKEOBJDIRPREFIX\fP instead of \fBGTAGSOBJDIRPREFIX\fP,
it is deprecated.
If \fIdbpath\fP is specified, this option is ignored.
.TP
\fB--single-update\fP \fIfile\fP
Update tag files for a single file.
It is considered that \fIfile\fP was added, updated or deleted,
and there is no change in other files.
This option implies the \fB-i\fP option.
.TP
\fB--skip-unreadable\fP
Skip unreadable files.
.TP
\fB--skip-symlink\fP [=\fItype\fP]
Skip symbolic links. If \fItype\fP is 'f' then skip only symbolic links for
file, else if 'd' then skip only symbolic links for directory.
The default value of \fItype\fP is 'a' (all symbolic links).
.TP
\fB--sqlite3\fP
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
\fB--with-sqlite3\fP in the build phase.
.TP
\fB--statistics\fP
Print statistics information.
.TP
\fB-q\fP, \fB--quiet\fP
Quiet mode.
.TP
\fB-v\fP, \fB--verbose\fP
Verbose mode.
.TP
\fB--version\fP
Show version number.
.TP
\fB-w\fP, \fB--warning\fP
Print warning messages.
.TP
\fIdbpath\fP
The directory in which tag files are generated.
The default is the current directory.
.SH EXAMPLES
.nf
$ ls -F
Makefile      src/    lib/
$ gtags -v
$ global -x main
main              10 src/main.c  main (argc, argv) {
.fi
.SH FILES
.TP
\'GTAGS\'
Tag file for definitions.
.TP
\'GRTAGS\'
Tag file for references.
.TP
\'GPATH\'
Tag file for source files.
.TP
\'gtags.conf\', \'$HOME/.globalrc\'
Configuration data for GNU GLOBAL.
See \fBgtags.conf\fP(5).
.TP
\'gtags.files\'
The list of candidates of target files.
.TP
\'.notfunction\'
The list of symbols which is not a definition.
If this file exists in the project root directory, \fBgtags\fP does not
regard the symbols listed in this file as definitions.
.SH ENVIRONMENT
The following environment variables affect the execution of \fBgtags\fP:
.PP
.TP
\fBGTAGSCACHE\fP
The size of the B-tree cache. The default is 50000000 (bytes).
.TP
\fBGTAGSCONF\fP
Configuration file.
.TP
\fBGTAGSFORCECPP\fP
If this variable is set, each file whose suffix is \'.h\' is treated
as a C++ source file.
.TP
\fBGTAGSFORCEENDBLOCK\fP
If this variable is set, each } at the first column brings end of block
of 0 level.
.TP
\fBGTAGSLABEL\fP
Configuration label. The default is \'default\'.
.TP
\fBGTAGSLOGGING\fP
If this variable is set, \'$GTAGSLOGGING\' is used as the path name
of a log file. There is no default value.
.TP
\fBGTAGS_COMMANDLINE\fP
This variable can only be referenced from the hook (see gtags_hook).
\fBGtags\fP 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.
.TP
\fBGTAGS_OPTIONS\fP
The value of this variable is inserted in the head of arguments.
.TP
\fBGTAGSOBJDIR\fP
If this variable is set, it is used as the name of BSD-style objdir.
The default is \'obj\'.
Though you can use \fBMAKEOBJDIR\fP instead of \fBGTAGSOBJDIR\fP,
it is deprecated.
.TP
\fBGTAGSOBJDIRPREFIX\fP
If this variable is set, it is used as the prefix of BSD-style objdir.
The default is \'/usr/obj\'.
Though you can use \fBMAKEOBJDIRPREFIX\fP instead of \fBGTAGSOBJDIRPREFIX\fP,
it is deprecated.
.TP
\fBTMPDIR\fP
The location used to stored temporary files. The default is \'/tmp\'.
.SH CONFIGURATION
The following configuration variables affect the execution of \fBgtags\fP.
You can see the default value for each variable with the \fB--config\fP option.
.PP
.TP
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, \fBgtags\fP collects values
from multiple gtags_parser variables.
For these mappings, the first match is adopted.
.TP
gtags_hook (command line)
Specify a command line which should be executed at the beginning of \fBgtags\fP
after loading configuration file. You can use this hook to update
\'gtags.files\' dynamically.
"./" in it always means the project root directory, since \fBgtags\fP is
always invoked there.

.br
This hook is ignored when the following options are specified:
--version, --help, --config, --dump.
.TP
icase_path (boolean)
Ignore case distinctions in the path.
Suffixes check is affected by this capability.
.TP
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, \fBgtags\fP collects values
from multiple langmap variables.
For these mappings, the first match is adopted.
Default mapping is:
.br
\'c:.c.h,yacc:.y,asm:.s.S,java:.java,cpp:.c++.cc.hh.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml\'.
.TP
skip (comma separated list)
\fBGtags\fP skips files and directories which are given in this list.
As a special exception, \fBgtags\fP collects values from multiple
skip variables.
If the value ends with \'/\', it is assumed as a directory and
\fBgtags\fP skips all files under it.
The value may include glob patterns (*, ?, [...], [!...], [^...]).

.br
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 \fB-f\fP option which can be combined with
\fBfind\fP(1). Since \fBfind\fP(1) has rich options to select files,
you can do everything. Additionally, this technique can also be applied
to any other tagging systems like \fBctags\fP(1), \fBcscope\fP(1), etc. 

.br
Skip list is also effective when you use the \fB-f\fP or \'gtags.files\'.
.SH DIAGNOSTICS
\fBGtags\fP exits with a non-0 value if an error occurred, 0 otherwise.
.PP
Note that files created by \fBgtags\fP with a non-zero exit code should be
considered corrupted.
.SH "SEE ALSO"
\fBglobal\fP(1),
\fBhtags\fP(1),
\fBgtags.conf\fP(5).
.PP
GNU GLOBAL source code tag system
.br
(http://www.gnu.org/software/global/).
.SH BUG
\'GTAGS\' and \'GRTAGS\' are very large.
In advance of using this command, check the space of your disk.
.PP
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.
.PP
C++ support is deprecated.
.PP
There is no concurrency control about tag files.
.SH AUTHOR
Shigio YAMAGUCHI, Hideki IWAMOTO and others.
.SH HISTORY
The \fBgtags\fP command appeared in FreeBSD 2.2.2.