1GTAGS(1)                    General Commands Manual                   GTAGS(1)
2
3
4

NAME

6       gtags - create tag files for global
7

SYNOPSIS

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

DESCRIPTION

12       Gtags is used to create tag files for global(1).
13
14       Gtags  recursively  collects  source files under the current directory,
15       picks up symbols and writes the cross-reference data into the tag files
16       (´GTAGS´, ´GRTAGS´ and ´GPATH´).
17
18       By  default,  gtags  picks up C, Yacc, assembly language, Java, C++ and
19       PHP source files.  Files whose names end in ´.c´, ´.h´ are  assumed  to
20       be  C  source  files.   Files whose names end in ´.y´ are assumed to be
21       Yacc source files.  Files whose names end in ´.s´, ´.S´ are assumed  to
22       be  assembly  language  source files.  Files whose names end in ´.java´
23       are assumed to be Java source files.  Files whose names end in  ´.c++´,
24       ´.cc´, ´.hh´, ´.cpp´, ´.cxx´, ´.hxx´, ´.hpp´, ´.C´, ´.H´ are assumed to
25       be C++ source  files.   Files  whose  names  end  in  ´.php´,  ´.php3´,
26       ´.phtml´  are  assumed to be PHP source files.  Other files are assumed
27       to be text files. Gtags does not treat binary files.
28
29       If ´gtags.files´ exists in the current directory or a file is specified
30       by  the  -f option, target files are limited by it. Lines starting with
31       ´. ´ are comments.
32

OPTIONS

34       The following options are available:
35
36       --accept-dotfiles
37              Accept files and directories whose names begin with a  dot.   By
38              default, gtags ignores them.
39
40       -c, --compact
41              Make  ´GTAGS´ in compact format.  This option does not influence
42              ´GRTAGS´, because that is always made in compact format.
43
44       -C, --directory dir
45              Change the directory before doing all the work including parame‐
46              ter  analysis.  This option is ignored in GTAGS_OPTIONS.  Please
47              specify it on the command line directly.
48
49       --config[=name]
50              Print the value of config variable name.  If name is not  speci‐
51              fied  then print all names and values.  In addition to the vari‐
52              ables listed in the ENVIRONMENT section, you can  refer  to  in‐
53              stall  directories  by  read  only  variables:  bindir,  libdir,
54              datadir, localstatedir and sysconfdir.
55
56       -d, --dump tag-file
57              Dump a tag file as text to the standard output.   Output  format
58              is 'key<tab>data'. This is for debugging.
59
60       --explain
61              Explain handling files.
62
63       -f, --file file
64              Give  a list of candidates of target files.  Files which are not
65              on the list are ignored.  The argument file can be set to ´-´ to
66              accept a list of files from the standard input.  File names must
67              be separated by newline.  To make the list you may use  find(1),
68              which has rich options for selecting files.
69
70       --gtagsconf file
71              Set environment variable GTAGSCONF to file.
72
73       --gtagslabel label
74              Set environment variable GTAGSLABEL to label.
75
76       --help Print a usage message.
77
78       -I, --idutils
79              In addition to tag files, make ID database for idutils(1).
80
81       -i, --incremental
82              Update  tag  files  incrementally.  It's better to use global(1)
83              with the -u command.
84
85       -O, --objdir
86              Use BSD-style obj directory as the location of  tag  files.   If
87              GTAGSOBJDIRPREFIX  is set and ´$GTAGSOBJDIRPREFIX´ directory ex‐
88              ists, gtags creates ´$GTAGSOBJDIRPREFIX/<current directory>´ di‐
89              rectory  and  makes tag files in it.  Though you can use MAKEOB‐
90              JDIRPREFIX instead of GTAGSOBJDIRPREFIX, it is  deprecated.   If
91              dbpath is specified, this option is ignored.
92
93       --single-update file
94              Update  tag files for a single file.  It is considered that file
95              was added, updated or deleted, and there is no change  in  other
96              files.  This option implies the -i option.
97
98       --skip-unreadable
99              Skip unreadable files.
100
101       --skip-symlink [=type]
102              Skip  symbolic  links.  If  type  is 'f' then skip only symbolic
103              links for file, else if 'd' then skip only  symbolic  links  for
104              directory.   The  default  value  of  type  is 'a' (all symbolic
105              links).
106
107       --sqlite3
108              Use Sqlite 3 API to make tag files. By default, BSD/DB 1.85  API
109              is  used.   To  use  this  option,  you need to invoke configure
110              script with --with-sqlite3 in the build phase.
111
112       --statistics
113              Print statistics information.
114
115       -q, --quiet
116              Quiet mode.
117
118       -v, --verbose
119              Verbose mode.
120
121       --version
122              Show version number.
123
124       -w, --warning
125              Print warning messages.
126
127       dbpath The directory in which tag files are generated.  The default  is
128              the current directory.
129

EXAMPLES

