1GTAGS(1) General Commands Manual GTAGS(1)
2
6 gtags - create tag files for global
7
9 gtags [-ciIOqvw][-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 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 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
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 --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 -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 --explain
56 Explain handling files.
57 -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 --gtagsconf file
66 Set environment variable GTAGSCONF to file.
67 --gtagslabel label
69 Set environment variable GTAGSLABEL to label.
70 -I, --idutils
72 In addition to tag files, make ID database for idutils(1).
73 -i, --incremental
75 Update tag files incrementally. It's better to use global(1)
76 with the -u command.
77 -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 --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 --skip-unreadable
92 Skip unreadable files.
93 --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 --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 --statistics
106 Print statistics information.
107 -q, --quiet
109 Quiet mode.
110 -v, --verbose
112 Verbose mode.
113 -w, --warning
115 Print warning messages.
116 dbpath The directory in which tag files are generated. The default is
118 the current directory.
119
121 $ ls -F
122 Makefile src/ lib/
123 $ gtags -v
124 $ global -x main
125 main 10 src/main.c main (argc, argv) {
126
128 ´GTAGS´
129 Tag file for definitions.
130 ´GRTAGS´
132 Tag file for references.
133 ´GPATH´
135 Tag file for source files.
136 ´gtags.conf´, ´$HOME/.globalrc´
138 Configuration data for GNU GLOBAL. See gtags.conf(5).
139 ´gtags.files´
141 The list of candidates of target files.
142 ´.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
149 The following environment variables affect the execution of gtags:
150 GTAGSCACHE
152 The size of the B-tree cache. The default is 50000000 (bytes).
153 GTAGSCONF
155 Configuration file.
156 GTAGSFORCECPP
158 If this variable is set, each file whose suffix is ´.h´ is
159 treated as a C++ source file.
160 GTAGSFORCEENDBLOCK
162 If this variable is set, each } at the first column brings end
163 of block of 0 level.
164 GTAGSLABEL
166 Configuration label. The default is ´default´.
167 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 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 GTAGS_OPTIONS
180 The value of this variable is inserted in the head of arguments.
181 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 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 TMPDIR The location used to stored temporary files. The default is
193 ´/tmp´.
194
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 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 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 icase_path (boolean)
216 Ignore case distinctions in the path. Suffixes check is
217 affected by this capability.
218 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 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 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 Skip list is also effective when you use the -f or
246 ´gtags.files´.
247
249 Gtags exits with a non-0 value if an error occurred, 0 otherwise.
250 Note that files created by gtags with a non-zero exit code should be
252 considered corrupted.
253
255 global(1), htags(1), gtags.conf(5).
256 GNU GLOBAL source code tag system
258 (http://www.gnu.org/software/global/).
259
261 ´GTAGS´ and ´GRTAGS´ are very large. In advance of using this command,
262 check the space of your disk.
263 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 There is no concurrency control about tag files.
269
271 Shigio YAMAGUCHI, Hideki IWAMOTO and others.
272
274 The gtags command appeared in FreeBSD 2.2.2.
275GNU Project June 2018 GTAGS(1)