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

FreeBSD Manual Pages

  
 
  

home | help
GTAGS(1)		    General Commands Manual		      GTAGS(1)

NAME
       gtags - create tag files	for global

SYNOPSIS
       gtags [-ciIOqvw][-d tag-file][-f	file][dbpath]

DESCRIPTION
       Gtags is	used to	create tag files for global(1).

       Gtags  recursively  collects  source files under	the current directory,
       picks up	symbols	and writes the cross-reference data into the tag files
       ('GTAGS', 'GRTAGS' and 'GPATH').

       If 'gtags.files'	exists in the current directory	or a file is specified
       by the -f option, target	files are limited by it. Lines	starting  with
       '. ' are	comments.

       C, yacc,	Assembly, Java,	C++ and	PHP source files are supported.	 Files
       whose names end in '.c',	'.h' are assumed to be C source	files.	 Files
       whose  names  end  in  '.y' are assumed to be yacc source files.	 Files
       whose names end in '.s',	'.S' are assumed to be Assembly	source	files.
       Files  whose  names end in '.java' are assumed to be Java source	files.
       Files whose names end in	'.c++',	'.cc', '.hh', '.cpp', '.cxx',  '.hxx',
       '.hpp',	'.C',  '.H'  are  assumed to be	C++ source files.  Files whose
       names end in '.php', '.php3', '.phtml' are assumed  to  be  PHP	source
       files.	Other files are	assumed	to be text files. Gtags	does not treat
       binary files.

OPTIONS
       The following options are available:

       --accept-dotfiles
	      Accept files and directories whose names begin with a  dot.   By
	      default, gtags ignores them.

       -c, --compact
	      Make  'GTAGS' in compact format.	This option does not influence
	      'GRTAGS',	because	that is	always made in compact format.

       --config[=name]
	      Print the	value of config	variable name.	If name	is not	speci-
	      fied  then print all names and values.  In addition to the vari-
	      ables listed in  the  ENVIRONMENT	 section,  you	can  refer  to
	      install  directories  by	read  only  variables: bindir, libdir,
	      datadir, localstatedir and sysconfdir.

       -d, --dump tag-file
	      Dump a tag file as text to the standard output. Output format is

       --explain
	      Explain handling files.

       -f, --file file
	      Give a list of candidates	of target files.  Files	which are  not
	      on the list are ignored.	The argument file can be set to	'-' to
	      accept a list of files from the standard input.  File names must
	      be  separated by newline.	 To make the list you may use find(1),
	      which has	rich options for selecting files.

       --gtagsconf file
	      Set environment variable GTAGSCONF to file.

       --gtagslabel label
	      Set environment variable GTAGSLABEL to label.

       -I, --idutils
	      In addition to tag files,	make ID	database for idutils(1).

       -i, --incremental
	      Update tag files incrementally.  It's better  to	use  global(1)
	      with the -u command.

       -O, --objdir
	      Use BSD-style objdir as the location of tag files.  If '$MAKEOB-
	      JDIRPREFIX' directory  exists,  gtags  creates  '$MAKEOBJDIRPRE-
	      FIX/<current  directory>'	 directory  and	makes tag files	in it.
	      If dbpath	is specified, this option is ignored.

       --single-update file
	      Update tag files for a single file.  It is considered that  file
	      was  added,  updated or deleted, and there is no change in other
	      files.  This option implies the -i option.

       --skip-unreadable
	      Skip unreadable files.

       --sqlite3
	      Use Sqlite 3 API to make tag files. By default, BSD/DB 1.85  API
	      is  used.	  To  use  this	 option,  you need to invoke configure
	      script with --with-sqlite3 in the	build phase.

       --statistics
	      Print statistics information.

       -q, --quiet
	      Quiet mode.

       -v, --verbose
	      Verbose mode.

       -w, --warning
	      Print warning messages.

       dbpath The directory in which tag files are generated.  The default  is
	      the current directory.