131       $ ls -F
132       Makefile      src/    lib/
133       $ gtags -v
134       $ global -x main
135       main              10 src/main.c  main (argc, argv) {
136

FILES

138       ´GTAGS´
139              Tag file for definitions.
140
141       ´GRTAGS´
142              Tag file for references.
143
144       ´GPATH´
145              Tag file for source files.
146
147       ´gtags.conf´, ´$HOME/.globalrc´
148              Configuration data for GNU GLOBAL.  See gtags.conf(5).
149
150       ´gtags.files´
151              The list of candidates of target files.
152
153       ´.notfunction´
154              The list of symbols which is not a definition.  If this file ex‐
155              ists in the project root directory, gtags does  not  regard  the
156              symbols listed in this file as definitions.
157

ENVIRONMENT

159       The following environment variables affect the execution of gtags:
160
161       GTAGSCACHE
162              The size of the B-tree cache. The default is 50000000 (bytes).
163
164       GTAGSCONF
165              Configuration file.
166
167       GTAGSFORCECPP
168              If  this  variable  is  set,  each  file whose suffix is ´.h´ is
169              treated as a C++ source file.
170
171       GTAGSFORCEENDBLOCK
172              If this variable is set, each } at the first column  brings  end
173              of block of 0 level.
174
175       GTAGSLABEL
176              Configuration label. The default is ´default´.
177
178       GTAGSLOGGING
179              If  this  variable  is  set, ´$GTAGSLOGGING´ is used as the path
180              name of a log file. There is no default value.
181
182       GTAGS_COMMANDLINE
183              This  variable  can  only  be  referenced  from  the  hook  (see
184              gtags_hook).   Gtags sets its own effective command line to this
185              variable before calling the hook. Each argument is separated  by
186              whitespace, and real whitespace is represented as '%20'. This is
187              read only.
188
189       GTAGS_OPTIONS
190              The value of this variable is inserted in the head of arguments.
191
192       GTAGSOBJDIR
193              If this variable is set, it is used as the name of BSD-style ob‐
194              jdir.   The default is ´obj´.  Though you can use MAKEOBJDIR in‐
195              stead of GTAGSOBJDIR, it is deprecated.
196
197       GTAGSOBJDIRPREFIX
198              If this variable is set, it is used as the prefix  of  BSD-style
199              objdir.   The default is ´/usr/obj´.  Though you can use MAKEOB‐
200              JDIRPREFIX instead of GTAGSOBJDIRPREFIX, it is deprecated.
201
202       TMPDIR The location used to stored  temporary  files.  The  default  is
203              ´/tmp´.
204

CONFIGURATION

206       The  following  configuration  variables affect the execution of gtags.
207       You can see the default value for each variable with the  --config  op‐
208       tion.
209
210       gtags_parser (comma separated list)
211              Specify the mapping of language names and plug-in parsers.  Each
212              part delimited by the comma  consists  of  a  language  name,  a
213              colon,  the  shared object path, an optional colon followed by a
214              function name.  If the function name is not specified,  'parser'
215              is  assumed.  As a special exception, gtags collects values from
216              multiple gtags_parser variables.  For these mappings, the  first
217              match is adopted.
218
219       gtags_hook (command line)
220              Specify a command line which should be executed at the beginning
221              of gtags after loading configuration file. You can use this hook
222              to  update  ´gtags.files´  dynamically.  "./" in it always means
223              the project root directory, since gtags is always invoked there.
224
225              This hook is ignored when the following options  are  specified:
226              --version, --help, --config, --dump.
227
228       icase_path (boolean)
229              Ignore  case  distinctions  in  the path.  Suffixes check is af‐
230              fected by this capability.
231
232       langmap (comma separated list)
233              Language mapping. Each comma-separated map consists  of  a  lan‐
234              guage  name,  a  colon,  and a list of file extensions.  You can
235              specify a glob pattern surrounded by parentheses instead  of  an
236              extension  for the files without extensions (e.g. Make:([Mm]ake‐
237              file).mak.mk).  As a special exception,  gtags  collects  values
238              from  multiple langmap variables.  For these mappings, the first
239              match is adopted.  Default mapping is:
240              ´c:.c.h,yacc:.y,asm:.s.S,java:.java,cpp:.c++.cc.hh.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml´.
241
242       skip (comma separated list)
243              Gtags  skips files and directories which are given in this list.
244              As a special exception, gtags collects values from multiple skip
245              variables.   If  the value ends with ´/´, it is assumed as a di‐
246              rectory and gtags skips all files under it.  The value  may  in‐
247              clude glob patterns (*, ?, [...], [!...], [^...]).
248
249              If the value starts with ´/´, it is assumed a relative path name
250              from the root directory of the project. You cannot use glob pat‐
251              terns  for  a path name. However, this direction is out-of-date,
252              and is not recommended. Instead, you can use -f option which can
253              be  combined with find(1). Since find(1) has rich options to se‐
254              lect files, you can do everything. Additionally, this  technique
255              can  also be applied to any other tagging systems like ctags(1),
256              cscope(1), etc.
257
258              Skip  list  is  also  effective  when  you   use   the   -f   or
259              ´gtags.files´.
260

DIAGNOSTICS

262       Gtags exits with a non-0 value if an error occurred, 0 otherwise.
263
264       Note  that  files  created by gtags with a non-zero exit code should be
265       considered corrupted.
266

SEE ALSO

268       global(1), htags(1), gtags.conf(5).
269
270       GNU GLOBAL source code tag system
271       (http://www.gnu.org/software/global/).
272

BUG

274       ´GTAGS´ and ´GRTAGS´ are very large.  In advance of using this command,
275       check the space of your disk.
276
277       Assembly  language  support is far from complete.  It extracts only EN‐
278       TRY() and ALTENTRY() from source file.  Probably valid only for FreeBSD
279       and Linux kernel source.
280
281       C++ support is deprecated.
282
283       There is no concurrency control about tag files.
284

AUTHOR

286       Shigio YAMAGUCHI, Hideki IWAMOTO and others.
287

HISTORY

289       The gtags command appeared in FreeBSD 2.2.2.
290
291
292
293GNU Project                        June 2018                          GTAGS(1)
Impressum