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, 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
24       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
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
48              option.
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       -d, --definition
99              Print locations of definitions.
100
101       -e, --regexp pattern
102              Use pattern as the pattern; useful to protect patterns  starting
103              with ´-´.
104
105       -E, --extended-regexp
106              Interpret pattern as a extended regular expression.  This is the
107              default.
108
109       --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
114       -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
119       --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
128       -G, --basic-regexp
129              Interpret pattern as a basic regular expression.  The default is
130              an extended regular expression.
131
132       --gtagsconf file
133              Set environment variable GTAGSCONF to file.
134
135       --gtagslabel label
136              Set environment variable GTAGSLABEL to label.
137
138       -i, --ignore-case
139              Ignore case distinctions in the pattern.
140
141       -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
146       -l, --local
147              Print only tags which exist under the current directory.
148
149       --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
154       -M, --match-case
155              Search is case-sensitive. This is the default.
156
157       --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
162       -n, --nofilter
163              Suppress sort filter and path conversion filter.
164
165       -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
183       -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
188       -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
193       --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
204       --print0
205              Print each record followed by a null character instead of a new‐
206              line.
207
208       -q, --quiet
209              Quiet mode.
210
211       -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
216       --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
223       --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
229       -s, --symbol
230              Print  other symbol tags.  Other symbol means the reference to a
231              symbol which has no definition.
232
233       -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
237       -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
242       -t, --tags
243              Use standard ctags format.
244
245       -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
249       -v, --verbose
250              Verbose mode.
251
252       -x, --cxref
253              Use standard ctags cxref (with -x) format.
254

EXAMPLES

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

FILES

289       ´GTAGS´
290              Tag file for definitions.
291
292       ´GRTAGS´
293              Tag file for references.
294
295       ´GPATH´
296              Tag file for source files.
297
298       ´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
303       ´gtags.conf´, ´$HOME/.globalrc´
304              Configuration data for GNU GLOBAL.  See gtags.conf(5).
305

ENVIRONMENT

307       The following environment variables affect the execution of global:
308
309       GREP_COLOR
310              The color to use for --color; GREP_COLORS has precedence.
311
312       GREP_COLORS
313              The color (mt or ms) to use for --color; see grep(1).
314
315       GTAGSBLANKENCODE
316              If this variable is set, the --encode-path="  <TAB>"  option  is
317              specified.
318
319       GTAGSCACHE
320              The size of the B-tree cache. The default is 50000000 (bytes).
321
322       GTAGSCONF
323              Configuration file.
324
325       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
330       GTAGSFORCECPP
331              If  this  variable  is  set,  each  file whose suffix is ´.h´ is
332              treated as a C++ source file.
333
334       GTAGSLABEL
335              Configuration label. The default is default.
336
337       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
344       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
348       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
352       GTAGSTHROUGH
353              If this variable is set, the -T option is specified.
354
355       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
360       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

CONFIGURATION

366       The following configuration variables affect the execution of global:
367
368       icase_path (boolean)
369              Ignore case distinctions in pattern.
370

DIAGNOSTICS

372       Global exits with a non-0 value if an error occurred, 0 otherwise.
373

SEE ALSO

375       gtags(1), htags(1), less(1), gtags.conf(5).
376
377       GNU GLOBAL source code tag system
378       (http://www.gnu.org/software/global/).
379

AUTHOR

381       Shigio YAMAGUCHI, Hideki IWAMOTO and others.
382

HISTORY

384       The global command appeared in FreeBSD 2.2.2.
385
386
387
388GNU Project                        May 2015                          GLOBAL(1)
Impressum