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

FreeBSD Manual Pages

  
 
  

home | help
GLOBAL(1)		    General Commands Manual		     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, Yacc, Java, PHP and as-
       sembly source files, and	prints the path	name, line number and line im-
       age  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-di-
       rectories  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 op-
	      tion.

       -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.

       -C, --directory dir
	      Change the directory before doing	all the	work including parame-
	      ter 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  de-
	      fault.

       --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 op-
	      tion 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 di-
	      rectory.
	      [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 op-
	      tion 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  di-
	      rectory 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  de-
	      fault, 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'
	      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=" <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  ig-
	      nored  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  cur-
	      rent  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+13.0-RELEASE+and+Ports>

home | help