1 =========================================================
2 Emacs frontend to GNU Global source code tagging system
3 =========================================================
5 This package is part of `GNU ELPA <http://elpa.gnu.org>`_ (``M-x
6 list-packages``) and is also available on `MELPA
7 <http://melpa.milkbox.net/#/ggtags>`_.
9 The goal is to make working with GNU Global in Emacs as effortlessly
10 and intuitively as possible and to integrate tightly with standard
11 emacs packages. ``ggtags.el`` is tested in emacs 24.1, 24.2, 24.3 and
12 trunk. Patches, feature requests and bug reports are welcome. Thanks.
17 #. Build on ``compile.el`` for asynchronicity and its large
19 #. Automatically update Global's tag files when needed with tuning for
21 #. Intuitive navigation among multiple matches with mode-line display
22 of current match, total matches and exit status.
23 #. Read tag with completion.
24 #. Show definition at point.
25 #. Jump to #include files.
26 #. Support search history and saving a search to register/bookmark.
28 #. Manage Global's environment variables on a per-project basis.
29 #. Highlight (definition) tag at point.
30 #. Abbreviated display of file names.
31 #. Support all Global search backends: ``grep``, ``idutils`` etc.
32 #. Support `exuberant ctags <http://ctags.sourceforge.net/>`_ backend.
33 #. Support all Global's output formats: ``grep``, ``ctags-x``,
35 #. Support projects on remote hosts (e.g. via ``tramp``)
41 .. figure:: http://i.imgur.com/LX7PVc3.png
43 :target: http://i.imgur.com/LX7PVc3.png
49 The opengrok project composed a feature comparison `table
50 <https://github.com/OpenGrok/OpenGrok/wiki/Comparison-with-Similar-Tools>`_
53 Install Global and plugins
54 ~~~~~~~~~~~~~~~~~~~~~~~~~~
56 1. Compile and install Global with ``exuberant-ctags``
59 ./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags
62 The executable ``ctags`` is unfortunately named because ``emacs`` also
63 includes a command of the same name. So make sure it is from
64 http://ctags.sourceforge.net. See ``plugin-factory/README`` in GNU
65 Global source for further information.
67 2. Install ``pygments`` plugin
71 git clone https://github.com/yoshizow/global-pygments-plugin.git
73 ./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags
75 cp sample.globalrc $HOME/.globalrc
77 Make sure the value of ``<PREFIX>`` agree with step 1.
82 Global with ``exuberant-ctags`` and ``pygments`` plugins can support
83 dozens of programming languages. For example, to enable
84 ``ggtags-mode`` for C/C++/Java modes::
86 (add-hook 'c-mode-common-hook
88 (when (derived-mode-p 'c-mode 'c++-mode 'java-mode)
91 Also see https://github.com/leoliu/ggtags/wiki for more examples.
96 Open any file in a project and type ``M-x ggtags-mode``. Use ``M-.``
97 (``ggtags-find-tag-dwim``) to find the tag at point. If the project
98 has not been indexed (i.e. no ``GTAGS`` file exists), ``ggtags`` will
99 ask for the project root directory and index it recursively.
100 Alternatively one can invoke ``ggtags-create-tags`` to index a
101 directory. The mode line will display the directory name next to the
102 buffer name. If point is at a valid definition tag, it is underlined.
104 ``ggtags`` is similar to the standard ``etags`` package. For example
105 these keys ``M-.``, ``M-,``, ``M-*`` and ``C-M-.`` should work as
106 expected in ``ggtags-mode``.
108 The following search commands are available:
112 Find a tag by context.
114 If point is at a definition tag, find references, and vice versa.
115 If point is at a line that matches ``ggtags-include-pattern``, find
116 the include file instead.
118 To force finding a definition tag, call it with a prefix (``C-u``).
120 ggtags-find-reference
122 Find references to a tag. With ``C-u`` ask for the tag name with
125 ggtags-find-other-symbol
127 Find a tag that has no definition. With ``C-u`` ask for the tag
128 name with completion.
130 ggtags-find-tag-regexp
132 Find definition tags matching a regexp. By default it lists all
133 matching tags in the project. With ``C-u`` restrict the lists to a
138 Use idutils to find matches.
142 Grep for lines matching a regexp. This is usually the slowest.
146 Find a file from all the files indexed by ``gtags``.
150 Do a query replace in all files found in a search.
152 Handling multiple matches
153 +++++++++++++++++++++++++
155 When a search finds multiple matches, a buffer named
156 ``*ggtags-global*`` is popped up and ``ggtags-navigation-mode`` is
157 turned on to facilitate locating the right match.
158 ``ggtags-navigation-mode`` makes a few commands in the
159 ``*ggtags-global*`` buffer globally accessible:
163 Move to the next match.
167 Move to the previous match.
175 Move to previous file.
179 Move to the first match.
183 Move to the last match.
187 Use ``isearch`` to find the match.
191 Found the right match so exit navigation mode. Resumable by ``M-,``
192 (``tags-loop-continue``).
196 Abort and go back to the location where the search was started.
198 Miscellaneous commands
199 ++++++++++++++++++++++
201 Commands are avaiable from the ``Ggtags`` menu in ``ggtags-mode``.
205 Move to the previously (older) visited location. Unlike ``M-*``
206 this doesn't delete the location from the tag ring.
210 Move to the next (newer) visited location.
212 ggtags-view-tag-history
214 Pop to a buffer listing all visited locations from newest to
215 oldest. The buffer is a next error buffer and works with standard
216 commands ``next-error`` and ``previous-error``. In addition ``TAB``
217 and ``S-TAB`` move to next/prev entry, and ``RET`` visits the
218 location. ``M-n`` and ``M-p`` move to and display the next/previous
221 ggtags-global-rerun-search
223 Re-run a search from search history as kept in
224 ``ggtags-global-search-history``.
226 ggtags-kill-file-buffers
228 Kill all file-visiting buffers of current project.
230 ggtags-toggle-project-read-only
232 Toggle opening files in ``read-only`` mode. Handy if the main
233 purpose of source navigation is to read code.
235 ggtags-visit-project-root
237 Open the project root directory in ``dired``.
239 ggtags-delete-tag-files
241 Delete the GTAGS, GRTAGS, GPATH and ID files of current project.
243 ggtags-browse-file-as-hypertext
245 Use ``htags`` to generate HTML of the source tree. This allows
246 browsing the porject in a browser with cross-references.
248 Integration with other packages
249 +++++++++++++++++++++++++++++++
253 ``Eldoc`` support can be enabled by, for example, setting this in
254 the desired major mode with:
258 (setq-local eldoc-documentation-function #'ggtags-eldoc-function)
262 Emacs major modes usually have excellent support for ``imenu`` so
263 this is not enabled by default. To use:
266 (setq-local imenu-create-index-function #'ggtags-build-imenu-index)
271 (setq-local hippie-expand-try-functions-list
272 (cons 'ggtags-try-complete-tag hippie-expand-try-functions-list))
276 ``company`` can use ``ggtags`` as completion source via
277 ``company-capf`` (enabled by default in emacs 24.4).
281 If ``helm-mode`` is enabled ``ggtags`` will use it for completion.
286 [2014-04-05 Sat] 0.8.2
287 ++++++++++++++++++++++
289 #. Default ``ggtags-auto-jump-to-match`` to ``history``.
290 #. Add eldoc support; see ``ggtags-eldoc-function``.
291 #. Improved support for tramp.
293 [2014-03-30 Sun] 0.8.1
294 ++++++++++++++++++++++
296 #. Improve ``ggtags-view-tag-history`` and tag history navigation.
297 #. New customsable variable ``ggtags-global-use-color``.
298 #. Automatically jump to match from location stored in search history.
299 See ``ggtags-auto-jump-to-match``.
300 #. Rename ``ggtags-supress-navigation-keys`` to
301 ``ggtags-enable-navigation-keys`` with a better way to suppress
302 navigation key bindings in some buffers including
303 ``*ggtags-global*`` buffer.
305 [2014-03-24 Mon] 0.8.0
306 ++++++++++++++++++++++
308 #. Record search history and re-run past searches.
309 #. Bookmark or save search to register.
310 #. New command ``ggtags-show-definition``.
311 #. Project name on mode line.
312 #. Automatically use ``.globalrc`` or ``gtags.conf`` file at project
314 #. Better completion based on tag types.
315 #. Use colored output to get column number for jumping to tag.
316 #. Improve detection of stale GTAGS file based on file modification
318 #. New customisable variables ``ggtags-executable-directory``,
319 ``ggtags-global-always-update``, ``ggtags-mode-sticky`` and
320 ``ggtags-supress-navigation-keys``.
326 https://github.com/leoliu/ggtags/issues