Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GLOBAL(1)							     GLOBAL(1)

NAME
       global -	print locations	of given symbols

SYNOPSIS
       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]

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
	      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 idu-
	      tils(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 follow-
	      ing commands: <no	command>, -f, -g, -I, -P.

       -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 environ-
	      ments 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 argu-
	      ment 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 'rel-
	      ative'.  The --path-style	option is given	more priority than the
	      -a option.

       --print0
	      Print each record	followed by a null character instead of	a new-
	      line.

       -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  'GTAGS-
	      ROOT'  exists  in	the same directory as 'GTAGS' then global sets
	      GTAGSROOT	to the contents	of the file.

       'gtags.conf', '$HOME/.globalrc'
	      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="  <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
	      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.

GNU Project			   May 2015			     GLOBAL(1)

NAME | SYNOPSIS | DESCRIPTION | COMMANDS | OPTIONS | EXAMPLES | FILES | ENVIRONMENT | CONFIGURATION | DIAGNOSTICS | SEE ALSO | AUTHOR | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=global&sektion=1&manpath=FreeBSD+11.2-RELEASE+and+Ports>

home | help