========================================================= Emacs frontend to GNU Global source code tagging system

This package is part of GNU ELPA <http://elpa.gnu.org>_ (M-x list-packages) and is also available on MELPA <https://melpa.org/#/ggtags>_.

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.

Features

#. 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/universal ctags <https://ctags.io/>`_ 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.

Screenshot

.. figure:: http://i.imgur.com/wx8ZPGe.png :width: 500px :target: http://i.imgur.com/wx8ZPGe.png :alt: ggtags.png

Why GNU Global

The opengrok project composed a feature comparison `table
<https://github.com/OpenGrok/OpenGrok/wiki/Comparison-with-Similar-Tools>`_
between a few tools.

Install Global and plugins

1. Compile and install Global with universal-ctags ::

   ./configure --prefix= --with-universal-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 https://ctags.io. 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 https://github.com/yoshizow/global-pygments-plugin.git cd global-pygments-plugin/ sh reconf.sh ./configure --prefix= --with-universal-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 ``universal-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-,`` 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.

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

Miscellaneous commands
++++++++++++++++++++++

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

ggtags-prev-mark

   Move to the previously (older) visited location. Unlike ``M-,``
   (``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
   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-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.

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.

NEWS
~~~~

(devel)
+++++++

#. Drop support for Emacs < 25.
#. Integration with ``xref.el``.
#. Make ``ggtags-sort-by-nearness`` actually work.

[2018-07-25 Wed] 0.8.13
+++++++++++++++++++++++

#. Don't choke on tag names start with ``-`` (`#156
   <https://github.com/leoliu/ggtags/issues/156>`_).
#. ``ggtags-show-definition`` supports ``ggtags-sort-by-nearness``.
#. New variable ``ggtags-extra-args``.
#. Unbreak ``ggtags-sort-by-nearness``.

[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
   ``GTAGSDBPATH``.
#. Fix error "Selecting deleted buffer"
   (`#89 <https://github.com/leoliu/ggtags/issues/89>`_).
   
[2015-12-15 Tue] 0.8.11
+++++++++++++++++++++++

#. ``ggtags-highlight-tag-delay`` is renamed to
   ``ggtags-highlight-tag``.
#. 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
   ``ggtags-view-search-history``.
#. The output buffer from ``ggtags-view-search-history`` looks
   cleaner.
#. 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
   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`` and
   ``ggtags-supress-navigation-keys``.
#. Other bug fixes.

Bugs
~~~~

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