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][-C dir][-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').

       By  default,  gtags  picks up C,	Yacc, assembly language, Java, C++ and
       PHP source files.  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  language  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.

       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.

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.

       -C, --directory dir
	      Change the directory before doing	all the	work including parame-
	      ter  analysis.  This option is ignored in	GTAGS_OPTIONS.	Please
	      specify it on the	command	line directly.

       --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  in-
	      stall  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 'key<tab>data'. This is for debugging.

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

       --help Print a usage message.

       -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 obj	directory as the location of  tag  files.   If
	      GTAGSOBJDIRPREFIX	 is set	and '$GTAGSOBJDIRPREFIX' directory ex-
	      ists, gtags creates '$GTAGSOBJDIRPREFIX/<current directory>' di-
	      rectory  and  makes tag files in it.  Though you can use MAKEOB-
	      JDIRPREFIX instead of GTAGSOBJDIRPREFIX, it is  deprecated.   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.

       --skip-symlink [=type]
	      Skip  symbolic  links.  If  type	is 'f' then skip only symbolic
	      links for	file, else if 'd' then skip only  symbolic  links  for
	      directory.   The	default	 value	of  type  is 'a' (all symbolic
	      links).

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

       --version
	      Show version number.

       -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'
	      Configuration data for GNU Global.  See gtags.conf(5).

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

       '.notfunction'
	      The list of symbols which	is not a definition.  If this file ex-
	      ists in the project root directory, gtags	does  not  regard  the
	      symbols listed in	this file as definitions.  Lines starting with
	      ';' are comment lines.

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
	      forcibly	parsed	by  the	 built-in  C++ parser. Do not set this
	      variable if you are using	plug-in	parsers. This variable and the
	      built-in C++ parser are deprecated.

       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.

       GTAGSOBJDIR
	      If this variable is set, it is used as the name of BSD-style ob-
	      jdir.  The default is 'obj'.  Though you can use MAKEOBJDIR  in-
	      stead of GTAGSOBJDIR, it is deprecated.

       GTAGSOBJDIRPREFIX
	      If  this	variable is set, it is used as the prefix of BSD-style
	      objdir.  The default is '/usr/obj'.  Though you can use  MAKEOB-
	      JDIRPREFIX instead of GTAGSOBJDIRPREFIX, it is deprecated.

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

       gtags_parser (comma separated list)
	      Specify the mapping of language names and	plug-in	parsers.  Each
	      part  delimited  by  the	comma  consists	 of a 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.

	      This  hook  is ignored when the following	options	are specified:
	      --version, --help, --config, --dump.

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

       langmap (comma separated	list)
	      Language	mapping.  Each	comma-separated	map consists of	a lan-
	      guage name, a colon, and a list of  file	extensions.   You  can
	      specify  a  glob pattern surrounded by parentheses instead of an
	      extension	for the	files without extensions (e.g.	Make:([Mm]ake-
	      file).mak.mk).   As  a  special 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  di-
	      rectory  and  gtags skips	all files under	it.  The value may in-
	      clude 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  se-
	      lect  files, you can do everything. Additionally,	this technique
	      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	language support is far	from complete.	It extracts  only  EN-
       TRY() and ALTENTRY() from source	file.  Probably	valid only for FreeBSD
       and Linux kernel	source.

       C++ support is deprecated.

       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			 February 2021			      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+13.1-RELEASE+and+Ports>

home | help