GNU ELPA - ggtags

Description: emacs frontend to GNU Global source code tagging system

Latest: ggtags-0.8.12.el, 2016-Oct-02, 108kB

Home page:

Browse ELPA's repository: CGit or Gitweb

Full description

 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 and 25. Patches,
feature requests and bug reports are welcome. Thanks.


#. Build on ``compile.el`` for asynchronicity and its large
#. 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.


.. figure::
   :width: 500px
   :alt: ggtags.png

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 See ``plugin-factory/PLUGIN_HOWTO``
   (``plugin-factory/README`` for Global < 6.5) in GNU Global
   source for further information.

2. Install ``pygments`` plugin

   The ``pygments`` plugin has been included in ``global`` since
   version ``6.3.2``. ``pip install pygments`` is the only step
   required. Note the plugin is not activated by the default
   ``gtags.conf`` or ``.globalrc``. See
   ``global/plugin-factory/PLUGIN_HOWTO.pygments`` for details.

   The following instructions are for older ``global``.

     pip install pygments
     git clone
     cd global-pygments-plugin/
     ./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 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

The following search commands are available:


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


   Like ``ggtags-find-tag-dwim`` but suitable for binding to mouse


   Find definition tags. With ``C-u`` ask for the tag name with


   Find reference tags. With ``C-u`` ask for the tag name with completion.


   Find tags that have no definitions. With ``C-u`` ask for the tag
   name with completion.


   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.


   Use idutils to find matches.


   Grep for lines matching a regexp. This is usually the slowest.


   Find a file from all the files indexed by ``gtags``.


   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:


   Move to the next match.


   Move to the previous match.


   Move to next file.


   Move to previous file.


   Move to the file where navigation session starts.


   Move to the first match.


   Move to the last match.

``C-M-s`` or ``M-s s``

   Use ``isearch`` to find the match.


   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.

Miscellaneous commands

Commands are available from the ``Ggtags`` menu in ``ggtags-mode``.


   Move to the previously (older) visited location. Unlike ``M-,``
   (``M-*`` if Emacs < 25) this doesn't delete the location from the
   tag ring.


   Move to the next (newer) visited location.


   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


   View or re-run past searches as kept in


   Kill all file-visiting buffers of current project.


   Toggle opening files in ``read-only`` mode. Handy if the main
   purpose of source navigation is to read code.


   Open the project root directory in ``dired``.


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


  Explain how each file is indexed in current project.


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

Integration with other packages

* 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 use ``ggtags`` as completion source via
  ``company-capf`` which is enabled by default.

* helm

  If ``helm-mode`` is enabled ``ggtags`` will use it for completion if
  ``ggtags-completing-read-function`` is nil.


[2016-10-02 Sun] 0.8.12

#. Work with Emacs 25.
#. ``ggtags-navigation-mode`` is more discreet in displaying lighter
   when ``ggtags-enable-navigation-keys`` is set to nil.
#. ``ggtags-make-project`` tries harder to find TAG files respecting
#. Fix error "Selecting deleted buffer"
   (`#89 <>`_).
[2015-12-15 Tue] 0.8.11

#. ``ggtags-highlight-tag-delay`` is renamed to
#. Tag highlighting can be disabled by setting
   ``ggtags-highlight-tag`` to nil.

[2015-06-12 Fri] 0.8.10

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

[2015-01-16 Fri] 0.8.9

#. ``ggtags-visit-project-root`` can visit past projects.
#. ``eldoc`` support enabled for emacs 24.4+.

[2014-12-03 Wed] 0.8.8

#. Command ``ggtags-update-tags`` now runs in the background for large
   projects (per ``ggtags-oversize-limit``) without blocking emacs.

[2014-11-10 Mon] 0.8.7

#. New navigation command ``ggtags-navigation-start-file``.
#. New variable ``ggtags-use-sqlite3`` to enable sqlite3 storage.

[2014-09-12 Fri] 0.8.6

#. ``ggtags-show-definition`` shows definition with font locking.

[2014-06-22 Sun] 0.8.5

#. 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 using
   ``M-s s``.
#. Command ``ggtags-global-rerun-search`` renamed to
#. The output buffer from ``ggtags-view-search-history`` looks
#. Search history items can be re-arranged with ``C-k`` and ``C-y``.

[2014-05-06 Tue] 0.8.4

#. ``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 via ``ggtags-global-search-libpath-for-reference``.

[2014-04-12 Sat] 0.8.3

#. Tweak mode-line lighter in ``ggtags-navigation-mode``.

[2014-04-05 Sat] 0.8.2

#. Default ``ggtags-auto-jump-to-match`` to ``history``.
#. Add eldoc support; see ``ggtags-eldoc-function``.
#. Improved support for tramp.

[2014-03-30 Sun] 0.8.1

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

#. 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`` or ``gtags.conf`` file at project
#. 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
#. New customisable variables ``ggtags-executable-directory``,
   ``ggtags-global-always-update``, ``ggtags-mode-sticky`` and
#. Other bug fixes.


Old versions

ggtags-0.8.9.el2015-Jan-17 104kB
ggtags-0.8.8.el2014-Dec-03 103kB
ggtags-0.8.7.el2014-Nov-10 102kB
ggtags-0.8.11.el2015-Dec-15 106kB
ggtags-0.8.10.el2015-Jun-12 106kB