GLOBAL(1)

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 print path name, line number and line image for each of them. 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 use regular expression for pattern. Global understands two different versions of regular expression syntax: basic and extended. The default is extended.

COMMANDS
The following commands are available:

<no command> pattern
    Print tags of symbols which match to the pattern. By default, print definition tags.

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

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

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

--help
    Print a usage message.

-I, --idutils pattern
    Print all lines which match to the pattern. This function use 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 the 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 name. By default, print relative path name.

-d, --definition
    Print locations of definitions.

--from-here context
    Decide tag type by the context. The context must be 'lineno:path'. If this option is specified then the -s and -r are ignored. Regular expression is not allowed for the pattern. This option assumes use in conversational environments such as editors and IDEs.

-e, --regexp pattern
    Use pattern as the pattern; useful to protect patterns beginning 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'.

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

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

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

-L, --file-list file-list
    Obtain files from file-list in addition to the arguments.

--literal
    Execute literal search instead of regular expression search. This option is only valid when the -g command is specified.

--match-part part
    Specify the matched part of path name. Possible values are as follows: first, last, all. The default is all. This option is valid only with the -c command with the -P option.

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

-O, --only-other
    Treat only text files: 'README', 'ChangeLog', or etc. 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: 'README', 'ChangeLog', or etc. This option is valid only with the -g or -P command.

--path-style format
    Print path names using the specified format. format may be relative, absolute, shorter, abslib or through. The --path-style option is given more priority than the -a options.

--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 the specified format. format may be path, ctags, ctags-x, grep or cscope. The default is path. The --result=ctags and --result=ctags-x are equivalent to the -t and -x respectively. The --result option is given more priority than the -t and -x options.

--single-update file
    Update tag files incrementally using gtags(1) with --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, --verbose
    Verbose mode.

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

-x, --cxref
    Use standard ctags cxref (with the -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 strlen
$ (cd /usr/src/lib; gtags)
$ GTAGSLIBPATH=/usr/src/lib:/usr/src/sys
$ global strlen

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 with '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:

GTAGSROOT
    The root directory of the project.

GTAGSDBPATH
    The directory on which tag files exist. This value is ignored when GTAGSROOT is not defined.

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 search in these paths. Since only 'GTAGS' is targeted in the retrieval, this variable is ignored when the -r or -s is specified.

GTAGSCONF
    Configuration file. The default is '$HOME/.globalrc'.

GTAGSLABEL
    Configuration label. The default is default.

MAKEOBJDIRPREFIX
    If this variable is set, '$MAKEOBJDIRPREFIX' is used as the prefix of BSD-style objdir. The default is '/usr/obj'.

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

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

CONFIGURATION
The following configuration variables affect the execution of global:

icase_path(boolean)
    Ignore case distinctions in the 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.