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 <https://melpa.org/#/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,
  12 24.4 and trunk. Patches, feature requests and bug reports are welcome.
  13 Thanks.
  14
  15 Features
  16 ~~~~~~~~
  17
  18 #. Build on ``compile.el`` for asynchronicity and its large
  19    feature-set.
  20 #. Automatically update Global's tag files when needed with tuning for
  21    large source trees.
  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.
  28 #. Query replace.
  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``,
  35    ``cscope`` etc.
  36 #. Support projects on remote hosts (e.g. via ``tramp``).
  37 #. Support eldoc.
  38 #. Search ``GTAGSLIBPATH`` for references and symbols.
  39
  40 Screenshot
  41 ~~~~~~~~~~
  42
  43 .. figure:: http://i.imgur.com/wx8ZPGe.png
  44    :width: 500px
  45    :target: http://i.imgur.com/wx8ZPGe.png
  46    :alt: ggtags.png
  47
  48 Why GNU Global
  49 ~~~~~~~~~~~~~~
  50
  51 The opengrok project composed a feature comparison `table
  52 <https://github.com/OpenGrok/OpenGrok/wiki/Comparison-with-Similar-Tools>`_
  53 between a few tools.
  54
  55 Install Global and plugins
  56 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  57
  58 1. Compile and install Global with ``exuberant-ctags``
  59    ::
  60
  61      ./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags
  62      make && make install
  63
  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.
  69
  70 2. Install ``pygments`` plugin
  71
  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.
  77
  78    The following instructions are for older ``global``.
  79    ::
  80
  81      pip install pygments
  82      git clone https://github.com/yoshizow/global-pygments-plugin.git
  83      cd global-pygments-plugin/
  84      sh reconf.sh
  85      ./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags
  86      make && make install
  87      cp sample.globalrc $HOME/.globalrc
  88
  89    Make sure the value of ``<PREFIX>`` agree with step 1.
  90
  91 Config
  92 ~~~~~~
  93
  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::
  97
  98     (add-hook 'c-mode-common-hook
  99               (lambda ()
 100                 (when (derived-mode-p 'c-mode 'c++-mode 'java-mode)
 101                   (ggtags-mode 1))))
 102
 103 Also see https://github.com/leoliu/ggtags/wiki for more examples.
 104
 105 Usage
 106 ~~~~~
 107
 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.
 115
 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``.
 119
 120 The following search commands are available:
 121
 122 ggtags-find-tag-dwim
 123
 124    Find a tag by context.
 125
 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.
 129
 130    To force finding a definition tag, call it with a prefix (``C-u``).
 131
 132 ggtags-find-tag-mouse
 133
 134    Like ``ggtags-find-tag-dwim`` but suitable for binding to mouse
 135    events.
 136
 137 ggtags-find-definition
 138
 139    Find definition tags. With ``C-u`` ask for the tag name with
 140    completion.
 141
 142 ggtags-find-reference
 143
 144    Find reference tags. With ``C-u`` ask for the tag name with completion.
 145
 146 ggtags-find-other-symbol
 147
 148    Find tags that have no definitions. With ``C-u`` ask for the tag
 149    name with completion.
 150
 151 ggtags-find-tag-regexp
 152
 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
 155    directory of choice.
 156
 157 ggtags-idutils-query
 158
 159    Use idutils to find matches.
 160
 161 ggtags-grep
 162
 163    Grep for lines matching a regexp. This is usually the slowest.
 164
 165 ggtags-find-file
 166
 167    Find a file from all the files indexed by ``gtags``.
 168
 169 ggtags-query-replace
 170
 171    Do a query replace in all files found in a search.
 172
 173 Handling multiple matches
 174 +++++++++++++++++++++++++
 175
 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:
 181
 182 ``M-n``
 183
 184    Move to the next match.
 185
 186 ``M-p``
 187
 188    Move to the previous match.
 189
 190 ``M-}``
 191
 192    Move to next file.
 193
 194 ``M-{``
 195
 196    Move to previous file.
 197
 198 ``M-=``
 199
 200    Move to the file where navigation session starts.
 201
 202 ``M-<``
 203
 204    Move to the first match.
 205
 206 ``M->``
 207
 208    Move to the last match.
 209
 210 ``C-M-s`` or ``M-s s``
 211
 212    Use ``isearch`` to find the match.
 213
 214 ``RET``
 215
 216    Found the right match so exit navigation mode. Resumable by ``M-,``
 217    (``tags-loop-continue``).
 218
 219 ``M-*``
 220
 221    Abort and go back to the location where the search was started.
 222
 223 Miscellaneous commands
 224 ++++++++++++++++++++++
 225
 226 Commands are available from the ``Ggtags`` menu in ``ggtags-mode``.
 227
 228 ggtags-prev-mark
 229
 230    Move to the previously (older) visited location. Unlike ``M-*``
 231    this doesn't delete the location from the tag ring.
 232
 233 ggtags-next-mark
 234
 235    Move to the next (newer) visited location.
 236
 237 ggtags-view-tag-history
 238
 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
 244    entry.
 245
 246 ggtags-view-search-history
 247
 248    View or re-run past searches as kept in
 249    ``ggtags-global-search-history``.
 250
 251 ggtags-kill-file-buffers
 252
 253    Kill all file-visiting buffers of current project.
 254
 255 ggtags-toggle-project-read-only
 256
 257    Toggle opening files in ``read-only`` mode. Handy if the main
 258    purpose of source navigation is to read code.
 259
 260 ggtags-visit-project-root
 261
 262    Open the project root directory in ``dired``.
 263
 264 ggtags-delete-tags
 265
 266    Delete the GTAGS, GRTAGS, GPATH and ID files of current project.
 267
 268 ggtags-explain-tags
 269
 270   Explain how each file is indexed in current project.
 271
 272 ggtags-browse-file-as-hypertext
 273
 274    Use ``htags`` to generate HTML of the source tree. This allows
 275    browsing the project in a browser with cross-references.
 276
 277 Integration with other packages
 278 +++++++++++++++++++++++++++++++
 279
 280 * eldoc
 281
 282   ``Eldoc`` support is set up by default on emacs 24.4+. For older
 283   versions set, for example, in the desired major mode:
 284
 285   ::
 286
 287      (setq-local eldoc-documentation-function #'ggtags-eldoc-function)
 288
 289 * imenu
 290
 291   Emacs major modes usually have excellent support for ``imenu`` so
 292   this is not enabled by default. To use:
 293   ::
 294
 295     (setq-local imenu-create-index-function #'ggtags-build-imenu-index)
 296
 297 * hippie-exp
 298   ::
 299
 300      (setq-local hippie-expand-try-functions-list
 301                  (cons 'ggtags-try-complete-tag hippie-expand-try-functions-list))
 302
 303 * company
 304
 305   ``company`` can use ``ggtags`` as completion source via
 306   ``company-capf`` which is enabled by default.
 307
 308 * helm
 309
 310   If ``helm-mode`` is enabled ``ggtags`` will use it for completion if
 311   ``ggtags-completing-read-function`` is nil.
 312
 313 NEWS
 314 ~~~~
 315
 316 [2015-12-15 Tue] 0.8.11
 317 +++++++++++++++++++++++
 318
 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.
 323
 324 [2015-06-12 Fri] 0.8.10
 325 +++++++++++++++++++++++
 326
 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.
 332
 333 [2015-01-16 Fri] 0.8.9
 334 ++++++++++++++++++++++
 335
 336 #. ``ggtags-visit-project-root`` can visit past projects.
 337 #. ``eldoc`` support enabled for emacs 24.4+.
 338
 339 [2014-12-03 Wed] 0.8.8
 340 ++++++++++++++++++++++
 341
 342 #. Command ``ggtags-update-tags`` now runs in the background for large
 343    projects (per ``ggtags-oversize-limit``) without blocking emacs.
 344
 345 [2014-11-10 Mon] 0.8.7
 346 ++++++++++++++++++++++
 347
 348 #. New navigation command ``ggtags-navigation-start-file``.
 349 #. New variable ``ggtags-use-sqlite3`` to enable sqlite3 storage.
 350
 351 [2014-09-12 Fri] 0.8.6
 352 ++++++++++++++++++++++
 353
 354 #. ``ggtags-show-definition`` shows definition with font locking.
 355
 356 [2014-06-22 Sun] 0.8.5
 357 ++++++++++++++++++++++
 358
 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
 363    ``M-s s``.
 364 #. Command ``ggtags-global-rerun-search`` renamed to
 365    ``ggtags-view-search-history``.
 366 #. The output buffer from ``ggtags-view-search-history`` looks
 367    cleaner.
 368 #. Search history items can be re-arranged with ``C-k`` and ``C-y``.
 369
 370 [2014-05-06 Tue] 0.8.4
 371 ++++++++++++++++++++++
 372
 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``.
 377
 378 [2014-04-12 Sat] 0.8.3
 379 ++++++++++++++++++++++
 380
 381 #. Tweak mode-line ligter in ``ggtags-navigation-mode``.
 382
 383 [2014-04-05 Sat] 0.8.2
 384 ++++++++++++++++++++++
 385
 386 #. Default ``ggtags-auto-jump-to-match`` to ``history``.
 387 #. Add eldoc support; see ``ggtags-eldoc-function``.
 388 #. Improved support for tramp.
 389
 390 [2014-03-30 Sun] 0.8.1
 391 ++++++++++++++++++++++
 392
 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.
 401
 402 [2014-03-24 Mon] 0.8.0
 403 ++++++++++++++++++++++
 404
 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
 410    root.
 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
 414    time.
 415 #. New customisable variables ``ggtags-executable-directory``,
 416    ``ggtags-global-always-update``, ``ggtags-mode-sticky`` and
 417    ``ggtags-supress-navigation-keys``.
 418 #. Other bug fixes.
 419
 420 Bugs
 421 ~~~~
 422
 423 https://github.com/leoliu/ggtags/issues