EXAMPLES
       $ ls -F
       Makefile	     src/    lib/
       $ gtags -v
       $ global	-x main
       main		 10 src/main.c	main (argc, argv) {

FILES
       'GTAGS'
	      Tag file for definitions.

       'GRTAGS'
	      Tag file for references.

       'GPATH'
	      Tag file for source files.

       'gtags.conf', '$HOME/.globalrc'
	      See gtags.conf(5).

       'gtags.files'
	      The list of candidates of	target files.

ENVIRONMENT
       The following environment variables affect the execution	of gtags:

       GTAGSCACHE
	      The size of the B-tree cache. The	default	is 50000000 (bytes).

       GTAGSCONF
	      Configuration file.

       GTAGSFORCECPP
	      If  this	variable  is  set,  each  file whose suffix is '.h' is
	      treated as a C++ source file.

       GTAGSFORCEENDBLOCK
	      If this variable is set, each } at the first column  brings  end
	      of block of 0 level.

       GTAGSLABEL
	      Configuration label. The default is 'default'.

       GTAGSLOGGING
	      If  this	variable  is  set, '$GTAGSLOGGING' is used as the path
	      name of a	log file. There	is no default value.

       GTAGS_COMMANDLINE
	      This  variable  can  only	 be  referenced	 from  the  hook  (see
	      gtags_hook).   Gtags sets	its own	effective command line to this
	      variable before calling the hook.	Each argument is separated  by
	      whitespace, and real whitespace is represented as	'%20'. This is
	      read only.

       GTAGS_OPTIONS
	      The value	of this	variable is inserted in	the head of arguments.

       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 pre-
	      fix of BSD-style objdir. The default is '/usr/obj'.

       TMPDIR The location used	to stored  temporary  files.  The  default  is
	      '/tmp'.

CONFIGURATION
       The  following  configuration  variables	affect the execution of	gtags.
       You can see the default value  for  each	 variable  with	 the  --config
       option.

       gtags_parser (comma separated list)
	      Specify the mapping of language names and	plug-in	parsers.  Each
	      part delimited by	the comma consists of  the  language  name,  a
	      colon,  the  shared object path, an optional colon followed by a
	      function name.  If the function name is not specified,  'parser'
	      is  assumed.  As a special exception, gtags collects values from
	      multiple gtags_parser variables.	For these mappings, the	 first
	      match is adopted.

       gtags_hook (command line)
	      Specify a	command	line which should be executed at the beginning
	      of gtags after loading configuration file. You can use this hook
	      to  update  'gtags.files'	 dynamically.  "./" in it always means
	      the project root directory, since	gtags is always	invoked	there.

       icase_path (boolean)
	      Ignore  case  distinctions  in  the  path.   Suffixes  check  is
	      affected by this capability.

       langmap (comma separated	list)
	      Language	mapping. Each comma-separated map consists of the lan-
	      guage name, a colon, and a list of file extensions.  As  a  spe-
	      cial  exception,	gtags  collects	 values	 from multiple langmap
	      variables.  For these mappings,  the  first  match  is  adopted.
	      Default mapping is:
	      'c:.c.h,yacc:.y,asm:.s.S,java:.java,cpp:.c++.cc.hh.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml'.

       skip (comma separated list)
	      Gtags skips files	and directories	which are given	in this	 list.
	      As a special exception, gtags collects values from multiple skip
	      variables.  If the value ends with  '/',	it  is	assumed	 as  a
	      directory	 and  gtags  skips  all	files under it.	 The value may
	      include glob patterns (*,	?, [...], [!...], [^...]).

	      If the value starts with '/', it is assumed a relative path name
	      from the root directory of the project. You cannot use glob pat-
	      terns for	a path name. However, this direction  is  out-of-date,
	      and is not recommended. Instead, you can use -f option which can
	      be combined with find(1).	Since  find(1)	has  rich  options  to
	      select  files,  you  can do everything. Additionally, this tech-
	      nique can	also be	applied	to  any	 other	tagging	 systems  like
	      ctags(1),	cscope(1), etc.

	      Skip   list   is	 also	effective  when	 you  use  the	-f  or
	      'gtags.files'.

DIAGNOSTICS
       Gtags exits with	a non-0	value if an error occurred, 0 otherwise.

       Note that files created by gtags	with a non-zero	exit  code  should  be
       considered corrupted.

SEE ALSO
       global(1), htags(1), gtags.conf(5).

       GNU GLOBAL source code tag system
       (http://www.gnu.org/software/global/).

BUG
       'GTAGS' and 'GRTAGS' are	very large.  In	advance	of using this command,
       check the space of your disk.

       Assembly	support	is far from complete.  It extracts  only  ENTRY()  and
       ALTENTRY() from source file.  Probably valid only for FreeBSD and Linux
       kernel source.

       There is	no concurrency control about tag files.

AUTHOR
       Shigio YAMAGUCHI, Hideki	IWAMOTO	and others.

HISTORY
       The gtags command appeared in FreeBSD 2.2.2.

GNU Project			September 2016			      GTAGS(1)

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

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

home | help