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, Yacc, Java, PHP and as‐
20 sembly source files, and prints the path name, line number and line im‐
21 age of the locations. Global can locate not only definitions but also
22 references and other symbols.
23 Global can treat a source tree, that is, a directory that has sub-di‐
25 rectories 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 op‐
48 tion.
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 -C, --directory dir
99 Change the directory before doing all the work including parame‐
100 ter analysis.
101 -d, --definition
103 Print locations of definitions.
104 -e, --regexp pattern
106 Use pattern as the pattern; useful to protect patterns starting
107 with ´-´.
108 -E, --extended-regexp
110 Interpret pattern as a extended regular expression. This is the
111 default.
112 --encode-path chars
114 Convert path characters in chars into a ´%´ symbol, followed by
115 the two-digit hexadecimal representation of the character. A
116 blank will be converted to ´%20´.
117 -F, --first-match
119 End the search without going through all the tag files listed in
120 GTAGSLIBPATH when tags are found in a tag file. This is the de‐
121 fault.
122 --from-here context
124 Decide tag type by context. Its syntax should be ´lineno:path´.
125 If the context is a definition of the pattern then use -r, else
126 if there is at least one definition of the pattern then use -d,
127 else use -s. If this option is specified then -d, -r and -s on
128 the command line are ignored. Regular expression is not allowed
129 for pattern. This option assumes use in conversational environ‐
130 ments such as editors and IDEs.
131 -G, --basic-regexp
133 Interpret pattern as a basic regular expression. The default is
134 an extended regular expression.
135 --gtagsconf file
137 Set environment variable GTAGSCONF to file.
138 --gtagslabel label
140 Set environment variable GTAGSLABEL to label.
141 -i, --ignore-case
143 Ignore case distinctions in the pattern.
144 -L, --file-list file
146 Obtain files from file in addition to the arguments. The argu‐
147 ment file can be set to '-' to accept a list of files from the
148 standard input. File names must be separated by newline.
149 -l, --local
151 Print only tags which exist under the current directory.
152 --literal
154 Execute literal search instead of regular expression search.
155 This option works with the tag search command, -g command, -P
156 command and -I command.
157 -M, --match-case
159 Search is case-sensitive. This is the default.
160 --match-part part
162 Specify how path name completion should match, where part is one
163 of: ´first´, ´last´ or ´all´ (default). This option is valid
164 only with the -c command in conjunction with -P.
165 -n, --nofilter
167 Suppress sort filter and path conversion filter.
168 -N, --nearness[=start]
170 Use Nearness sort method (sorting by closest from start) for the
171 output. By default, alphabetical sort method is used. This op‐
172 tion is effective for the tag search command, -P command and -g
173 command. As an exception, -g command ignores this option when
174 files are specified by arguments. The nearness is defined by
175 how many parent directories to go up to reach the target. The
176 result of nearness sort is concatenation of the following
177 ([0]-[n]) in this order. The default of start is the current di‐
178 rectory.
179 [0] If the start is a file, output of local search in the file.
180 [1] Output of local search in the start directory except for [0].
181 [2] Output of local search in the parent directory except for [0]-[1].
182 [3] Output of local search in the grandparent directory except for [0]-[2].
183 ... (repeat until the project root directory)
184 [n] Output of local search in the project root directory except for [0]-[n-1].
185 In each directory, they are sorted by alphabetical order.
186 -O, --only-other
188 Treat only text files other than source code, like ´README´.
189 This option is valid only with the -g or -P command. This op‐
190 tion overrides the -o option.
191 -o, --other
193 Treat not only source files but also text files other than
194 source code, like ´README´. This option is valid only with the
195 -g or -P command.
196 --path-style format
198 Print path names using format, which may be one of: ´relative´,
199 ´absolute´, ´shorter´, ´abslib´ or ´through´. ´relative´ means
200 relative path. ´absolute´ means absolute path. ´shorter´ means
201 the shorter one of relative and absolute path. ´abslib´ means
202 absolute path for libraries (GTAGSLIBPATH) and relative path for
203 the rest. ´through´ means the relative path from the project
204 root directory (internal format of GPATH). The default is ´rel‐
205 ative´. The --path-style option is given more priority than the
206 -a option.
207 --print0
209 Print each record followed by a null character instead of a new‐
210 line.
211 -q, --quiet
213 Quiet mode.
214 -r, --reference, --rootdir
216 Print reference tags. Reference means the reference to a symbol
217 which has definitions. With the -p option, print the root di‐
218 rectory of the project.
219 --result format
221 Print out using format, which may be one of: ´path´ (default),
222 ´ctags´, ´ctags-x´, ´grep´ or ´cscope´. The --result=ctags and
223 --result=ctags-x options are equivalent to the -t and -x options
224 respectively. The --result option is given more priority than
225 the -t and -x options.
226 --single-update file
228 Update tag files using gtags(1) with the --single-update option.
229 It is considered that file was added, updated or deleted, and
230 there is no change in other files. This option implies the -u
231 option.
232 -s, --symbol
234 Print other symbol tags. Other symbol means the reference to a
235 symbol which has no definition.
236 -S, --scope dir
238 Print only tags which exist under dir directory. It is similar
239 to the -l option, but you need not change directory.
240 -T, --through
242 Go through all the tag files listed in GTAGSLIBPATH. By de‐
243 fault, stop searching when tag is found. This option is ignored
244 when either -s, -r or -l option is specified.
245 -t, --tags
247 Use standard ctags format.
248 -V, --invert-match
250 Invert the sense of matching, to select non-matching lines.
251 This option is valid only with the -g or -P commands.
252 -v, --verbose
254 Verbose mode.
255 -x, --cxref
257 Use standard ctags cxref (with -x) format.
258
260 $ ls -F
261 Makefile src/ lib/
262 $ gtags
263 $ ls G*
264 GPATH GRTAGS GTAGS
265 $ global main
266 src/main.c
267 $ (cd src; global main)
268 main.c
269 $ global -x main
270 main 10 src/main.c main (argc, argv) {
271 $ global -f src/main.c
272 main 10 src/main.c main (argc, argv) {
273 func1 55 src/main.c func1() {
274 func2 72 src/main.c func2() {
275 func3 120 src/main.c func3() {
276 $ global -x '^[sg]et'
277 set_num 20 lib/util.c set_num(values) {
278 get_num 30 lib/util.c get_num() {
279 $ global -rx set_num
280 set_num 113 src/op.c set_num(32);
281 set_num 225 src/opop.c if (set_num(0) > 0) {
282 $ global strlen
283 $ (cd /usr/src/sys; gtags)
284 $ export GTAGSLIBPATH=/usr/src/sys
285 $ global -a strlen
286 /usr/src/sys/libkern/strlen.c
287 $ (cd /usr/src/lib; gtags)
288 $ GTAGSLIBPATH=/usr/src/lib:/usr/src/sys
289 $ global -a strlen
290 /usr/src/lib/libc/string/strlen.c
291
293 ´GTAGS´
294 Tag file for definitions.
295 ´GRTAGS´
297 Tag file for references.
298 ´GPATH´
300 Tag file for source files.
301 ´GTAGSROOT´
303 If environment variable GTAGSROOT is not set and file ´GTAGS‐
304 ROOT´ exists in the same directory as ´GTAGS´ then global sets
305 GTAGSROOT to the contents of the file.
306 ´gtags.conf´, ´$HOME/.globalrc´
308 Configuration data for GNU GLOBAL. See gtags.conf(5).
309
311 The following environment variables affect the execution of global:
312 GREP_COLOR
314 The color to use for --color; GREP_COLORS has precedence.
315 GREP_COLORS
317 The color (mt or ms) to use for --color; see grep(1).
318 GTAGSBLANKENCODE
320 If this variable is set, the --encode-path=" <TAB>" option is
321 specified.
322 GTAGSCACHE
324 The size of the B-tree cache. The default is 50000000 (bytes).
325 GTAGSCONF
327 Configuration file.
328 GTAGSDBPATH
330 The directory in which the tag files exist. This value is ig‐
331 nored when GTAGSROOT is not defined. Use of this variable is
332 not recommended.
333 GTAGSFORCECPP
335 If this variable is set, each file whose suffix is ´.h´ is
336 treated as a C++ source file.
337 GTAGSLABEL
339 Configuration label. The default is default.
340 GTAGSLIBPATH
342 If this variable is set, it is used as the path to search for
343 library functions. If the given symbol is not found in the cur‐
344 rent project, global also searches in these paths. Since only
345 ´GTAGS´ is targeted in the retrieval, this variable is ignored
346 when -r or -s is specified.
347 GTAGSLOGGING
349 If this variable is set, ´$GTAGSLOGGING´ is used as the path
350 name of a log file. There is no default value.
351 GTAGSROOT
353 The root directory of the project. Usually, it is recognized by
354 existence of ´GTAGS´. Use of this variable is not recommended.
355 GTAGSTHROUGH
357 If this variable is set, the -T option is specified.
358 GTAGSOBJDIR, MAKEOBJDIR
360 If eigher of the two variable is set, it is used as the name of
361 BSD-style objdir. The former is given priority. The default is
362 ´obj´.
363 GTAGSOBJDIRPREFIX, MAKEOBJDIRPREFIX
365 If eigher of the two variable is set, it is used as the prefix
366 of BSD-style objdir. The former is given priority. The default
367 is ´/usr/obj´.
368
370 The following configuration variables affect the execution of global:
371 icase_path (boolean)
373 Ignore case distinctions in pattern.
374
376 Global exits with a non-0 value if an error occurred, 0 otherwise.
377
379 gtags(1), htags(1), less(1), gtags.conf(5).
380 GNU GLOBAL source code tag system
382 (http://www.gnu.org/software/global/).
383
385 Shigio YAMAGUCHI, Hideki IWAMOTO and others.
386
388 The global command appeared in FreeBSD 2.2.2.
389GNU Project May 2015 GLOBAL(1)