@c This file is generated automatically by convert.pl from gtags/manual.in.
@unnumberedsubsec NAME
gtags - create tag files for global.
@unnumberedsubsec SYNOPSIS
@quotation
gtags [-ciIOqvw][-d tag-file][-f file][dbpath]@*
@end quotation
@unnumberedsubsec 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
(@file{GTAGS}, @file{GRTAGS} and @file{GPATH}).

If @file{gtags.files} exists or the @samp{-f} option is specified,
target files are limited by it. Lines starting with @samp{. } are comments.

C, yacc, Assembly, Java, C++ and PHP source files are supported.
Files whose names end in @file{.c}, @file{.h} are assumed to be C source files.
Files whose names end in @file{.y} are assumed to be yacc source files.
Files whose names end in @file{.s}, @file{.S} are assumed to be Assembly source files.
Files whose names end in @file{.java} are assumed to be Java source files.
Files whose names end in @file{.c++}, @file{.cc}, @file{.hh}, @file{.cpp}, @file{.cxx}, @file{.hxx}, @file{.hpp}, @file{.C}, @file{.H} are assumed to be C++ source files.
Files whose names end in @file{.php}, @file{.php3}, @file{.phtml} are assumed to be PHP source files.
Other files are assumed to be text files. Gtags does not treat binary files.
@unnumberedsubsec OPTIONS
The following options are available:

