-=========================
- Use GNU Global in Emacs
-=========================
+=========================================================
+ Emacs frontend to GNU Global source code tagging system
+=========================================================
-A package for working with `GNU Global
-<http://www.gnu.org/software/global>`_ source tagging system in Emacs.
+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>`_.
-This package is part of `GNU ELPA <http://elpa.gnu.org>`_
-(``M-x list-packages``).
-
-Patches, feature requests and bug reports are welcome. Thanks.
+``ggtags.el`` is tested in emacs 24.1, 24.2, 24.3 and trunk. Patches,
+feature requests and bug reports are welcome. Thanks.
Features
~~~~~~~~
-#. Automatically run ``global -u`` when needed
-#. Highlight valid tag at point
-#. Built on top of ``compile.el`` (asynchonrous and other nice
- features)
-#. Support all output formats of ``global``: ``grep``, ``ctags-x``,
+#. Automatically update Global's tag files when needed with tuning for
+ large source trees.
+#. Build on ``compile.el`` for asynchronicity and its large
+ feature-set.
+#. Intuitive navigation among multiple matches with mode-line display
+ of current match, total matches and exit status.
+#. Manage Global's environment variables on a per-project basis.
+#. Support all Global search backends: ``grep``, ``idutils`` etc.
+#. Query replace.
+#. Highlight (definition) tag at point.
+#. Abbreviated display of file names.
+#. Support `exuberant ctags <http://ctags.sourceforge.net/>`_ backend.
+#. Support all Global's output formats: ``grep``, ``ctags-x``,
``cscope`` etc.
-#. Abbreviated display of file names
Why GNU Global
~~~~~~~~~~~~~~
-The opengrok project composed a feature comparison table between a few
-tools. The `page
-<http://hub.opensolaris.org/bin/view/Project+opengrok>`_ was taken
-offline after 2013-03-24 but `here <http://i.imgur.com/IQCPQ0j.png>`_
-is a backup.
+The opengrok project composed a feature comparison `table
+<https://github.com/OpenGrok/OpenGrok/wiki/Comparison-with-Similar-Tools>`_
+between a few tools.
Screenshot
~~~~~~~~~~
-.. figure:: http://i.imgur.com/d430rmm.png
+.. figure:: http://i.imgur.com/E5Gr56m.png
:width: 500px
- :target: http://i.imgur.com/d430rmm.png
+ :target: http://i.imgur.com/E5Gr56m.png
:alt: ggtags.png
Config
(when (derived-mode-p 'c-mode 'c++-mode 'java-mode)
(ggtags-mode 1))))
+More languages/modes are supported if `GNU Global
+<http://www.gnu.org/software/global>`_ is compiled with
+``--with-exuberant-ctags`` to support `exuberant ctags
+<http://ctags.sourceforge.net/>`_. Also set the environment variable
+``GTAGSCONF`` to the correct location of ``gtags.conf``. For example::
+
+ export GTAGSCONF=/usr/local/share/gtags/gtags.conf
+
+See ``plugin-factory/README`` in GNU Global source for further
+information.
+
+Also see https://github.com/leoliu/ggtags/wiki for more examples.
+
Tutorial
~~~~~~~~
``M-.`` finds definitions or references according to the tag at point,
i.e. if point is at a definition tag find references and vice versa.
-``C-u M-.`` is verbose and will ask you the name - with completion
-- and the type of tag to search.
-
-If multiple matches are found, navigation mode is entered. In this
-mode, ``M-n`` and ``M-p`` moves to next and previous match, ``M-}``
-and ``M-{`` to next and previous file respectively. ``M-o`` toggles
-between full and abbreviated displays of file names in the auxiliary
-popup window. When you locate the right match, press RET to finish
-which hides the auxiliary window and exits navigation mode. You can
-resume the search using ``M-,``. To abort the search press ``M-*``.
+``M-]`` finds references.
+
+If multiple matches are found, navigation mode is entered, the
+mode-line lighter changed, and a navigation menu-bar entry presented.
+In this mode, ``M-n`` and ``M-p`` moves to next and previous match,
+``M-}`` and ``M-{`` to next and previous file respectively. ``M-o``
+toggles between full and abbreviated displays of file names in the
+auxiliary popup window. When you locate the right match, press RET to
+finish which hides the auxiliary window and exits navigation mode. You
+can continue the search using ``M-,``. To abort the search press
+``M-*``.
Normally after a few searches a dozen buffers are created visiting
files tracked by GNU Global. ``C-c M-k`` helps clean them up.
+Check the menu-bar entry ``Ggtags`` for other useful commands.
+
Development
~~~~~~~~~~~
-The goal is to make working with GNU Global in Emacs as effortless and
-intuitively as possible.
+The goal is to make working with GNU Global in Emacs as effortlessly
+and intuitively as possible.
Bugs
~~~~