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``).
37 #. Search ``GTAGSLIBPATH`` for references and symbols.
42 .. figure:: http://i.imgur.com/LX7PVc3.png
44 :target: http://i.imgur.com/LX7PVc3.png
50 The opengrok project composed a feature comparison `table
51 <https://github.com/OpenGrok/OpenGrok/wiki/Comparison-with-Similar-Tools>`_
54 Install Global and plugins
55 ~~~~~~~~~~~~~~~~~~~~~~~~~~
57 1. Compile and install Global with ``exuberant-ctags``
60 ./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags
63 The executable ``ctags`` is unfortunately named because ``emacs`` also
64 includes a command of the same name. So make sure it is from
65 http://ctags.sourceforge.net. See ``plugin-factory/README`` in GNU
66 Global source for further information.
68 2. Install ``pygments`` plugin
72 git clone https://github.com/yoshizow/global-pygments-plugin.git
74 ./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags
76 cp sample.globalrc $HOME/.globalrc
78 Make sure the value of ``<PREFIX>`` agree with step 1.
83 Global with ``exuberant-ctags`` and ``pygments`` plugins can support
84 dozens of programming languages. For example, to enable
85 ``ggtags-mode`` for C/C++/Java modes::
87 (add-hook 'c-mode-common-hook
89 (when (derived-mode-p 'c-mode 'c++-mode 'java-mode)
92 Also see https://github.com/leoliu/ggtags/wiki for more examples.
97 Open any file in a project and type ``M-x ggtags-mode``. Use ``M-.``
98 (``ggtags-find-tag-dwim``) to find the tag at point. If the project
99 has not been indexed (i.e. no ``GTAGS`` file exists), ``ggtags`` will
100 ask for the project root directory and index it recursively.
101 Alternatively one can invoke ``ggtags-create-tags`` to index a
102 directory. The mode line will display the directory name next to the
103 buffer name. If point is at a valid definition tag, it is underlined.
105 ``ggtags`` is similar to the standard ``etags`` package. For example
106 these keys ``M-.``, ``M-,``, ``M-*`` and ``C-M-.`` should work as
107 expected in ``ggtags-mode``.
109 The following search commands are available:
113 Find a tag by context.
115 If point is at a definition tag, find references, and vice versa.
116 If point is at a line that matches ``ggtags-include-pattern``, find
117 the include file instead.
119 To force finding a definition tag, call it with a prefix (``C-u``).
121 ggtags-find-tag-mouse
123 Like ``ggtags-find-tag-dwim`` but suitable for binding to mouse
126 ggtags-find-definition
128 Find definition tags. With ``C-u`` ask for the tag name with
131 ggtags-find-reference
133 Find reference tags. With ``C-u`` ask for the tag name with completion.
135 ggtags-find-other-symbol
137 Find tags that have no definitions. With ``C-u`` ask for the tag
138 name with completion.
140 ggtags-find-tag-regexp
142 Find definition tags matching a regexp. By default it lists all
143 matching tags in the project. With ``C-u`` restrict the lists to a
148 Use idutils to find matches.
152 Grep for lines matching a regexp. This is usually the slowest.
156 Find a file from all the files indexed by ``gtags``.
160 Do a query replace in all files found in a search.
162 Handling multiple matches
163 +++++++++++++++++++++++++
165 When a search finds multiple matches, a buffer named
166 ``*ggtags-global*`` is popped up and ``ggtags-navigation-mode`` is
167 turned on to facilitate locating the right match.
168 ``ggtags-navigation-mode`` makes a few commands in the
169 ``*ggtags-global*`` buffer globally accessible:
173 Move to the next match.
177 Move to the previous match.
185 Move to previous file.
189 Move to the first match.
193 Move to the last match.
195 ``C-M-s`` or ``M-s s``
197 Use ``isearch`` to find the match.
201 Found the right match so exit navigation mode. Resumable by ``M-,``
202 (``tags-loop-continue``).
206 Abort and go back to the location where the search was started.
208 Miscellaneous commands
209 ++++++++++++++++++++++
211 Commands are avaiable from the ``Ggtags`` menu in ``ggtags-mode``.
215 Move to the previously (older) visited location. Unlike ``M-*``
216 this doesn't delete the location from the tag ring.
220 Move to the next (newer) visited location.
222 ggtags-view-tag-history
224 Pop to a buffer listing all visited locations from newest to
225 oldest. The buffer is a next error buffer and works with standard
226 commands ``next-error`` and ``previous-error``. In addition ``TAB``
227 and ``S-TAB`` move to next/prev entry, and ``RET`` visits the
228 location. ``M-n`` and ``M-p`` move to and display the next/previous
231 ggtags-view-search-history
233 View or re-run past searches as kept in
234 ``ggtags-global-search-history``.
236 ggtags-kill-file-buffers
238 Kill all file-visiting buffers of current project.
240 ggtags-toggle-project-read-only
242 Toggle opening files in ``read-only`` mode. Handy if the main
243 purpose of source navigation is to read code.
245 ggtags-visit-project-root
247 Open the project root directory in ``dired``.
251 Delete the GTAGS, GRTAGS, GPATH and ID files of current project.
253 ggtags-browse-file-as-hypertext
255 Use ``htags`` to generate HTML of the source tree. This allows
256 browsing the porject in a browser with cross-references.
258 Integration with other packages
259 +++++++++++++++++++++++++++++++
263 ``Eldoc`` support can be enabled by, for example, setting this in
264 the desired major mode with:
268 (setq-local eldoc-documentation-function #'ggtags-eldoc-function)
272 Emacs major modes usually have excellent support for ``imenu`` so
273 this is not enabled by default. To use:
276 (setq-local imenu-create-index-function #'ggtags-build-imenu-index)
281 (setq-local hippie-expand-try-functions-list
282 (cons 'ggtags-try-complete-tag hippie-expand-try-functions-list))
286 ``company`` can use ``ggtags`` as completion source via
287 ``company-capf`` which is enabled by default.
291 If ``helm-mode`` is enabled ``ggtags`` will use it for completion if
292 ``ggtags-completing-read-function`` is nil.
297 [2014-06-22 Sun] 0.8.5
298 ++++++++++++++++++++++
300 #. New command ``ggtags-find-tag-mouse`` for mouse support.
301 #. New command ``ggtags-find-definition``.
302 #. Variable ``ggtags-completing-read-function`` restored.
303 #. ``ggtags-navigation-isearch-forward`` can also be invoked using
305 #. Command ``ggtags-global-rerun-search`` renamed to
306 ``ggtags-view-search-history``.
307 #. The output buffer from ``ggtags-view-search-history`` looks
309 #. Search history items can be re-arranged with ``C-k`` and ``C-y``.
311 [2014-05-06 Tue] 0.8.4
312 ++++++++++++++++++++++
314 #. ``M-.`` (``ggtags-find-tag-dwim``) is smarter on new files.
315 #. Always update tags for current file on save.
316 #. Can continue search ``GTAGSLIBPATH`` if search turns up 0 matches.
317 Customisable via ``ggtags-global-search-libpath-for-reference``.
319 [2014-04-12 Sat] 0.8.3
320 ++++++++++++++++++++++
322 #. Tweak mode-line ligter in ``ggtags-navigation-mode``.
324 [2014-04-05 Sat] 0.8.2
325 ++++++++++++++++++++++
327 #. Default ``ggtags-auto-jump-to-match`` to ``history``.
328 #. Add eldoc support; see ``ggtags-eldoc-function``.
329 #. Improved support for tramp.
331 [2014-03-30 Sun] 0.8.1
332 ++++++++++++++++++++++
334 #. Improve ``ggtags-view-tag-history`` and tag history navigation.
335 #. New customsable variable ``ggtags-global-use-color``.
336 #. Automatically jump to match from location stored in search history.
337 See ``ggtags-auto-jump-to-match``.
338 #. Rename ``ggtags-supress-navigation-keys`` to
339 ``ggtags-enable-navigation-keys`` with a better way to suppress
340 navigation key bindings in some buffers including
341 ``*ggtags-global*`` buffer.
343 [2014-03-24 Mon] 0.8.0
344 ++++++++++++++++++++++
346 #. Record search history and re-run past searches.
347 #. Bookmark or save search to register.
348 #. New command ``ggtags-show-definition``.
349 #. Project name on mode line.
350 #. Automatically use ``.globalrc`` or ``gtags.conf`` file at project
352 #. Better completion based on tag types.
353 #. Use colored output to get column number for jumping to tag.
354 #. Improve detection of stale GTAGS file based on file modification
356 #. New customisable variables ``ggtags-executable-directory``,
357 ``ggtags-global-always-update``, ``ggtags-mode-sticky`` and
358 ``ggtags-supress-navigation-keys``.
364 https://github.com/leoliu/ggtags/issues