This package is part of `GNU ELPA <http://elpa.gnu.org>`_ (``M-x
list-packages``) and is also available on `MELPA
-<http://melpa.milkbox.net/#/ggtags>`_.
+<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.1, 24.2, 24.3 and
-trunk. Patches, feature requests and bug reports are welcome. Thanks.
+emacs packages. ``ggtags.el`` is tested in emacs 24.1, 24.2, 24.3,
+24.4 and trunk. Patches, feature requests and bug reports are welcome.
+Thanks.
Features
~~~~~~~~
#. Support `exuberant ctags <http://ctags.sourceforge.net/>`_ backend.
#. Support all Global's output formats: ``grep``, ``ctags-x``,
``cscope`` etc.
-#. Support projects on remote hosts (e.g. via ``tramp``)
-#. Support eldoc
+#. Support projects on remote hosts (e.g. via ``tramp``).
+#. Support eldoc.
+#. Search ``GTAGSLIBPATH`` for references and symbols.
Screenshot
~~~~~~~~~~
-.. figure:: http://i.imgur.com/LX7PVc3.png
+.. figure:: http://i.imgur.com/wx8ZPGe.png
:width: 500px
- :target: http://i.imgur.com/LX7PVc3.png
+ :target: http://i.imgur.com/wx8ZPGe.png
:alt: ggtags.png
Why GNU Global
~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Compile and install Global with ``exuberant-ctags``
-::
+ ::
- ./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags
- make && make install
+
./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.
+ 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/PLUGIN_HOWTO``
+ (``plugin-factory/README`` for Global < 6.5) 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
+ 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.
-Make sure the value of ``<PREFIX>`` agree with step 1.
+ 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.
Config
~~~~~~
To force finding a definition tag, call it with a prefix (``C-u``).
-ggtags-find-reference
+ggtags-find-tag-mouse
+
+ Like ``ggtags-find-tag-dwim`` but suitable for binding to mouse
+ events.
+
+ggtags-find-definition
- Find references to a tag. With ``C-u`` ask for the tag name with
+ 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 a tag that has no definition. With ``C-u`` ask for the tag
+ Find tags that have no definitions. With ``C-u`` ask for the tag
name with completion.
ggtags-find-tag-regexp
Move to previous file.
+``M-=``
+
+ Move to the file where navigation session starts.
+
``M-<``
Move to the first match.
Move to the last match.
-``C-M-s``
+``C-M-s`` or ``M-s s``
Use ``isearch`` to find the match.
Miscellaneous commands
++++++++++++++++++++++
-Commands are avaiable from the ``Ggtags`` menu in ``ggtags-mode``.
+Commands are available from the ``Ggtags`` menu in ``ggtags-mode``.
ggtags-prev-mark
location. ``M-n`` and ``M-p`` move to and display the next/previous
entry.
-ggtags-global-rerun-search
+ggtags-view-search-history
- Re-run a search from search history as kept in
+ View or re-run past searches as kept in
``ggtags-global-search-history``.
ggtags-kill-file-buffers
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 porject in a browser with cross-references.
+ browsing the project 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:
+ ``Eldoc`` support is set up by default on emacs 24.4+. For older
+ versions set, for example, in the desired major mode:
::
* company
``company`` can use ``ggtags`` as completion source via
- ``company-capf`` (enabled by default in emacs 24.4).
+ ``company-capf`` which is enabled by default.
* helm
- If ``helm-mode`` is enabled ``ggtags`` will use it for completion.
+ If ``helm-mode`` is enabled ``ggtags`` will use it for completion if
+ ``ggtags-completing-read-function`` is nil.
NEWS
~~~~
+[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 ligter in ``ggtags-navigation-mode``.
+
[2014-04-05 Sat] 0.8.2
++++++++++++++++++++++