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 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/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
+ 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
- Find references to a tag. With ``C-u`` ask for the tag name with
+ 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 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.
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
Open the project root directory in ``dired``.
-ggtags-delete-tag-files
+ggtags-delete-tags
Delete the GTAGS, GRTAGS, GPATH and ID files of current project.
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
(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
+~~~~
+
+[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
+++++++++++++++++++++++
+
+#. 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
~~~~