GLOBAL(1) GNU Project GLOBAL(1)
Jun 2013
NAME
global - print locations of given symbols
SYNOPSIS
global [-adGilnqrstTvx][-e] pattern
global -c[diIoOPrsT] prefix
global -f[adlnqrstvx][-L file-list] files
global -g[aGilnoOqtvVx][-L file-list][-e] pattern [files]
global -I[ailnqtvx][-e] pattern
global -P[aGilnoOqtvVx][-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
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.
- 1 - Formatted: October 28, 2025
GLOBAL(1) GNU Project GLOBAL(1)
Jun 2013
-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'.
-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.
-d, --definition
Print locations of definitions.
-e, --regexp pattern
Use pattern as the pattern; useful to protect patterns starting
with '-'.
--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'.
--from-here context
Decide tag type by context, which must be 'lineno:path'. If this
option is specified then -s and -r 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.
-i, --ignore-case
Ignore case distinctions in the pattern.
- 2 - Formatted: October 28, 2025
GLOBAL(1) GNU Project GLOBAL(1)
Jun 2013
-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 is only valid when the -g command is specified.
--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.
-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'. 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' (deault),
'ctags', 'ctags-x', 'grep' or 'cscope'. The --result=ctags and
--result=ctags-x options are equivalent to the -t and -x options
- 3 - Formatted: October 28, 2025
GLOBAL(1) GNU Project GLOBAL(1)
Jun 2013
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 or updated, 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.
-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
- 4 - Formatted: October 28, 2025
GLOBAL(1) GNU Project GLOBAL(1)
Jun 2013
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.
'$HOME/.globalrc', '/etc/gtags.conf', '[sysconfdir]/gtags.conf'
Configuration files.
ENVIRONMENT
The following environment variables affect the execution of global:
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. The default is '$HOME/.globalrc'.
GTAGSDBPATH
The directory in which the tag files exist. This value is
ignored when GTAGSROOT is not defined.
GTAGSFORCECPP
If this variable is set, each file whose suffix is '.h' is
treated as a C++ source file.
- 5 - Formatted: October 28, 2025
GLOBAL(1) GNU Project GLOBAL(1)
Jun 2013
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.
GTAGSTHROUGH
If this variable is set, the -T option is specified.
MAKEOBJDIR
If this variable is set, '$MAKEOBJDIR' is used as the name of
BSD-style objdir. The default is 'obj'.
MAKEOBJDIRPREFIX
If this variable is set, '$MAKEOBJDIRPREFIX' is used as the
prefix of BSD-style objdir. 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.
SEE ALSO
gtags(1), htags(1), less(1).
GNU GLOBAL source code tag system
(http://www.gnu.org/software/global/).
AUTHOR
Shigio YAMAGUCHI, Hideki IWAMOTO and others.
HISTORY
The global command appeared in FreeBSD 2.2.2.
- 6 - Formatted: October 28, 2025
