This package is part of GNU ELPA (M-x
list-packages
) and is also available on MELPA.
The goal is to make working with GNU Global in Emacs as effortlessly
and intuitively as possible and to integrate tightly with standard
emacs packages. ggtags.el
is tested in Emacs 24 and 25. Patches,
feature requests and bug reports are welcome. Thanks.
- Build on
compile.el
for asynchronicity and its large feature-set. - Automatically update Global's tag files when needed with tuning for large source trees.
- Intuitive navigation among multiple matches with mode-line display of current match, total matches and exit status.
- Read tag with completion.
- Show definition at point.
- Jump to #include files.
- Support search history and saving a search to register/bookmark.
- Query replace.
- Manage Global's environment variables on a per-project basis.
- Highlight (definition) tag at point.
- Abbreviated display of file names.
- Support all Global search backends:
grep
,idutils
etc. - Support exuberant ctags and
pygments
backend. - Support all Global's output formats:
grep
,ctags-x
,cscope
etc. - Support projects on remote hosts (e.g. via
tramp
). - Support eldoc.
- Search
GTAGSLIBPATH
for references and symbols.
The opengrok project composed a feature comparison table between a few tools.
Compile and install Global with
exuberant-ctags
./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags make && make install
The executable
ctags
is unfortunately named becauseemacs
also includes a command of the same name. So make sure it is from http://ctags.sourceforge.net. Seeplugin-factory/PLUGIN_HOWTO
(plugin-factory/README
for Global < 6.5) in GNU Global source for further information.Install
pygments
pluginThe
pygments
plugin has been included inglobal
since version6.3.2
.pip install pygments
is the only step required. Note the plugin is not activated by the defaultgtags.conf
or.globalrc
. Seeglobal/plugin-factory/PLUGIN_HOWTO.pygments
for details.The following instructions are for older
global
.pip install pygments git clone https://github.com/yoshizow/global-pygments-plugin.git cd global-pygments-plugin/ sh reconf.sh ./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags make && make install cp sample.globalrc $HOME/.globalrc
Make sure the value of
<PREFIX>
agree with step 1.
Global with exuberant-ctags
and pygments
plugins can support
dozens of programming languages. For example, to enable
ggtags-mode
for C/C++/Java modes:
(add-hook 'c-mode-common-hook (lambda () (when (derived-mode-p 'c-mode 'c++-mode 'java-mode) (ggtags-mode 1))))
Also see https://github.com/leoliu/ggtags/wiki for more examples.
Open any file in a project and type M-x ggtags-mode
. Use M-.
(ggtags-find-tag-dwim
) to find the tag at point. If the project
has not been indexed (i.e. no GTAGS
file exists), ggtags
will
ask for the project root directory and index it recursively.
Alternatively one can invoke ggtags-create-tags
to index a
directory. The mode line will display the directory name next to the
buffer name. If point is at a valid definition tag, it is underlined.
ggtags
is similar to the standard etags
package. For example
these keys M-.
, M-,
and C-M-.
should work as expected in
ggtags-mode
.
The following search commands are available:
ggtags-find-tag-dwim
Find a tag by context.
If point is at a definition tag, find references, and vice versa. If point is at a line that matches
ggtags-include-pattern
, find the include file instead.To force finding a definition tag, call it with a prefix (
C-u
).
ggtags-find-tag-mouse
Like ggtags-find-tag-dwim
but suitable for binding to mouse
events.
ggtags-find-definition
Find definition tags. With C-u
ask for the tag name with
completion.
ggtags-find-reference
Find reference tags. With C-u
ask for the tag name with completion.
ggtags-find-other-symbol
Find tags that have no definitions. With C-u
ask for the tag
name with completion.
ggtags-find-tag-regexp
Find definition tags matching a regexp. By default it lists all
matching tags in the project. With C-u
restrict the lists to a
directory of choice.
ggtags-idutils-query
Use idutils to find matches.
ggtags-grep
Grep for lines matching a regexp. This is usually the slowest.
ggtags-find-file
Find a file from all the files indexed by gtags
.
ggtags-query-replace
Do a query replace in all files found in a search.
When a search finds multiple matches, a buffer named
*ggtags-global*
is popped up and ggtags-navigation-mode
is
turned on to facilitate locating the right match.
ggtags-navigation-mode
makes a few commands in the
*ggtags-global*
buffer globally accessible:
M-n
Move to the next match.
M-p
Move to the previous match.
M-}
Move to next file.
M-{
Move to previous file.
M-=
Move to the file where navigation session starts.
M-<
Move to the first match.
M->
Move to the last match.
C-M-s
or M-s s
Use isearch
to find the match.
RET
Found the right match so exit navigation mode. Resumable by
M-x tags-loop-continue
.
M-,
(M-*
if Emacs < 25)
Abort and go back to the location where the search was started.
Commands are available from the Ggtags
menu in ggtags-mode
.
ggtags-prev-mark
Move to the previously (older) visited location. UnlikeM-,
(M-*
if Emacs < 25) this doesn't delete the location from the tag ring.
ggtags-next-mark
Move to the next (newer) visited location.
ggtags-view-tag-history
Pop to a buffer listing all visited locations from newest to oldest. The buffer is a next error buffer and works with standard commandsnext-error
andprevious-error
. In additionTAB
andS-TAB
move to next/prev entry, andRET
visits the location.M-n
andM-p
move to and display the next/previous entry.
ggtags-view-search-history
View or re-run past searches as kept in
ggtags-global-search-history
.
ggtags-kill-file-buffers
Kill all file-visiting buffers of current project.
ggtags-toggle-project-read-only
Toggle opening files in read-only
mode. Handy if the main
purpose of source navigation is to read code.
ggtags-visit-project-root
Open the project root directory in dired
.
ggtags-delete-tags
Delete the GTAGS, GRTAGS, GPATH and ID files of current project.
ggtags-explain-tags
Explain how each file is indexed in current project.
ggtags-browse-file-as-hypertext
Use htags
to generate HTML of the source tree. This allows
browsing the project in a browser with cross-references.
eldoc
Eldoc
support is set up by default on emacs 24.4+. For older versions set, for example, in the desired major mode:(setq-local eldoc-documentation-function #'ggtags-eldoc-function)
imenu
Emacs major modes usually have excellent support for
imenu
so this is not enabled by default. To use:(setq-local imenu-create-index-function #'ggtags-build-imenu-index)
hippie-exp
(setq-local hippie-expand-try-functions-list (cons 'ggtags-try-complete-tag hippie-expand-try-functions-list))
company
company
can useggtags
as completion source viacompany-capf
which is enabled by default.helm
If
helm-mode
is enabledggtags
will use it for completion ifggtags-completing-read-function
is nil.
- Don't choke on tag names start with
-
(#156). ggtags-show-definition
supportsggtags-sort-by-nearness
.- New variable
ggtags-extra-args
. - Unbreak
ggtags-sort-by-nearness
.
- Work with Emacs 25.
ggtags-navigation-mode
is more discreet in displaying lighter whenggtags-enable-navigation-keys
is set to nil.ggtags-make-project
tries harder to find TAG files respectingGTAGSDBPATH
.- Fix error "Selecting deleted buffer" (#89).
ggtags-highlight-tag-delay
is renamed toggtags-highlight-tag
.- Tag highlighting can be disabled by setting
ggtags-highlight-tag
to nil.
- Tags update on save is configurable by
ggtags-update-on-save
. - New command
ggtags-explain-tags
to explain how each file is indexed in current project. Global 6.4+ required. - New user option
ggtags-sort-by-nearness
that sorts matched tags by nearness to current directory.
ggtags-visit-project-root
can visit past projects.eldoc
support enabled for emacs 24.4+.
- Command
ggtags-update-tags
now runs in the background for large projects (perggtags-oversize-limit
) without blocking emacs.
- New navigation command
ggtags-navigation-start-file
. - New variable
ggtags-use-sqlite3
to enable sqlite3 storage.
ggtags-show-definition
shows definition with font locking.
- New command
ggtags-find-tag-mouse
for mouse support. - New command
ggtags-find-definition
. - Variable
ggtags-completing-read-function
restored. ggtags-navigation-isearch-forward
can also be invoked usingM-s s
.- Command
ggtags-global-rerun-search
renamed toggtags-view-search-history
. - The output buffer from
ggtags-view-search-history
looks cleaner. - Search history items can be re-arranged with
C-k
andC-y
.
M-.
(ggtags-find-tag-dwim
) is smarter on new files.- Always update tags for current file on save.
- Can continue search
GTAGSLIBPATH
if search turns up 0 matches. Customisable viaggtags-global-search-libpath-for-reference
.
- Tweak mode-line lighter in
ggtags-navigation-mode
.
- Default
ggtags-auto-jump-to-match
tohistory
. - Add eldoc support; see
ggtags-eldoc-function
. - Improved support for tramp.
- Improve
ggtags-view-tag-history
and tag history navigation. - New customsable variable
ggtags-global-use-color
. - Automatically jump to match from location stored in search history.
See
ggtags-auto-jump-to-match
. - Rename
ggtags-supress-navigation-keys
toggtags-enable-navigation-keys
with a better way to suppress navigation key bindings in some buffers including*ggtags-global*
buffer.
- Record search history and re-run past searches.
- Bookmark or save search to register.
- New command
ggtags-show-definition
. - Project name on mode line.
- Automatically use
.globalrc
orgtags.conf
file at project root. - Better completion based on tag types.
- Use colored output to get column number for jumping to tag.
- Improve detection of stale GTAGS file based on file modification time.
- New customisable variables
ggtags-executable-directory
,ggtags-global-always-update
,ggtags-mode-sticky
andggtags-supress-navigation-keys
. - Other bug fixes.