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 is
53 --explain
55 Explain handling files.
56 -f, --file file
58 Give a list of candidates of target files. Files which are not
59 on the list are ignored. The argument file can be set to ´-´ to
60 accept a list of files from the standard input. File names must
61 be separated by newline. To make the list you may use find(1),
62 which has rich options for selecting files.
63 --gtagsconf file
65 Set environment variable GTAGSCONF to file.
66 --gtagslabel label
68 Set environment variable GTAGSLABEL to label.
69 -I, --idutils
71 In addition to tag files, make ID database for idutils(1).
72 -i, --incremental
74 Update tag files incrementally. It's better to use global(1)
75 with the -u command.
76 -O, --objdir
78 Use BSD-style objdir as the location of tag files. If ´$MAKEOB‐
79 JDIRPREFIX´ directory exists, gtags creates ´$MAKEOBJDIRPRE‐
80 FIX/<current directory>´ directory and makes tag files in it.
81 If dbpath is specified, this option is ignored.
82 --single-update file
84 Update tag files for a single file. It is considered that file
85 was added, updated or deleted, and there is no change in other
86 files. This option implies the -i option.
87 --skip-unreadable
89 Skip unreadable files.
90 --sqlite3
92 Use Sqlite 3 API to make tag files. By default, BSD/DB 1.85 API
93 is used. To use this option, you need to invoke configure
94 script with --with-sqlite3 in the build phase.
95 --statistics
97 Print statistics information.
98 -q, --quiet
100 Quiet mode.
101 -v, --verbose
103 Verbose mode.
104 -w, --warning
106 Print warning messages.
107 dbpath The directory in which tag files are generated. The default is
109 the current directory.
110
112 $ ls -F
113 Makefile src/ lib/
114 $ gtags -v
115 $ global -x main
116 main 10 src/main.c main (argc, argv) {
117
119 ´GTAGS´
120 Tag file for definitions.
121 ´GRTAGS´
123 Tag file for references.
124 ´GPATH´
126 Tag file for source files.
127 ´gtags.conf´, ´$HOME/.globalrc´
129 Configuration data for GNU GLOBAL. See gtags.conf(5).
130 ´gtags.files´
132 The list of candidates of target files.
133 ´.notfunction´
135 The list of symbols which is not a definition. If this file
136 exists in the project root directory, gtags does not regard the
137 symbols listed in this file as definitions.
138
140 The following environment variables affect the execution of gtags:
141 GTAGSCACHE
143 The size of the B-tree cache. The default is 50000000 (bytes).
144 GTAGSCONF
146 Configuration file.
147 GTAGSFORCECPP
149 If this variable is set, each file whose suffix is ´.h´ is
150 treated as a C++ source file.
151 GTAGSFORCEENDBLOCK
153 If this variable is set, each } at the first column brings end
154 of block of 0 level.
155 GTAGSLABEL
157 Configuration label. The default is ´default´.
158 GTAGSLOGGING
160 If this variable is set, ´$GTAGSLOGGING´ is used as the path
161 name of a log file. There is no default value.
162 GTAGS_COMMANDLINE
164 This variable can only be referenced from the hook (see
165 gtags_hook). Gtags sets its own effective command line to this
166 variable before calling the hook. Each argument is separated by
167 whitespace, and real whitespace is represented as '%20'. This is
168 read only.
169 GTAGS_OPTIONS
171 The value of this variable is inserted in the head of arguments.
172 MAKEOBJDIR
174 If this variable is set, ´$MAKEOBJDIR´ is used as the name of
175 BSD-style objdir. The default is ´obj´.
176 MAKEOBJDIRPREFIX
178 If this variable is set, ´$MAKEOBJDIRPREFIX´ is used as the pre‐
179 fix of BSD-style objdir. The default is ´/usr/obj´.
180 TMPDIR The location used to stored temporary files. The default is
182 ´/tmp´.
183
185 The following configuration variables affect the execution of gtags.
186 You can see the default value for each variable with the --config
187 option.
188 gtags_parser (comma separated list)
190 Specify the mapping of language names and plug-in parsers. Each
191 part delimited by the comma consists of a language name, a
192 colon, the shared object path, an optional colon followed by a
193 function name. If the function name is not specified, 'parser'
194 is assumed. As a special exception, gtags collects values from
195 multiple gtags_parser variables. For these mappings, the first
196 match is adopted.
197 gtags_hook (command line)
199 Specify a command line which should be executed at the beginning
200 of gtags after loading configuration file. You can use this hook
201 to update ´gtags.files´ dynamically. "./" in it always means
202 the project root directory, since gtags is always invoked there.
203 icase_path (boolean)
205 Ignore case distinctions in the path. Suffixes check is
206 affected by this capability.
207 langmap (comma separated list)
209 Language mapping. Each comma-separated map consists of a lan‐
210 guage name, a colon, and a list of file extensions. You can
211 specify a glob pattern surrounded by parentheses instead of an
212 extension for the files without extensions (e.g. Make:([Mm]ake‐
213 file).mak.mk). As a special exception, gtags collects values
214 from multiple langmap variables. For these mappings, the first
215 match is adopted. Default mapping is:
216 ´c:.c.h,yacc:.y,asm:.s.S,java:.java,cpp:.c++.cc.hh.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml´.
217 skip (comma separated list)
219 Gtags skips files and directories which are given in this list.
220 As a special exception, gtags collects values from multiple skip
221 variables. If the value ends with ´/´, it is assumed as a
222 directory and gtags skips all files under it. The value may
223 include glob patterns (*, ?, [...], [!...], [^...]).
224 If the value starts with ´/´, it is assumed a relative path name
226 from the root directory of the project. You cannot use glob pat‐
227 terns for a path name. However, this direction is out-of-date,
228 and is not recommended. Instead, you can use -f option which can
229 be combined with find(1). Since find(1) has rich options to
230 select files, you can do everything. Additionally, this tech‐
231 nique can also be applied to any other tagging systems like
232 ctags(1), cscope(1), etc.
233 Skip list is also effective when you use the -f or
235 ´gtags.files´.
236
238 Gtags exits with a non-0 value if an error occurred, 0 otherwise.
239 Note that files created by gtags with a non-zero exit code should be
241 considered corrupted.
242
244 global(1), htags(1), gtags.conf(5).
245 GNU GLOBAL source code tag system
247 (http://www.gnu.org/software/global/).
248
250 ´GTAGS´ and ´GRTAGS´ are very large. In advance of using this command,
251 check the space of your disk.
252 Assembly support is far from complete. It extracts only ENTRY() and
254 ALTENTRY() from source file. Probably valid only for FreeBSD and Linux
255 kernel source.
256 There is no concurrency control about tag files.
258
260 Shigio YAMAGUCHI, Hideki IWAMOTO and others.
261
263 The gtags command appeared in FreeBSD 2.2.2.
264GNU Project September 2016 GTAGS(1)