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,
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`` also
65 includes a command of the same name. So make sure it is from
66 http://ctags.sourceforge.net. See ``plugin-factory/README`` in GNU
67 Global source for further information.
69 2. Install ``pygments`` plugin
71 The ``pygments`` plugin has been included in ``global`` since
72 version ``6.3.2``. ``pip install pygments`` is the only step
73 required. Note the plugin is not activated by the default
74 ``gtags.conf`` or ``.globalrc``. See
75 ``global/plugin-factory/PLUGIN_HOWTO.pygments`` for details.
77 The following instructions are for older ``global``.
81 git clone https://github.com/yoshizow/global-pygments-plugin.git
82 cd global-pygments-plugin/
84 ./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags
86 cp sample.globalrc $HOME/.globalrc
88 Make sure the value of ``<PREFIX>`` agree with step 1.
93 Global with ``exuberant-ctags`` and ``pygments`` plugins can support
94 dozens of programming languages. For example, to enable
95 ``ggtags-mode`` for C/C++/Java modes::
97 (add-hook 'c-mode-common-hook
99 (when (derived-mode-p 'c-mode 'c++-mode 'java-mode)
102 Also see https://github.com/leoliu/ggtags/wiki for more examples.
107 Open any file in a project and type ``M-x ggtags-mode``. Use ``M-.``
108 (``ggtags-find-tag-dwim``) to find the tag at point. If the project
109 has not been indexed (i.e. no ``GTAGS`` file exists), ``ggtags`` will
110 ask for the project root directory and index it recursively.
111 Alternatively one can invoke ``ggtags-create-tags`` to index a
112 directory. The mode line will display the directory name next to the
113 buffer name. If point is at a valid definition tag, it is underlined.
115 ``ggtags`` is similar to the standard ``etags`` package. For example
116 these keys ``M-.``, ``M-,``, ``M-*`` and ``C-M-.`` should work as
117 expected in ``ggtags-mode``.
119 The following search commands are available:
123 Find a tag by context.
125 If point is at a definition tag, find references, and vice versa.
126 If point is at a line that matches ``ggtags-include-pattern``, find
127 the include file instead.
129 To force finding a definition tag, call it with a prefix (``C-u``).
131 ggtags-find-tag-mouse
133 Like ``ggtags-find-tag-dwim`` but suitable for binding to mouse
136 ggtags-find-definition
138 Find definition tags. With ``C-u`` ask for the tag name with
141 ggtags-find-reference
143 Find reference tags. With ``C-u`` ask for the tag name with completion.
145 ggtags-find-other-symbol
147 Find tags that have no definitions. With ``C-u`` ask for the tag
148 name with completion.
150 ggtags-find-tag-regexp
152 Find definition tags matching a regexp. By default it lists all
153 matching tags in the project. With ``C-u`` restrict the lists to a
158 Use idutils to find matches.
162 Grep for lines matching a regexp. This is usually the slowest.
166 Find a file from all the files indexed by ``gtags``.
170 Do a query replace in all files found in a search.
172 Handling multiple matches
173 +++++++++++++++++++++++++
175 When a search finds multiple matches, a buffer named
176 ``*ggtags-global*`` is popped up and ``ggtags-navigation-mode`` is
177 turned on to facilitate locating the right match.
178 ``ggtags-navigation-mode`` makes a few commands in the
179 ``*ggtags-global*`` buffer globally accessible:
183 Move to the next match.
187 Move to the previous match.
195 Move to previous file.
199 Move to the file where navigation session starts.
203 Move to the first match.
207 Move to the last match.
209 ``C-M-s`` or ``M-s s``
211 Use ``isearch`` to find the match.
215 Found the right match so exit navigation mode. Resumable by ``M-,``
216 (``tags-loop-continue``).
220 Abort and go back to the location where the search was started.
222 Miscellaneous commands
223 ++++++++++++++++++++++
225 Commands are avaiable from the ``Ggtags`` menu in ``ggtags-mode``.
229 Move to the previously (older) visited location. Unlike ``M-*``
230 this doesn't delete the location from the tag ring.
234 Move to the next (newer) visited location.
236 ggtags-view-tag-history
238 Pop to a buffer listing all visited locations from newest to
239 oldest. The buffer is a next error buffer and works with standard
240 commands ``next-error`` and ``previous-error``. In addition ``TAB``
241 and ``S-TAB`` move to next/prev entry, and ``RET`` visits the
242 location. ``M-n`` and ``M-p`` move to and display the next/previous
245 ggtags-view-search-history
247 View or re-run past searches as kept in
248 ``ggtags-global-search-history``.
250 ggtags-kill-file-buffers
252 Kill all file-visiting buffers of current project.
254 ggtags-toggle-project-read-only
256 Toggle opening files in ``read-only`` mode. Handy if the main
257 purpose of source navigation is to read code.
259 ggtags-visit-project-root
261 Open the project root directory in ``dired``.
265 Delete the GTAGS, GRTAGS, GPATH and ID files of current project.
267 ggtags-browse-file-as-hypertext
269 Use ``htags`` to generate HTML of the source tree. This allows
270 browsing the porject in a browser with cross-references.
272 Integration with other packages
273 +++++++++++++++++++++++++++++++
277 ``Eldoc`` support is set up by default on emacs 24.4+. For older
278 versions set, for example, in the desired major mode:
282 (setq-local eldoc-documentation-function #'ggtags-eldoc-function)
286 Emacs major modes usually have excellent support for ``imenu`` so
287 this is not enabled by default. To use:
290 (setq-local imenu-create-index-function #'ggtags-build-imenu-index)
295 (setq-local hippie-expand-try-functions-list
296 (cons 'ggtags-try-complete-tag hippie-expand-try-functions-list))
300 ``company`` can use ``ggtags`` as completion source via
301 ``company-capf`` which is enabled by default.
305 If ``helm-mode`` is enabled ``ggtags`` will use it for completion if
306 ``ggtags-completing-read-function`` is nil.
311 [2015-01-16 Fri] 0.8.9
312 ++++++++++++++++++++++
314 #. ``ggtags-visit-project-root`` can visit past projects.
315 #. ``eldoc`` support enabled for emacs 24.4+.
317 [2014-12-03 Wed] 0.8.8
318 ++++++++++++++++++++++
320 #. Command ``ggtags-update-tags`` now runs in the background for large
321 projects (per ``ggtags-oversize-limit``) without blocking emacs.
323 [2014-11-10 Mon] 0.8.7
324 ++++++++++++++++++++++
326 #. New navigation command ``ggtags-navigation-start-file``.
327 #. New variable ``ggtags-use-sqlite3`` to enable sqlite3 storage.
329 [2014-09-12 Fri] 0.8.6
330 ++++++++++++++++++++++
332 #. ``ggtags-show-definition`` shows definition with font locking.
334 [2014-06-22 Sun] 0.8.5
335 ++++++++++++++++++++++
337 #. New command ``ggtags-find-tag-mouse`` for mouse support.
338 #. New command ``ggtags-find-definition``.
339 #. Variable ``ggtags-completing-read-function`` restored.
340 #. ``ggtags-navigation-isearch-forward`` can also be invoked using
342 #. Command ``ggtags-global-rerun-search`` renamed to
343 ``ggtags-view-search-history``.
344 #. The output buffer from ``ggtags-view-search-history`` looks
346 #. Search history items can be re-arranged with ``C-k`` and ``C-y``.
348 [2014-05-06 Tue] 0.8.4
349 ++++++++++++++++++++++
351 #. ``M-.`` (``ggtags-find-tag-dwim``) is smarter on new files.
352 #. Always update tags for current file on save.
353 #. Can continue search ``GTAGSLIBPATH`` if search turns up 0 matches.
354 Customisable via ``ggtags-global-search-libpath-for-reference``.
356 [2014-04-12 Sat] 0.8.3
357 ++++++++++++++++++++++
359 #. Tweak mode-line ligter in ``ggtags-navigation-mode``.
361 [2014-04-05 Sat] 0.8.2
362 ++++++++++++++++++++++
364 #. Default ``ggtags-auto-jump-to-match`` to ``history``.
365 #. Add eldoc support; see ``ggtags-eldoc-function``.
366 #. Improved support for tramp.
368 [2014-03-30 Sun] 0.8.1
369 ++++++++++++++++++++++
371 #. Improve ``ggtags-view-tag-history`` and tag history navigation.
372 #. New customsable variable ``ggtags-global-use-color``.
373 #. Automatically jump to match from location stored in search history.
374 See ``ggtags-auto-jump-to-match``.
375 #. Rename ``ggtags-supress-navigation-keys`` to
376 ``ggtags-enable-navigation-keys`` with a better way to suppress
377 navigation key bindings in some buffers including
378 ``*ggtags-global*`` buffer.
380 [2014-03-24 Mon] 0.8.0
381 ++++++++++++++++++++++
383 #. Record search history and re-run past searches.
384 #. Bookmark or save search to register.
385 #. New command ``ggtags-show-definition``.
386 #. Project name on mode line.
387 #. Automatically use ``.globalrc`` or ``gtags.conf`` file at project
389 #. Better completion based on tag types.
390 #. Use colored output to get column number for jumping to tag.
391 #. Improve detection of stale GTAGS file based on file modification
393 #. New customisable variables ``ggtags-executable-directory``,
394 ``ggtags-global-always-update``, ``ggtags-mode-sticky`` and
395 ``ggtags-supress-navigation-keys``.
401 https://github.com/leoliu/ggtags/issues