1GLOBAL(1) General Commands Manual GLOBAL(1)
2
6 global - print locations of given symbols
7
9 global [-adEFGilMnNqrstTvx][-S dir][-e] pattern
10 global -c[dFiIMoOPrsT] prefix
11 global -f[adlnqrstvx][-L file-list][-S dir] files
12 global -g[aEGilMnoOqtvVx][-L file-list][-S dir][-e] pattern [files]
13 global -I[ailMnqtvx][-S dir][-e] pattern
14 global -P[aEGilMnoOqtvVx][-S dir][-e] pattern
15 global -p[qrv]
16 global -u[qv]
17
19 Global finds locations of given symbols in C, C++, Yacc, Java, PHP and
20 Assembly source files, and prints the path name, line number and line
21 image of the locations. Global can locate not only definitions but
22 also references and other symbols.
23 Global can treat a source tree, that is, a directory that has sub-
25 directories and source files, as a project. In advance of using this
26 command, you must execute gtags(1) at the root directory of the project
27 which you want to investigate to make tag files. Then you can use
28 global command anywhere in the project. You need not specify where the
29 tag file is. Instead, global locates it by itself.
30 You can specify a regular expression for pattern. Global understands
32 two different versions of regular expression syntax: basic and extended
33 (default).
34
36 The following commands are available:
37 <no command> pattern
39 No command means tag search command. Print tags which match to
40 pattern. By default, print definition tags.
41 -c, --completion [prefix]
43 Print symbols which start with prefix. If prefix is not given,
44 print all symbols.
45 -f, --file files
47 Print all tags in the files. This command implies the -x
48 option.
49 -g, --grep pattern [files]
51 Print all lines which match to the pattern. If files are given,
52 this command searches in those files.
53 --help Print a usage message.
55 -I, --idutils pattern
57 Print all lines which match to pattern. This function uses idu‐
58 tils(1) as a search engine. To use this command, you need to
59 install idutils(1) in your system and execute gtags(1) with the
60 -I option.
61 -P, --path [pattern]
63 Print path names which match to pattern. If no pattern is
64 given, print all paths in the project.
65 -p, --print-dbpath
67 Print location of ´GTAGS´.
68 --print name
70 Print location of name, which may be one of: ´root´, ´dbpath´ or
71 ´conf´. ´root´ means project's root directory. ´dbpath´ means a
72 directory where tag databases exist. ´conf´ means configuration
73 file.
74 -u, --update
76 Update tag files incrementally. This command internally invokes
77 gtags(1). You can execute this command anywhere in the project,
78 differing from gtags(1).
79 --version
81 Show version number.
82
84 The following options are available:
85 -a, --absolute
87 Print absolute path names. By default, print relative path
88 names.
89 --color when
91 Use color to highlight the pattern within the line; when may be
92 one of: never, always or auto (default). The default color is
93 bold red text on current background; the environment variable
94 GREP_COLORS (only mt and ms are effective at present) or
95 GREP_COLOR defines it. This option is effective to the follow‐
96 ing commands: <no command>, -f, -g, -I, -P.
97 -d, --definition
99 Print locations of definitions.
100 -e, --regexp pattern
102 Use pattern as the pattern; useful to protect patterns starting
103 with ´-´.
104 -E, --extended-regexp
106 Interpret pattern as a extended regular expression. This is the
107 default.
108 --encode-path chars
110 Convert path characters in chars into a ´%´ symbol, followed by
111 the two-digit hexadecimal representation of the character. A
112 blank will be converted to ´%20´.
113 -F, --first-match
115 End the search without going through all the tag files listed in
116 GTAGSLIBPATH when tags are found in a tag file. This is the
117 default.
118 --from-here context
120 Decide tag type by context. Its syntax should be ´lineno:path´.
121 If the context is a definition of the pattern then use -r, else
122 if there is at least one definition of the pattern then use -d,
123 else use -s. If this option is specified then -d, -r and -s on
124 the command line are ignored. Regular expression is not allowed
125 for pattern. This option assumes use in conversational environ‐
126 ments such as editors and IDEs.
127 -G, --basic-regexp
129 Interpret pattern as a basic regular expression. The default is
130 an extended regular expression.
131 --gtagsconf file
133 Set environment variable GTAGSCONF to file.
134 --gtagslabel label
136 Set environment variable GTAGSLABEL to label.
137 -i, --ignore-case
139 Ignore case distinctions in the pattern.
140 -L, --file-list file
142 Obtain files from file in addition to the arguments. The argu‐
143 ment file can be set to '-' to accept a list of files from the
144 standard input. File names must be separated by newline.
145 -l, --local
147 Print only tags which exist under the current directory.
148 --literal
150 Execute literal search instead of regular expression search.
151 This option works with the tag search command, -g command, -P
152 command and -I command.
153 -M, --match-case
155 Search is case-sensitive. This is the default.
156 --match-part part
158 Specify how path name completion should match, where part is one
159 of: ´first´, ´last´ or ´all´ (default). This option is valid
160 only with the -c command in conjunction with -P.
161 -n, --nofilter
163 Suppress sort filter and path conversion filter.
164 -N, --nearness[=start]
166 Use Nearness sort method (sorting by closest from start) for the
167 output. By default, alphabetical sort method is used. This
168 option is effective for the tag search command, -P command and
169 -g command. As an exception, -g command ignores this option when
170 files are specified by arguments. The nearness is defined by
171 how many parent directories to go up to reach the target. The
172 result of nearness sort is concatenation of the following
173 ([0]-[n]) in this order. The default of start is the current
174 directory.
175 [0] If the start is a file, output of local search in the file.
176 [1] Output of local search in the start directory except for [0].
177 [2] Output of local search in the parent directory except for [0]-[1].
178 [3] Output of local search in the grandparent directory except for [0]-[2].
179 ... (repeat until the project root directory)
180 [n] Output of local search in the project root directory except for [0]-[n-1].
181 In each directory, they are sorted by alphabetical order.
182 -O, --only-other
184 Treat only text files other than source code, like ´README´.
185 This option is valid only with the -g or -P command. This
186 option overrides the -o option.
187 -o, --other
189 Treat not only source files but also text files other than
190 source code, like ´README´. This option is valid only with the
191 -g or -P command.
192 --path-style format
194 Print path names using format, which may be one of: ´relative´,
195 ´absolute´, ´shorter´, ´abslib´ or ´through´. ´relative´ means
196 relative path. ´absolute´ means absolute path. ´shorter´ means
197 the shorter one of relative and absolute path. ´abslib´ means
198 absolute path for libraries (GTAGSLIBPATH) and relative path for
199 the rest. ´through´ means the relative path from the project
200 root directory (internal format of GPATH). The default is ´rel‐
201 ative´. The --path-style option is given more priority than the
202 -a option.
203 --print0
205 Print each record followed by a null character instead of a new‐
206 line.
207 -q, --quiet
209 Quiet mode.
210 -r, --reference, --rootdir
212 Print reference tags. Reference means the reference to a symbol
213 which has definitions. With the -p option, print the root
214 directory of the project.
215 --result format
217 Print out using format, which may be one of: ´path´ (default),
218 ´ctags´, ´ctags-x´, ´grep´ or ´cscope´. The --result=ctags and
219 --result=ctags-x options are equivalent to the -t and -x options
220 respectively. The --result option is given more priority than
221 the -t and -x options.
222 --single-update file
224 Update tag files using gtags(1) with the --single-update option.
225 It is considered that file was added, updated or deleted, and
226 there is no change in other files. This option implies the -u
227 option.
228 -s, --symbol
230 Print other symbol tags. Other symbol means the reference to a
231 symbol which has no definition.
232 -S, --scope dir
234 Print only tags which exist under dir directory. It is similar
235 to the -l option, but you need not change directory.
236 -T, --through
238 Go through all the tag files listed in GTAGSLIBPATH. By
239 default, stop searching when tag is found. This option is
240 ignored when either -s, -r or -l option is specified.
241 -t, --tags
243 Use standard ctags format.
244 -V, --invert-match
246 Invert the sense of matching, to select non-matching lines.
247 This option is valid only with the -g or -P commands.
248 -v, --verbose
250 Verbose mode.
251 -x, --cxref
253 Use standard ctags cxref (with -x) format.
254
256 $ ls -F
257 Makefile src/ lib/
258 $ gtags
259 $ ls G*
260 GPATH GRTAGS GTAGS
261 $ global main
262 src/main.c
263 $ (cd src; global main)
264 main.c
265 $ global -x main
266 main 10 src/main.c main (argc, argv) {
267 $ global -f src/main.c
268 main 10 src/main.c main (argc, argv) {
269 func1 55 src/main.c func1() {
270 func2 72 src/main.c func2() {
271 func3 120 src/main.c func3() {
272 $ global -x '^[sg]et'
273 set_num 20 lib/util.c set_num(values) {
274 get_num 30 lib/util.c get_num() {
275 $ global -rx set_num
276 set_num 113 src/op.c set_num(32);
277 set_num 225 src/opop.c if (set_num(0) > 0) {
278 $ global strlen
279 $ (cd /usr/src/sys; gtags)
280 $ export GTAGSLIBPATH=/usr/src/sys
281 $ global -a strlen
282 /usr/src/sys/libkern/strlen.c
283 $ (cd /usr/src/lib; gtags)
284 $ GTAGSLIBPATH=/usr/src/lib:/usr/src/sys
285 $ global -a strlen
286 /usr/src/lib/libc/string/strlen.c
287
289 ´GTAGS´
290 Tag file for definitions.
291 ´GRTAGS´
293 Tag file for references.
294 ´GPATH´
296 Tag file for source files.
297 ´GTAGSROOT´
299 If environment variable GTAGSROOT is not set and file ´GTAGS‐
300 ROOT´ exists in the same directory as ´GTAGS´ then global sets
301 GTAGSROOT to the contents of the file.
302 ´gtags.conf´, ´$HOME/.globalrc´
304 Configuration data for GNU GLOBAL. See gtags.conf(5).
305
307 The following environment variables affect the execution of global:
308 GREP_COLOR
310 The color to use for --color; GREP_COLORS has precedence.
311 GREP_COLORS
313 The color (mt or ms) to use for --color; see grep(1).
314 GTAGSBLANKENCODE
316 If this variable is set, the --encode-path=" <TAB>" option is
317 specified.
318 GTAGSCACHE
320 The size of the B-tree cache. The default is 50000000 (bytes).
321 GTAGSCONF
323 Configuration file.
324 GTAGSDBPATH
326 The directory in which the tag files exist. This value is
327 ignored when GTAGSROOT is not defined. Use of this variable is
328 not recommended.
329 GTAGSFORCECPP
331 If this variable is set, each file whose suffix is ´.h´ is
332 treated as a C++ source file.
333 GTAGSLABEL
335 Configuration label. The default is default.
336 GTAGSLIBPATH
338 If this variable is set, it is used as the path to search for
339 library functions. If the given symbol is not found in the
340 project, global also searches in these paths. Since only
341 ´GTAGS´ is targeted in the retrieval, this variable is ignored
342 when -r or -s is specified.
343 GTAGSLOGGING
345 If this variable is set, ´$GTAGSLOGGING´ is used as the path
346 name of a log file. There is no default value.
347 GTAGSROOT
349 The root directory of the project. Usually, it is recognized by
350 existence of ´GTAGS´. Use of this variable is not recommended.
351 GTAGSTHROUGH
353 If this variable is set, the -T option is specified.
354 GTAGSOBJDIR, MAKEOBJDIR
356 If eigher of the two variable is set, it is used as the name of
357 BSD-style objdir. The former is given priority. The default is
358 ´obj´.
359 GTAGSOBJDIRPREFIX, MAKEOBJDIRPREFIX
361 If eigher of the two variable is set, it is used as the prefix
362 of BSD-style objdir. The former is given priority. The default
363 is ´/usr/obj´.
364
366 The following configuration variables affect the execution of global:
367 icase_path (boolean)
369 Ignore case distinctions in pattern.
370
372 Global exits with a non-0 value if an error occurred, 0 otherwise.
373
375 gtags(1), htags(1), less(1), gtags.conf(5).
376 GNU GLOBAL source code tag system
378 (http://www.gnu.org/software/global/).
379
381 Shigio YAMAGUCHI, Hideki IWAMOTO and others.
382
384 The global command appeared in FreeBSD 2.2.2.
385GNU Project May 2015 GLOBAL(1)