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 <https://melpa.org/#/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,
12 24.4 and trunk. Patches, feature requests and bug reports are welcome.
18 #. Build on ``compile.el`` for asynchronicity and its large
20 #. Automatically update Global's tag files when needed with tuning for
22 #. Intuitive navigation among multiple matches with mode-line display
23 of current match, total matches and exit status.
24 #. Read tag with completion.
25 #. Show definition at point.
26 #. Jump to #include files.
27 #. Support search history and saving a search to register/bookmark.
29 #. Manage Global's environment variables on a per-project basis.
30 #. Highlight (definition) tag at point.
31 #. Abbreviated display of file names.
32 #. Support all Global search backends: ``grep``, ``idutils`` etc.
33 #. Support `exuberant ctags <http://ctags.sourceforge.net/>`_ backend.
34 #. Support all Global's output formats: ``grep``, ``ctags-x``,
36 #. Support projects on remote hosts (e.g. via ``tramp``).
38 #. Search ``GTAGSLIBPATH`` for references and symbols.
43 .. figure:: http://i.imgur.com/wx8ZPGe.png
45 :target: http://i.imgur.com/wx8ZPGe.png
51 The opengrok project composed a feature comparison `table
52 <https://github.com/OpenGrok/OpenGrok/wiki/Comparison-with-Similar-Tools>`_
55 Install Global and plugins
56 ~~~~~~~~~~~~~~~~~~~~~~~~~~
58 1. Compile and install Global with ``exuberant-ctags``
61 ./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags
64 The executable ``ctags`` is unfortunately named because ``emacs``
65 also includes a command of the same name. So make sure it is from
66 http://ctags.sourceforge.net. See ``plugin-factory/PLUGIN_HOWTO``
67 (``plugin-factory/README`` for Global < 6.5) in GNU Global
68 source for further information.
70 2. Install ``pygments`` plugin
72 The ``pygments`` plugin has been included in ``global`` since
73 version ``6.3.2``. ``pip install pygments`` is the only step
74 required. Note the plugin is not activated by the default
75 ``gtags.conf`` or ``.globalrc``. See
76 ``global/plugin-factory/PLUGIN_HOWTO.pygments`` for details.
78 The following instructions are for older ``global``.
82 git clone https://github.com/yoshizow/global-pygments-plugin.git
83 cd global-pygments-plugin/
85 ./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags
87 cp sample.globalrc $HOME/.globalrc
89 Make sure the value of ``<PREFIX>`` agree with step 1.
94 Global with ``exuberant-ctags`` and ``pygments`` plugins can support
95 dozens of programming languages. For example, to enable
96 ``ggtags-mode`` for C/C++/Java modes::
98 (add-hook 'c-mode-common-hook
100 (when (derived-mode-p 'c-mode 'c++-mode 'java-mode)
103 Also see https://github.com/leoliu/ggtags/wiki for more examples.
108 Open any file in a project and type ``M-x ggtags-mode``. Use ``M-.``
109 (``ggtags-find-tag-dwim``) to find the tag at point. If the project
110 has not been indexed (i.e. no ``GTAGS`` file exists), ``ggtags`` will
111 ask for the project root directory and index it recursively.
112 Alternatively one can invoke ``ggtags-create-tags`` to index a
113 directory. The mode line will display the directory name next to the
114 buffer name. If point is at a valid definition tag, it is underlined.
116 ``ggtags`` is similar to the standard ``etags`` package. For example
117 these keys ``M-.``, ``M-,``, ``M-*`` and ``C-M-.`` should work as
118 expected in ``ggtags-mode``.
120 The following search commands are available:
124 Find a tag by context.
126 If point is at a definition tag, find references, and vice versa.
127 If point is at a line that matches ``ggtags-include-pattern``, find
128 the include file instead.
130 To force finding a definition tag, call it with a prefix (``C-u``).
132 ggtags-find-tag-mouse
134 Like ``ggtags-find-tag-dwim`` but suitable for binding to mouse
137 ggtags-find-definition
139 Find definition tags. With ``C-u`` ask for the tag name with
142 ggtags-find-reference
144 Find reference tags. With ``C-u`` ask for the tag name with completion.
146 ggtags-find-other-symbol
148 Find tags that have no definitions. With ``C-u`` ask for the tag
149 name with completion.
151 ggtags-find-tag-regexp
153 Find definition tags matching a regexp. By default it lists all
154 matching tags in the project. With ``C-u`` restrict the lists to a
159 Use idutils to find matches.
163 Grep for lines matching a regexp. This is usually the slowest.
167 Find a file from all the files indexed by ``gtags``.
171 Do a query replace in all files found in a search.
173 Handling multiple matches
174 +++++++++++++++++++++++++
176 When a search finds multiple matches, a buffer named
177 ``*ggtags-global*`` is popped up and ``ggtags-navigation-mode`` is
178 turned on to facilitate locating the right match.
179 ``ggtags-navigation-mode`` makes a few commands in the
180 ``*ggtags-global*`` buffer globally accessible:
184 Move to the next match.
188 Move to the previous match.
196 Move to previous file.
200 Move to the file where navigation session starts.
204 Move to the first match.
208 Move to the last match.
210 ``C-M-s`` or ``M-s s``
212 Use ``isearch`` to find the match.
216 Found the right match so exit navigation mode. Resumable by ``M-,``
217 (``tags-loop-continue``).
221 Abort and go back to the location where the search was started.
223 Miscellaneous commands
224 ++++++++++++++++++++++
226 Commands are available from the ``Ggtags`` menu in ``ggtags-mode``.
230 Move to the previously (older) visited location. Unlike ``M-*``
231 this doesn't delete the location from the tag ring.
235 Move to the next (newer) visited location.
237 ggtags-view-tag-history
239 Pop to a buffer listing all visited locations from newest to
240 oldest. The buffer is a next error buffer and works with standard
241 commands ``next-error`` and ``previous-error``. In addition ``TAB``
242 and ``S-TAB`` move to next/prev entry, and ``RET`` visits the
243 location. ``M-n`` and ``M-p`` move to and display the next/previous
246 ggtags-view-search-history
248 View or re-run past searches as kept in
249 ``ggtags-global-search-history``.
251 ggtags-kill-file-buffers
253 Kill all file-visiting buffers of current project.
255 ggtags-toggle-project-read-only
257 Toggle opening files in ``read-only`` mode. Handy if the main
258 purpose of source navigation is to read code.
260 ggtags-visit-project-root
262 Open the project root directory in ``dired``.
266 Delete the GTAGS, GRTAGS, GPATH and ID files of current project.
270 Explain how each file is indexed in current project.
272 ggtags-browse-file-as-hypertext
274 Use ``htags`` to generate HTML of the source tree. This allows
275 browsing the project in a browser with cross-references.
277 Integration with other packages
278 +++++++++++++++++++++++++++++++
282 ``Eldoc`` support is set up by default on emacs 24.4+. For older
283 versions set, for example, in the desired major mode:
287 (setq-local eldoc-documentation-function #'ggtags-eldoc-function)
291 Emacs major modes usually have excellent support for ``imenu`` so
292 this is not enabled by default. To use:
295 (setq-local imenu-create-index-function #'ggtags-build-imenu-index)
300 (setq-local hippie-expand-try-functions-list
301 (cons 'ggtags-try-complete-tag hippie-expand-try-functions-list))
305 ``company`` can use ``ggtags`` as completion source via
306 ``company-capf`` which is enabled by default.
310 If ``helm-mode`` is enabled ``ggtags`` will use it for completion if
311 ``ggtags-completing-read-function`` is nil.
316 [2015-12-15 Tue] 0.8.11
317 +++++++++++++++++++++++
319 #. ``ggtags-highlight-tag-delay`` is renamed to
320 ``ggtags-highlight-tag``.
321 #. Tag highlighting can be disabled by setting
322 ``ggtags-highlight-tag`` to nil.
324 [2015-06-12 Fri] 0.8.10
325 +++++++++++++++++++++++
327 #. Tags update on save is configurable by ``ggtags-update-on-save``.
328 #. New command ``ggtags-explain-tags`` to explain how each file is
329 indexed in current project. Global 6.4+ required.
330 #. New user option ``ggtags-sort-by-nearness`` that sorts matched tags
331 by nearness to current directory.
333 [2015-01-16 Fri] 0.8.9
334 ++++++++++++++++++++++
336 #. ``ggtags-visit-project-root`` can visit past projects.
337 #. ``eldoc`` support enabled for emacs 24.4+.
339 [2014-12-03 Wed] 0.8.8
340 ++++++++++++++++++++++
342 #. Command ``ggtags-update-tags`` now runs in the background for large
343 projects (per ``ggtags-oversize-limit``) without blocking emacs.
345 [2014-11-10 Mon] 0.8.7
346 ++++++++++++++++++++++
348 #. New navigation command ``ggtags-navigation-start-file``.
349 #. New variable ``ggtags-use-sqlite3`` to enable sqlite3 storage.
351 [2014-09-12 Fri] 0.8.6
352 ++++++++++++++++++++++
354 #. ``ggtags-show-definition`` shows definition with font locking.
356 [2014-06-22 Sun] 0.8.5
357 ++++++++++++++++++++++
359 #. New command ``ggtags-find-tag-mouse`` for mouse support.
360 #. New command ``ggtags-find-definition``.
361 #. Variable ``ggtags-completing-read-function`` restored.
362 #. ``ggtags-navigation-isearch-forward`` can also be invoked using
364 #. Command ``ggtags-global-rerun-search`` renamed to
365 ``ggtags-view-search-history``.
366 #. The output buffer from ``ggtags-view-search-history`` looks
368 #. Search history items can be re-arranged with ``C-k`` and ``C-y``.
370 [2014-05-06 Tue] 0.8.4
371 ++++++++++++++++++++++
373 #. ``M-.`` (``ggtags-find-tag-dwim``) is smarter on new files.
374 #. Always update tags for current file on save.
375 #. Can continue search ``GTAGSLIBPATH`` if search turns up 0 matches.
376 Customisable via ``ggtags-global-search-libpath-for-reference``.
378 [2014-04-12 Sat] 0.8.3
379 ++++++++++++++++++++++
381 #. Tweak mode-line ligter in ``ggtags-navigation-mode``.
383 [2014-04-05 Sat] 0.8.2
384 ++++++++++++++++++++++
386 #. Default ``ggtags-auto-jump-to-match`` to ``history``.
387 #. Add eldoc support; see ``ggtags-eldoc-function``.
388 #. Improved support for tramp.
390 [2014-03-30 Sun] 0.8.1
391 ++++++++++++++++++++++
393 #. Improve ``ggtags-view-tag-history`` and tag history navigation.
394 #. New customsable variable ``ggtags-global-use-color``.
395 #. Automatically jump to match from location stored in search history.
396 See ``ggtags-auto-jump-to-match``.
397 #. Rename ``ggtags-supress-navigation-keys`` to
398 ``ggtags-enable-navigation-keys`` with a better way to suppress
399 navigation key bindings in some buffers including
400 ``*ggtags-global*`` buffer.
402 [2014-03-24 Mon] 0.8.0
403 ++++++++++++++++++++++
405 #. Record search history and re-run past searches.
406 #. Bookmark or save search to register.
407 #. New command ``ggtags-show-definition``.
408 #. Project name on mode line.
409 #. Automatically use ``.globalrc`` or ``gtags.conf`` file at project
411 #. Better completion based on tag types.
412 #. Use colored output to get column number for jumping to tag.
413 #. Improve detection of stale GTAGS file based on file modification
415 #. New customisable variables ``ggtags-executable-directory``,
416 ``ggtags-global-always-update``, ``ggtags-mode-sticky`` and
417 ``ggtags-supress-navigation-keys``.
423 https://github.com/leoliu/ggtags/issues