Ubuntu Manpage: global - print locations of given symbols

NAME

       global - print locations of given symbols

SYNOPSIS

       global [-adEFGilMnNqrstTvx][-S dir][-e] pattern
       global -c[dFiIMoOPrsT] prefix
       global -f[adlnqrstvx][-L file-list][-S dir] files
       global -g[aEGilMnoOqtvVx][-L file-list][-S dir][-e] pattern [files]
       global -I[ailMnqtvx][-S dir][-e] pattern
       global -P[aEGilMnoOqtvVx][-S dir][-e] pattern
       global -p[qrv]
       global -u[qv]

DESCRIPTION

       Global  finds  locations  of  given symbols in C, C++, Yacc, Java, PHP and Assembly source
       files, and prints the path name, line number and line image of the locations.  Global  can
       locate not only definitions but also references and other symbols.

       Global  can  treat a source tree, that is, a directory that has sub-directories and source
       files, as a project.  In advance of using this command, you must execute gtags(1)  at  the
       root  directory  of the project which you want to investigate to make tag files.  Then you
       can use global command anywhere in the project.  You need not specify where the  tag  file
       is.  Instead, global locates it by itself.

       You  can  specify  a  regular  expression  for  pattern.  Global understands two different
       versions of regular expression syntax: basic and extended (default).

COMMANDS

The following commands are available:

<no command> pattern
No command means tag search command. Print tags which match to pattern. By
default, print definition tags.

-c, --completion [prefix]
Print symbols which start with prefix. If prefix is not given, print all symbols.

-f, --file files
Print all tags in the files. This command implies the -x option.

-g, --grep pattern [files]
Print all lines which match to the pattern. If files are given, this command
searches in those files.

--help Print a usage message.

-I, --idutils pattern
Print all lines which match to pattern. This function uses idutils(1) as a search
engine. To use this command, you need to install idutils(1) in your system and
execute gtags(1) with the -I option.

-P, --path [pattern]
Print path names which match to pattern. If no pattern is given, print all paths
in the project.

-p, --print-dbpath
Print location of ´GTAGS´.

--print name
Print location of name, which may be one of: ´root´, ´dbpath´ or ´conf´. ´root´
means project's root directory. ´dbpath´ means a directory where tag databases
exist. ´conf´ means configuration file.

-u, --update
Update tag files incrementally. This command internally invokes gtags(1). You can
execute this command anywhere in the project, differing from gtags(1).

--version
Show version number.

OPTIONS

The following options are available:

-a, --absolute
Print absolute path names. By default, print relative path names.

--color when
Use color to highlight the pattern within the line; when may be one of: never,
always or auto (default). The default color is bold red text on current
background; the environment variable GREP_COLORS (only mt and ms are effective at
present) or GREP_COLOR defines it. This option is effective to the following
commands: <no command>, -f, -g, -I, -P.

-d, --definition
Print locations of definitions.

-e, --regexp pattern
Use pattern as the pattern; useful to protect patterns starting with ´-´.

-E, --extended-regexp
Interpret pattern as a extended regular expression. This is the default.

--encode-path chars
Convert path characters in chars into a ´%´ symbol, followed by the two-digit
hexadecimal representation of the character. A blank will be converted to ´%20´.

-F, --first-match
End the search without going through all the tag files listed in GTAGSLIBPATH when
tags are found in a tag file. This is the default.

--from-here context
Decide tag type by context. Its syntax should be ´lineno:path´. If the context is
a definition of the pattern then use -r, else if there is at least one definition
of the pattern then use -d, else use -s. If this option is specified then -d, -r
and -s on the command line are ignored. Regular expression is not allowed for
pattern. This option assumes use in conversational environments such as editors
and IDEs.

-G, --basic-regexp
Interpret pattern as a basic regular expression. The default is an extended
regular expression.

--gtagsconf file
Set environment variable GTAGSCONF to file.

--gtagslabel label
Set environment variable GTAGSLABEL to label.

-i, --ignore-case
Ignore case distinctions in the pattern.

-L, --file-list file
Obtain files from file in addition to the arguments. The argument file can be set
to '-' to accept a list of files from the standard input. File names must be
separated by newline.

-l, --local
Print only tags which exist under the current directory.

--literal
Execute literal search instead of regular expression search. This option works
with the tag search command, -g command, -P command and -I command.

-M, --match-case
Search is case-sensitive. This is the default.

--match-part part
Specify how path name completion should match, where part is one of: ´first´,
´last´ or ´all´ (default). This option is valid only with the -c command in
conjunction with -P.

-n, --nofilter
Suppress sort filter and path conversion filter.

-N, --nearness[=start]
Use Nearness sort method (sorting by closest from start) for the output. By
default, alphabetical sort method is used. This option is effective for the tag
search command, -P command and -g command. As an exception, -g command ignores this
option when files are specified by arguments. The nearness is defined by how many
parent directories to go up to reach the target. The result of nearness sort is
concatenation of the following ([0]-[n]) in this order. The default of start is the
current directory.
[0] If the start is a file, output of local search in the file.
[1] Output of local search in the start directory except for [0].
[2] Output of local search in the parent directory except for [0]-[1].
[3] Output of local search in the grandparent directory except for [0]-[2].
... (repeat until the project root directory)
[n] Output of local search in the project root directory except for [0]-[n-1].
In each directory, they are sorted by alphabetical order.

-O, --only-other
Treat only text files other than source code, like ´README´. This option is valid
only with the -g or -P command. This option overrides the -o option.

-o, --other
Treat not only source files but also text files other than source code, like
´README´. This option is valid only with the -g or -P command.

