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.
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-global-rerun-search
233 Re-run a search from search history 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.
300 #. New command ``ggtags-find-tag-mouse`` for mouse support.
301 #. New command ``ggtags-find-definition``.
302 #. Variable ``ggtags-completing-read-function`` restored.
304 [2014-05-06 Tue] 0.8.4
305 ++++++++++++++++++++++
307 #. ``M-.`` (``ggtags-find-tag-dwim``) is smarter on new files.
308 #. Always update tags for current file on save.
309 #. Can continue search ``GTAGSLIBPATH`` if search turns up 0 matches.
310 Customisable via ``ggtags-global-search-libpath-for-reference``.
312 [2014-04-12 Sat] 0.8.3
313 ++++++++++++++++++++++
315 #. Tweak mode-line ligter in ``ggtags-navigation-mode``.
317 [2014-04-05 Sat] 0.8.2
318 ++++++++++++++++++++++
320 #. Default ``ggtags-auto-jump-to-match`` to ``history``.
321 #. Add eldoc support; see ``ggtags-eldoc-function``.
322 #. Improved support for tramp.
324 [2014-03-30 Sun] 0.8.1
325 ++++++++++++++++++++++
327 #. Improve ``ggtags-view-tag-history`` and tag history navigation.
328 #. New customsable variable ``ggtags-global-use-color``.
329 #. Automatically jump to match from location stored in search history.
330 See ``ggtags-auto-jump-to-match``.
331 #. Rename ``ggtags-supress-navigation-keys`` to
332 ``ggtags-enable-navigation-keys`` with a better way to suppress
333 navigation key bindings in some buffers including
334 ``*ggtags-global*`` buffer.
336 [2014-03-24 Mon] 0.8.0
337 ++++++++++++++++++++++
339 #. Record search history and re-run past searches.
340 #. Bookmark or save search to register.
341 #. New command ``ggtags-show-definition``.
342 #. Project name on mode line.
343 #. Automatically use ``.globalrc`` or ``gtags.conf`` file at project
345 #. Better completion based on tag types.
346 #. Use colored output to get column number for jumping to tag.
347 #. Improve detection of stale GTAGS file based on file modification
349 #. New customisable variables ``ggtags-executable-directory``,
350 ``ggtags-global-always-update``, ``ggtags-mode-sticky`` and
351 ``ggtags-supress-navigation-keys``.
357 https://github.com/leoliu/ggtags/issues