--- name: "global" section: "1" platform: "linux" package: "global" version: "6.7-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/global" --- # global(1) print locations of given symbols ## NAME global - print locations of given symbols ## SYNOPSIS **global** \[-adEFGilMnNqrstTvx\]\[-S dir\]\[-e\] *pattern*\ **global** -c\[dFiIMoOPqrsTv\] *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, 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)](/gtags/1.md) 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: - \ *pattern* No command means tag search command. Print tags which match to *pattern*. By default, print definition tags. - **-c**, **--completion\[=***limit***\]** *\[prefix\]* *Print symbols which start with prefix.* *If prefix is not given, print all symbols.* *If limit is given, print up to limit lines.* - **-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:* *\, -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). When this style is used, GTAGSLIBPATH is ignored.* *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=" \"** *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´.* ## 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),* **gtags.conf***(5).* *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.*