1GTAGS(1) General Commands Manual GTAGS(1)
2
6 gtags - create tag files for global
7
9 gtags [-ciIOqvw][-C dir][-d tag-file][-f file][dbpath]
10
12 Gtags is used to create tag files for global(1).
13 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 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 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
34 The following options are available:
35 --accept-dotfiles
37 Accept files and directories whose names begin with a dot. By
38 default, gtags ignores them.
39 -c, --compact
41 Make ´GTAGS´ in compact format. This option does not influence
42 ´GRTAGS´, because that is always made in compact format.
43 -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 --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 -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 --explain
61 Explain handling files.
62 -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 --gtagsconf file
71 Set environment variable GTAGSCONF to file.
72 --gtagslabel label
74 Set environment variable GTAGSLABEL to label.
75 --help Print a usage message.
77 -I, --idutils
79 In addition to tag files, make ID database for idutils(1).
80 -i, --incremental
82 Update tag files incrementally. It's better to use global(1)
83 with the -u command.
84 -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 --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 --skip-unreadable
99 Skip unreadable files.
100 --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 --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 --statistics
113 Print statistics information.
114 -q, --quiet
116 Quiet mode.
117 -v, --verbose
119 Verbose mode.
120 --version
122 Show version number.
123 -w, --warning
125 Print warning messages.
126 dbpath The directory in which tag files are generated. The default is
128 the current directory.
129
131 $ ls -F
132 Makefile src/ lib/
133 $ gtags -v
134 $ global -x main
135 main 10 src/main.c main (argc, argv) {
136
138 ´GTAGS´
139 Tag file for definitions.
140 ´GRTAGS´
142 Tag file for references.
143 ´GPATH´
145 Tag file for source files.
146 ´gtags.conf´, ´$HOME/.globalrc´
148 Configuration data for GNU GLOBAL. See gtags.conf(5).
149 ´gtags.files´
151 The list of candidates of target files.
152 ´.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
159 The following environment variables affect the execution of gtags:
160 GTAGSCACHE
162 The size of the B-tree cache. The default is 50000000 (bytes).
163 GTAGSCONF
165 Configuration file.
166 GTAGSFORCECPP
168 If this variable is set, each file whose suffix is ´.h´ is
169 treated as a C++ source file.
170 GTAGSFORCEENDBLOCK
172 If this variable is set, each } at the first column brings end
173 of block of 0 level.
174 GTAGSLABEL
176 Configuration label. The default is ´default´.
177 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 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 GTAGS_OPTIONS
190 The value of this variable is inserted in the head of arguments.
191 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 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 TMPDIR The location used to stored temporary files. The default is
203 ´/tmp´.
204
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 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 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 This hook is ignored when the following options are specified:
226 --version, --help, --config, --dump.
227 icase_path (boolean)
229 Ignore case distinctions in the path. Suffixes check is af‐
230 fected by this capability.
231 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 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 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 Skip list is also effective when you use the -f or
259 ´gtags.files´.
260
262 Gtags exits with a non-0 value if an error occurred, 0 otherwise.
263 Note that files created by gtags with a non-zero exit code should be
265 considered corrupted.
266
268 global(1), htags(1), gtags.conf(5).
269 GNU GLOBAL source code tag system
271 (http://www.gnu.org/software/global/).
272
274 ´GTAGS´ and ´GRTAGS´ are very large. In advance of using this command,
275 check the space of your disk.
276 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 C++ support is deprecated.
282 There is no concurrency control about tag files.
284
286 Shigio YAMAGUCHI, Hideki IWAMOTO and others.
287
289 The gtags command appeared in FreeBSD 2.2.2.
290GNU Project June 2018 GTAGS(1)