code.delx.au - gnu-emacs-elpa/blob - packages/ggtags/README.rst

   1 =========================================================
   2  Emacs frontend to GNU Global source code tagging system
   3 =========================================================
   4
   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>`_.
   8
   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.
  13
  14 Features
  15 ~~~~~~~~
  16
  17 #. Build on ``compile.el`` for asynchronicity and its large
  18    feature-set.
  19 #. Automatically update Global's tag files when needed with tuning for
  20    large source trees.
  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.
  27 #. Query replace.
  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``,
  34    ``cscope`` etc.
  35 #. Support projects on remote hosts (e.g. via ``tramp``)
  36 #. Support eldoc
  37
  38 Screenshot
  39 ~~~~~~~~~~
  40
  41 .. figure:: http://i.imgur.com/LX7PVc3.png
  42    :width: 500px
  43    :target: http://i.imgur.com/LX7PVc3.png
  44    :alt: ggtags.png
  45
  46 Why GNU Global
  47 ~~~~~~~~~~~~~~
  48
  49 The opengrok project composed a feature comparison `table
  50 <https://github.com/OpenGrok/OpenGrok/wiki/Comparison-with-Similar-Tools>`_
  51 between a few tools.
  52
  53 Install Global and plugins
  54 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  55
  56 1. Compile and install Global with ``exuberant-ctags``
  57 ::
  58
  59    ./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags
  60    make && make install
  61
  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.
  66
  67 2. Install ``pygments`` plugin
  68 ::
  69
  70    pip install pygments
  71    git clone https://github.com/yoshizow/global-pygments-plugin.git
  72    sh reconf.sh
  73    ./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags
  74    make && make install
  75    cp sample.globalrc $HOME/.globalrc
  76
  77 Make sure the value of ``<PREFIX>`` agree with step 1.
  78
  79 Config
  80 ~~~~~~
  81
  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::
  85
  86     (add-hook 'c-mode-common-hook
  87               (lambda ()
  88                 (when (derived-mode-p 'c-mode 'c++-mode 'java-mode)
  89                   (ggtags-mode 1))))
  90
  91 Also see https://github.com/leoliu/ggtags/wiki for more examples.
  92
  93 Usage
  94 ~~~~~
  95
  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.
 103
 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``.
 107
 108 The following search commands are available:
 109
 110 ggtags-find-tag-dwim
 111
 112    Find a tag by context.
 113
 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.
 117
 118    To force finding a definition tag, call it with a prefix (``C-u``).
 119
 120 ggtags-find-reference
 121
 122    Find references to a tag. With ``C-u`` ask for the tag name with
 123    completion.
 124
 125 ggtags-find-other-symbol
 126
 127    Find a tag that has no definition. With ``C-u`` ask for the tag
 128    name with completion.
 129
 130 ggtags-find-tag-regexp
 131
 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
 134    directory of choice.
 135
 136 ggtags-idutils-query
 137
 138    Use idutils to find matches.
 139
 140 ggtags-grep
 141
 142    Grep for lines matching a regexp. This is usually the slowest.
 143
 144 ggtags-find-file
 145
 146    Find a file from all the files indexed by ``gtags``.
 147
 148 ggtags-query-replace
 149
 150    Do a query replace in all files found in a search.
 151
 152 Handling multiple matches
 153 +++++++++++++++++++++++++
 154
 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:
 160
 161 ``M-n``
 162
 163    Move to the next match.
 164
 165 ``M-p``
 166
 167    Move to the previous match.
 168
 169 ``M-}``
 170
 171    Move to next file.
 172
 173 ``M-{``
 174
 175    Move to previous file.
 176
 177 ``M-<``
 178
 179    Move to the first match.
 180
 181 ``M->``
 182
 183    Move to the last match.
 184
 185 ``C-M-s``
 186
 187    Use ``isearch`` to find the match.
 188
 189 ``RET``
 190
 191    Found the right match so exit navigation mode. Resumable by ``M-,``
 192    (``tags-loop-continue``).
 193
 194 ``M-*``
 195
 196    Abort and go back to the location where the search was started.
 197
 198 Miscellaneous commands
 199 ++++++++++++++++++++++
 200
 201 Commands are avaiable from the ``Ggtags`` menu in ``ggtags-mode``.
 202
 203 ggtags-prev-mark
 204
 205    Move to the previously (older) visited location. Unlike ``M-*``
 206    this doesn't delete the location from the tag ring.
 207
 208 ggtags-next-mark
 209
 210    Move to the next (newer) visited location.
 211
 212 ggtags-view-tag-history
 213
 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
 219    entry.
 220
 221 ggtags-global-rerun-search
 222
 223    Re-run a search from search history as kept in
 224    ``ggtags-global-search-history``.
 225
 226 ggtags-kill-file-buffers
 227
 228    Kill all file-visiting buffers of current project.
 229
 230 ggtags-toggle-project-read-only
 231
 232    Toggle opening files in ``read-only`` mode. Handy if the main
 233    purpose of source navigation is to read code.
 234
 235 ggtags-visit-project-root
 236
 237    Open the project root directory in ``dired``.
 238
 239 ggtags-delete-tags
 240
 241    Delete the GTAGS, GRTAGS, GPATH and ID files of current project.
 242
 243 ggtags-browse-file-as-hypertext
 244
 245    Use ``htags`` to generate HTML of the source tree. This allows
 246    browsing the porject in a browser with cross-references.
 247
 248 Integration with other packages
 249 +++++++++++++++++++++++++++++++
 250
 251 * eldoc
 252
 253   ``Eldoc`` support can be enabled by, for example, setting this in
 254   the desired major mode with:
 255
 256   ::
 257
 258      (setq-local eldoc-documentation-function #'ggtags-eldoc-function)
 259
 260 * imenu
 261
 262   Emacs major modes usually have excellent support for ``imenu`` so
 263   this is not enabled by default. To use:
 264   ::
 265
 266     (setq-local imenu-create-index-function #'ggtags-build-imenu-index)
 267
 268 * hippie-exp
 269   ::
 270
 271      (setq-local hippie-expand-try-functions-list
 272                  (cons 'ggtags-try-complete-tag hippie-expand-try-functions-list))
 273
 274 * company
 275
 276   ``company`` can use ``ggtags`` as completion source via
 277   ``company-capf`` (enabled by default in emacs 24.4).
 278
 279 * helm
 280
 281   If ``helm-mode`` is enabled ``ggtags`` will use it for completion.
 282
 283 NEWS
 284 ~~~~
 285
 286 [2014-04-12 Sat] 0.8.3
 287 ++++++++++++++++++++++
 288
 289 #. Tweak mode-line ligter in ``ggtags-navigation-mode``.
 290
 291 [2014-04-05 Sat] 0.8.2
 292 ++++++++++++++++++++++
 293
 294 #. Default ``ggtags-auto-jump-to-match`` to ``history``.
 295 #. Add eldoc support; see ``ggtags-eldoc-function``.
 296 #. Improved support for tramp.
 297
 298 [2014-03-30 Sun] 0.8.1
 299 ++++++++++++++++++++++
 300
 301 #. Improve ``ggtags-view-tag-history`` and tag history navigation.
 302 #. New customsable variable ``ggtags-global-use-color``.
 303 #. Automatically jump to match from location stored in search history.
 304    See ``ggtags-auto-jump-to-match``.
 305 #. Rename ``ggtags-supress-navigation-keys`` to
 306    ``ggtags-enable-navigation-keys`` with a better way to suppress
 307    navigation key bindings in some buffers including
 308    ``*ggtags-global*`` buffer.
 309
 310 [2014-03-24 Mon] 0.8.0
 311 ++++++++++++++++++++++
 312
 313 #. Record search history and re-run past searches.
 314 #. Bookmark or save search to register.
 315 #. New command ``ggtags-show-definition``.
 316 #. Project name on mode line.
 317 #. Automatically use ``.globalrc`` or ``gtags.conf`` file at project
 318    root.
 319 #. Better completion based on tag types.
 320 #. Use colored output to get column number for jumping to tag.
 321 #. Improve detection of stale GTAGS file based on file modification
 322    time.
 323 #. New customisable variables ``ggtags-executable-directory``,
 324    ``ggtags-global-always-update``, ``ggtags-mode-sticky`` and
 325    ``ggtags-supress-navigation-keys``.
 326 #. Other bug fixes.
 327
 328 Bugs
 329 ~~~~
 330
 331 https://github.com/leoliu/ggtags/issues