1GLOBAL(1)                   General Commands Manual                  GLOBAL(1)
2
3
4

NAME

6       global - print locations of given symbols
7

SYNOPSIS

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

DESCRIPTION

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
24       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
31       You  can  specify a regular expression for pattern.  Global understands
32       two different versions of regular expression syntax: basic and extended
33       (default).
34

COMMANDS

36       The following commands are available:
37
38       <no command> pattern
39              No  command means tag search command.  Print tags which match to
40              pattern.  By default, print definition tags.
41
42       -c, --completion [prefix]
43              Print symbols which start with prefix.  If prefix is not  given,
44              print all symbols.
45
46       -f, --file files
47              Print  all  tags  in the files.  This command implies the -x op‐
48              tion.
49
50       -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
54       --help Print a usage message.
55
56       -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
62       -P, --path [pattern]
63              Print path names which match  to  pattern.   If  no  pattern  is
64              given, print all paths in the project.
65
66       -p, --print-dbpath
67              Print location of ´GTAGS´.
68
69       --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
75       -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
80       --version
81              Show version number.
82

OPTIONS

84       The following options are available:
85
86       -a, --absolute
87              Print absolute path  names.  By  default,  print  relative  path
88              names.
89
90       --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
98       -C, --directory dir
99              Change the directory before doing all the work including parame‐
100              ter analysis.
101
102       -d, --definition
103              Print locations of definitions.
104
105       -e, --regexp pattern
106              Use  pattern as the pattern; useful to protect patterns starting
107              with ´-´.
108
109       -E, --extended-regexp
110              Interpret pattern as a extended regular expression.  This is the
111              default.
112
113       --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
118       -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
123       --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
132       -G, --basic-regexp
133              Interpret pattern as a basic regular expression.  The default is
134              an extended regular expression.
135
136       --gtagsconf file
137              Set environment variable GTAGSCONF to file.
138
139       --gtagslabel label
140              Set environment variable GTAGSLABEL to label.
141
142       -i, --ignore-case
143              Ignore case distinctions in the pattern.
144
145       -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
150       -l, --local
151              Print only tags which exist under the current directory.
152
153       --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
158       -M, --match-case
159              Search is case-sensitive. This is the default.
160
161       --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
166       -n, --nofilter
167              Suppress sort filter and path conversion filter.
168
169       -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
187       -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
192       -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
197       --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
208       --print0
209              Print each record followed by a null character instead of a new‐
210              line.
211
212       -q, --quiet
213              Quiet mode.
214
215       -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
220       --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
227       --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
233       -s, --symbol
234              Print other symbol tags.  Other symbol means the reference to  a
235              symbol which has no definition.
236
237       -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
241       -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
246       -t, --tags
247              Use standard ctags format.
248
249       -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
253       -v, --verbose
254              Verbose mode.
255
256       -x, --cxref
257              Use standard ctags cxref (with -x) format.
258

EXAMPLES

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

FILES

293       ´GTAGS´
294              Tag file for definitions.
295
296       ´GRTAGS´
297              Tag file for references.
298
299       ´GPATH´
300              Tag file for source files.
301
302       ´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
307       ´gtags.conf´, ´$HOME/.globalrc´
308              Configuration data for GNU GLOBAL.  See gtags.conf(5).
309

ENVIRONMENT

311       The following environment variables affect the execution of global:
312
313       GREP_COLOR
314              The color to use for --color; GREP_COLORS has precedence.
315
316       GREP_COLORS
317              The color (mt or ms) to use for --color; see grep(1).
318
319       GTAGSBLANKENCODE
320              If  this  variable  is set, the --encode-path=" <TAB>" option is
321              specified.
322
323       GTAGSCACHE
324              The size of the B-tree cache. The default is 50000000 (bytes).
325
326       GTAGSCONF
327              Configuration file.
328
329       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
334       GTAGSFORCECPP
335              If this variable is set, each  file  whose  suffix  is  ´.h´  is
336              treated as a C++ source file.
337
338       GTAGSLABEL
339              Configuration label. The default is default.
340
341       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
348       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
352       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
356       GTAGSTHROUGH
357              If this variable is set, the -T option is specified.
358
359       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
364       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

CONFIGURATION

370       The following configuration variables affect the execution of global:
371
372       icase_path (boolean)
373              Ignore case distinctions in pattern.
374

DIAGNOSTICS

376       Global exits with a non-0 value if an error occurred, 0 otherwise.
377

SEE ALSO

379       gtags(1), htags(1), less(1), gtags.conf(5).
380
381       GNU GLOBAL source code tag system
382       (http://www.gnu.org/software/global/).
383

AUTHOR

385       Shigio YAMAGUCHI, Hideki IWAMOTO and others.
386

HISTORY

388       The global command appeared in FreeBSD 2.2.2.
389
390
391
392GNU Project                        May 2015                          GLOBAL(1)
Impressum