Provided by: global_6.6.3-2_amd64 bug

NAME

       gtags - create tag files for global

SYNOPSIS

       gtags [-ciIOqvw][-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´).

       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.

       C, yacc, Assembly, Java, C++ and PHP source files are supported.  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
       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.

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.

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

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

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

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 treated as a C++  source
              file.

       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.

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

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.

SEE ALSO

       global(1), htags(1), gtags.conf(5).

       GNU GLOBAL source code tag system
       (http://www.gnu.org/software/global/).

BUG

       ´GTAGS´ and ´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  ENTRY()  and  ALTENTRY()  from
       source file.  Probably valid only for FreeBSD and Linux kernel source.

       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.