packages icon



 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:  March 29, 2024






 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:  March 29, 2024






 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:  March 29, 2024






 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:  March 29, 2024






 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:  March 29, 2024






 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:  March 29, 2024