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

NAME

6       gtags - create tag files for global
7

SYNOPSIS

9       gtags [-ciIOqvw][-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       If ´gtags.files´ exists in the current directory or a file is specified
19       by the -f option, target files are limited by it. Lines  starting  with
20       ´. ´ are comments.
21
22       C, yacc, Assembly, Java, C++ and PHP source files are supported.  Files
23       whose names end in ´.c´, ´.h´ are assumed to be C source files.   Files
24       whose  names  end  in  ´.y´ are assumed to be yacc source files.  Files
25       whose names end in ´.s´, ´.S´ are assumed to be Assembly source  files.
26       Files  whose  names end in ´.java´ are assumed to be Java source files.
27       Files whose names end in ´.c++´, ´.cc´, ´.hh´, ´.cpp´, ´.cxx´,  ´.hxx´,
28       ´.hpp´,  ´.C´,  ´.H´  are  assumed to be C++ source files.  Files whose
29       names end in ´.php´, ´.php3´, ´.phtml´ are assumed  to  be  PHP  source
30       files.   Other files are assumed to be text files. Gtags does not treat
31       binary files.
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       --config[=name]
45              Print the value of config variable name.  If name is not  speci‐
46              fied  then print all names and values.  In addition to the vari‐
47              ables listed in  the  ENVIRONMENT  section,  you  can  refer  to
48              install  directories  by  read  only  variables: bindir, libdir,
49              datadir, localstatedir and sysconfdir.
50
51       -d, --dump tag-file
52              Dump a tag file as text to the standard output.   Output  format
53              is 'key<tab>data'. This is for debugging.
54
55       --explain
56              Explain handling files.
57
58       -f, --file file
59              Give  a list of candidates of target files.  Files which are not
60              on the list are ignored.  The argument file can be set to ´-´ to
61              accept a list of files from the standard input.  File names must
62              be separated by newline.  To make the list you may use  find(1),
63              which has rich options for selecting files.
64
65       --gtagsconf file
66              Set environment variable GTAGSCONF to file.
67
68       --gtagslabel label
69              Set environment variable GTAGSLABEL to label.
70
71       -I, --idutils
72              In addition to tag files, make ID database for idutils(1).
73
74       -i, --incremental
75              Update  tag  files  incrementally.  It's better to use global(1)
76              with the -u command.
77
78       -O, --objdir
79              Use BSD-style obj directory as the location of  tag  files.   If
80              GTAGSOBJDIRPREFIX  is  set  and  ´$GTAGSOBJDIRPREFIX´  directory
81              exists, gtags creates  ´$GTAGSOBJDIRPREFIX/<current  directory>´
82              directory and makes tag files in it.  Though you can use MAKEOB‐
83              JDIRPREFIX instead of GTAGSOBJDIRPREFIX, it is  deprecated.   If
84              dbpath is specified, this option is ignored.
85
86       --single-update file
87              Update  tag files for a single file.  It is considered that file
88              was added, updated or deleted, and there is no change  in  other
89              files.  This option implies the -i option.
90
91       --skip-unreadable
92              Skip unreadable files.
93
94       --skip-symlink [=type]
95              Skip  symbolic  links.  If  type  is 'f' then skip only symbolic
96              links for file, else if 'd' then skip only  symbolic  links  for
97              directory.   The  default  value  of  type  is 'a' (all symbolic
98              links).
99
100       --sqlite3
101              Use Sqlite 3 API to make tag files. By default, BSD/DB 1.85  API
102              is  used.   To  use  this  option,  you need to invoke configure
103              script with --with-sqlite3 in the build phase.
104
105       --statistics
106              Print statistics information.
107
108       -q, --quiet
109              Quiet mode.
110
111       -v, --verbose
112              Verbose mode.
113
114       -w, --warning
115              Print warning messages.
116
117       dbpath The directory in which tag files are generated.  The default  is
118              the current directory.
119

EXAMPLES

121       $ ls -F
122       Makefile      src/    lib/
123       $ gtags -v
124       $ global -x main
125       main              10 src/main.c  main (argc, argv) {
126

FILES

128       ´GTAGS´
129              Tag file for definitions.
130
131       ´GRTAGS´
132              Tag file for references.
133
134       ´GPATH´
135              Tag file for source files.
136
137       ´gtags.conf´, ´$HOME/.globalrc´
138              Configuration data for GNU GLOBAL.  See gtags.conf(5).
139
140       ´gtags.files´
141              The list of candidates of target files.
142
143       ´.notfunction´
144              The  list  of  symbols  which is not a definition.  If this file
145              exists in the project root directory, gtags does not regard  the
146              symbols listed in this file as definitions.
147

ENVIRONMENT

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

CONFIGURATION

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

DIAGNOSTICS

249       Gtags exits with a non-0 value if an error occurred, 0 otherwise.
250
251       Note that files created by gtags with a non-zero exit  code  should  be
252       considered corrupted.
253

SEE ALSO

255       global(1), htags(1), gtags.conf(5).
256
257       GNU GLOBAL source code tag system
258       (http://www.gnu.org/software/global/).
259

BUG

261       ´GTAGS´ and ´GRTAGS´ are very large.  In advance of using this command,
262       check the space of your disk.
263
264       Assembly support is far from complete.  It extracts  only  ENTRY()  and
265       ALTENTRY() from source file.  Probably valid only for FreeBSD and Linux
266       kernel source.
267
268       There is no concurrency control about tag files.
269

AUTHOR

271       Shigio YAMAGUCHI, Hideki IWAMOTO and others.
272

HISTORY

274       The gtags command appeared in FreeBSD 2.2.2.
275
276
277
278GNU Project                        June 2018                          GTAGS(1)
Impressum