--path-style format
Print path names using format, which may be one of: ´relative´, ´absolute´,
´shorter´, ´abslib´ or ´through´. ´relative´ means relative path. ´absolute´ means
absolute path. ´shorter´ means the shorter one of relative and absolute path.
´abslib´ means absolute path for libraries (GTAGSLIBPATH) and relative path for the
rest. ´through´ means the relative path from the project root directory (internal
format of GPATH). The default is ´relative´. The --path-style option is given
more priority than the -a option.

--print0
Print each record followed by a null character instead of a newline.

-q, --quiet
Quiet mode.

-r, --reference, --rootdir
Print reference tags. Reference means the reference to a symbol which has
definitions. With the -p option, print the root directory of the project.

--result format
Print out using format, which may be one of: ´path´ (default), ´ctags´, ´ctags-x´,
´grep´ or ´cscope´. The --result=ctags and --result=ctags-x options are equivalent
to the -t and -x options respectively. The --result option is given more priority
than the -t and -x options.

--single-update file
Update tag files using gtags(1) with the --single-update option. It is considered
that file was added, updated or deleted, and there is no change in other files.
This option implies the -u option.

-s, --symbol
Print other symbol tags. Other symbol means the reference to a symbol which has no
definition.

-S, --scope dir
Print only tags which exist under dir directory. It is similar to the -l option,
but you need not change directory.

-T, --through
Go through all the tag files listed in GTAGSLIBPATH. By default, stop searching
when tag is found. This option is ignored when either -s, -r or -l option is
specified.

-t, --tags
Use standard ctags format.

-V, --invert-match
Invert the sense of matching, to select non-matching lines. This option is valid
only with the -g or -P commands.

-v, --verbose
Verbose mode.

-x, --cxref
Use standard ctags cxref (with -x) format.

EXAMPLES

       $ ls -F
       Makefile      src/    lib/
       $ gtags
       $ ls G*
       GPATH   GRTAGS  GTAGS
       $ global main
       src/main.c
       $ (cd src; global main)
       main.c
       $ global -x main
       main              10 src/main.c  main (argc, argv) {
       $ global -f src/main.c
       main              10 src/main.c  main (argc, argv) {
       func1             55 src/main.c  func1() {
       func2             72 src/main.c  func2() {
       func3            120 src/main.c  func3() {
       $ global -x '^[sg]et'
       set_num           20 lib/util.c  set_num(values) {
       get_num           30 lib/util.c  get_num() {
       $ global -rx set_num
       set_num          113 src/op.c            set_num(32);
       set_num          225 src/opop.c               if (set_num(0) > 0) {
       $ global strlen
       $ (cd /usr/src/sys; gtags)
       $ export GTAGSLIBPATH=/usr/src/sys
       $ global -a strlen
       /usr/src/sys/libkern/strlen.c
       $ (cd /usr/src/lib; gtags)
       $ GTAGSLIBPATH=/usr/src/lib:/usr/src/sys
       $ global -a strlen
       /usr/src/lib/libc/string/strlen.c

FILES

       ´GTAGS´
              Tag file for definitions.

       ´GRTAGS´
              Tag file for references.

       ´GPATH´
              Tag file for source files.

       ´GTAGSROOT´
              If environment variable GTAGSROOT is not set and file  ´GTAGSROOT´  exists  in  the
              same directory as ´GTAGS´ then global sets GTAGSROOT to the contents of the file.

       ´gtags.conf´, ´$HOME/.globalrc´
              Configuration data for GNU GLOBAL.  See gtags.conf(5).

ENVIRONMENT

The following environment variables affect the execution of global:

GREP_COLOR
The color to use for --color; GREP_COLORS has precedence.

GREP_COLORS
The color (mt or ms) to use for --color; see grep(1).

GTAGSBLANKENCODE
If this variable is set, the --encode-path=" <TAB>" option is specified.

GTAGSCACHE
The size of the B-tree cache. The default is 50000000 (bytes).

GTAGSCONF
Configuration file.

GTAGSDBPATH
The directory in which the tag files exist. This value is ignored when GTAGSROOT
is not defined. Use of this variable is not recommended.

GTAGSFORCECPP
If this variable is set, each file whose suffix is ´.h´ is treated as a C++ source
file.

GTAGSLABEL
Configuration label. The default is default.

GTAGSLIBPATH
If this variable is set, it is used as the path to search for library functions. If
the given symbol is not found in the project, global also searches in these paths.
Since only ´GTAGS´ is targeted in the retrieval, this variable is ignored when -r
or -s is specified.

GTAGSLOGGING
If this variable is set, ´$GTAGSLOGGING´ is used as the path name of a log file.
There is no default value.

GTAGSROOT
The root directory of the project. Usually, it is recognized by existence of
´GTAGS´. Use of this variable is not recommended.

GTAGSTHROUGH
If this variable is set, the -T option is specified.

GTAGSOBJDIR, MAKEOBJDIR
If eigher of the two variable is set, it is used as the name of BSD-style objdir.
The former is given priority. The default is ´obj´.

GTAGSOBJDIRPREFIX, MAKEOBJDIRPREFIX
If eigher of the two variable is set, it is used as the prefix of BSD-style objdir.
The former is given priority. The default is ´/usr/obj´.

CONFIGURATION

       The following configuration variables affect the execution of global:

       icase_path (boolean)
              Ignore case distinctions in pattern.

DIAGNOSTICS

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

AUTHOR

       Shigio YAMAGUCHI, Hideki IWAMOTO and others.

HISTORY

       The global command appeared in FreeBSD 2.2.2.