Emacs frontend to GNU Global source code tagging system

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.1, 24.2, 24.3 and trunk. Patches, feature requests and bug reports are welcome. Thanks.

Features

1. Build on compile.el for asynchronicity and its large feature-set.
2. Automatically update Global's tag files when needed with tuning for large source trees.
3. Intuitive navigation among multiple matches with mode-line display of current match, total matches and exit status.
4. Read tag with completion.
5. Show definition at point.
6. Jump to #include files.
7. Support search history and saving a search to register/bookmark.
8. Query replace.
9. Manage Global's environment variables on a per-project basis.
10. Highlight (definition) tag at point.
11. Abbreviated display of file names.
12. Support all Global search backends: grep, idutils etc.
13. Support exuberant ctags backend.
14. Support all Global's output formats: grep, ctags-x, cscope etc.
15. Support projects on remote hosts (e.g. via tramp)

Screenshot

Why GNU Global

The opengrok project composed a feature comparison table between a few tools.

Install Global and plugins

1. 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 because emacs also includes a command of the same name. So make sure it is from http://ctags.sourceforge.net. See plugin-factory/README in GNU Global source for further information.

2. Install pygments plugin

pip install pygments
git clone https://github.com/yoshizow/global-pygments-plugin.git
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.

Config

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.

Usage

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-,, 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-reference

Find references to a tag. With C-u ask for the tag name with completion.

ggtags-find-other-symbol

Find a tag that has no definition. 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.

Handling multiple matches

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

M->

Move to the last match.

C-M-s

Use isearch to find the match.

RET

Found the right match so exit navigation mode. Resumable by M-, (tags-loop-continue).

M-*

Abort and go back to the location where the search was started.

Miscellaneous commands

Commands are avaiable from the Ggtags menu in ggtags-mode.

ggtags-prev-mark

Move to the previously (older) visited location. Unlike M-* 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 commands next-error and previous-error. In addition TAB and S-TAB move to next/prev entry, and RET visits the location. M-n and M-p move to and display the next/previous entry.

ggtags-global-rerun-search

Re-run a search from search history 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-tag-files

Delete the GTAGS, GRTAGS, GPATH and ID files of current project.

ggtags-browse-file-as-hypertext

Use htags to generate HTML of the source tree. This allows browsing the porject in a browser with cross-references.

Integration with other packages

• eldoc

  Eldoc support can be enabled by, for example, setting this in the desired major mode with:

  (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))
  

NEWS

[2014-03-30 Sun] 0.8.1

1. Improve ggtags-view-tag-history and tag history navigation.
2. New customsable variable ggtags-global-use-color.
3. Automatically jump to match from location stored in search history. See ggtags-auto-jump-to-match.
4. Rename ggtags-supress-navigation-keys to ggtags-enable-navigation-keys with a better way to suppress navigation key bindings in some buffers including *ggtags-global* buffer.

[2014-03-24 Mon] 0.8.0

1. Record search history and re-run past searches.
2. Bookmark or save search to register.
3. New command ggtags-show-definition.
4. Project name on mode line.
5. Automatically use .globalrc or gtags.conf file at project root.
6. Better completion based on tag types.
7. Use colored output to get column number for jumping to tag.
8. Improve detection of stale GTAGS file based on file modification time.
9. New customisable variables ggtags-executable-directory, ggtags-global-always-update, ggtags-mode-sticky and ggtags-supress-navigation-keys.
10. Other bug fixes.

Bugs

https://github.com/leoliu/ggtags/issues