global - print locations of given symbols
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]
Global finds locations of given symbols in 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).
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.
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.
- -C, --directory
dir
- Change the directory before doing all the work including parameter
analysis.
- -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.
$ 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
- ´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).
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 current 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´.
The following configuration variables affect the execution of
global:
- icase_path
(boolean)
- Ignore case distinctions in pattern.
Global exits with a non-0 value if an error occurred, 0
otherwise.
Shigio YAMAGUCHI, Hideki IWAMOTO and others.
The global command appeared in FreeBSD 2.2.2.