@table @asis
@item @samp{--accept-dotfiles}
Accept files and directories whose names begin with a dot.
By default, gtags ignores them.
@item @samp{-c}, @samp{--compact}
Make @file{GTAGS} in compact format.
This option does not influence @file{GRTAGS},
because that is always made in compact format.
@item @samp{--config}[=name]
Print the value of config variable name.
If name is not specified then print all names and values.
@item @samp{-d}, @samp{--dump} tag-file
Dump a tag file as text to the standard output. Output format is 'key<tab>data'.
This is for debugging.
@item @samp{--explain}
Explain handling files.
@item @samp{-f}, @samp{--file} file
Browse through all files whose names are listed in file.
The argument file can be set to @samp{-} to accept a list of
files from the standard input.
File names must be separated by newline.
@item @samp{--gtagsconf} file
Set environment variable @var{GTAGSCONF} to file.
@item @samp{--gtagslabel} label
Set environment variable @var{GTAGSLABEL} to label.
@item @samp{-I}, @samp{--idutils}
In addition to tag files, make ID database for idutils(1).
@item @samp{-i}, @samp{--incremental}
Update tag files incrementally.
It's better to use global(1) with the @samp{-u} command.
@item @samp{-O}, @samp{--objdir}
Use BSD-style objdir as the location of tag files.
If @file{$MAKEOBJDIRPREFIX} directory exists, gtags creates
@file{$MAKEOBJDIRPREFIX/<current directory>} directory and makes
tag files in it.
If dbpath is specified, this option is ignored.
@item @samp{--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 @samp{-i} option.
@item @samp{--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
@samp{--with-sqlite3} in the build phase.
@item @samp{--statistics}
Print statistics information.
@item @samp{-q}, @samp{--quiet}
Quiet mode.
@item @samp{-v}, @samp{--verbose}
Verbose mode.
@item @samp{-w}, @samp{--warning}
Print warning messages.
@item dbpath
The directory in which tag files are generated.
The default is the current directory.
@end table
@unnumberedsubsec EXAMPLES
@example
	$ ls -F
	Makefile      src/    lib/
	$ gtags -v
	$ global -x main
	main              10 src/main.c  main (argc, argv) @{
@end example
@unnumberedsubsec FILES
@table @asis
@item @file{GTAGS}
Tag file for definitions.
@item @file{GRTAGS}
Tag file for references.
@item @file{GPATH}
Tag file for source files.
@item @file{$HOME/.globalrc}, @file{gtags.conf}
Gtags load a configuration file according to the following
priority (Lower number means higher priority).
@example
		(1) $GTAGSCONF
		(2) [project root]/gtags.conf
		(3) $HOME/.globalrc
		(4) /etc/gtags.conf
		(5) [sysconfdir]/gtags.conf
@end example
@item @file{gtags.files}
The list of candidates of target files.
@end table
@unnumberedsubsec ENVIRONMENT
The following environment variables affect the execution of gtags:

@table @asis
@item @var{GTAGSCACHE}
The size of the B-tree cache. The default is 50000000 (bytes).
@item @var{GTAGSCONF}
Configuration file. The default is @file{$HOME/.globalrc}.
@item @var{GTAGSFORCECPP}
If this variable is set, each file whose suffix is @file{.h} is treated
as a C++ source file.
@item @var{GTAGSLABEL}
Configuration label. The default is @samp{default}.
@item @var{GTAGSLOGGING}
If this variable is set, @file{$GTAGSLOGGING} is used as the path name
of a log file. There is no default value.
@item @var{GTAGS_OPTIONS}
The value of this variable is inserted in the head of arguments.
@item @var{MAKEOBJDIR}
If this variable is set, @file{$MAKEOBJDIR} is used as the name
of BSD-style objdir. The default is @file{obj}.
@item @var{MAKEOBJDIRPREFIX}
If this variable is set, @file{$MAKEOBJDIRPREFIX} is used as the prefix
of BSD-style objdir. The default is @file{/usr/obj}.
@item @var{TMPDIR}
The location used to stored temporary files. The default is @file{/tmp}.
@end table
@unnumberedsubsec CONFIGURATION
The following configuration variables affect the execution of gtags.
You can see the default value for each variable with the @samp{--config} option.

@table @asis
@item @code{gtags_parser} (comma separated list)
Specify the mapping of language names and plug-in parsers.
Each part delimited by the comma consists of the 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 @code{gtags_parser} variables.
@item @code{icase_path} (boolean)
Ignore case distinctions in the path.
Suffixes check is affected by this capability.
@item @code{langmap} (comma separated list)
Language mapping. Each comma-separated map consists of
the language name, a colon, and a list of file extensions.
As a special exception, gtags collects values
from multiple @code{langmap} variables.
Default mapping is:@*
@samp{c:.c.h,yacc:.y,asm:.s.S,java:.java,cpp:.c++.cc.hh.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml}.
@item @code{skip} (comma separated list)
Gtags skips files and directories which are given in this list.
As a special exception, gtags collects values from multiple
@code{skip} variables.
If the value ends with @samp{/}, it is assumed as a directory and
gtags skips all files under it.
The value may include glob patterns (*, ?, [...], [!...], [^...]).
If the value starts with @samp{/}, it is assumed a relative path name
from the root directory of the project. You cannot use glob patterns
for a path name.
@end table

Addition to these, the variables listed in the ENVIRONMENT section except for
GTAGSCONF and GTAGSLABEL are also available as configuration variables.
Each environment variable is given more priority than configuration variable 
of the same name.
@unnumberedsubsec DIAGNOSTICS
Gtags exits with a non-0 value if an error occurred, 0 otherwise.
@unnumberedsubsec SEE ALSO
global(1),
htags(1).

GNU GLOBAL source code tag system@*
(http://www.gnu.org/software/global/).
@unnumberedsubsec BUG
@file{GTAGS} and @file{GRTAGS} are very large.
In advance of using this command, check the space of your disk.

Assembly support is far from complete.
It extracts only @code{ENTRY()} and @code{ALTENTRY()} from source file.
Probably valid only for FreeBSD and Linux kernel source.

There is no concurrency control about tag files.
@unnumberedsubsec AUTHOR
Shigio YAMAGUCHI, Hideki IWAMOTO and others.
@unnumberedsubsec HISTORY
The gtags command appeared in FreeBSD 2.2.2.
