code.delx.au - gnu-emacs-elpa/blob - 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
  37 Screenshot
  38 ~~~~~~~~~~
  39
  40 .. figure:: http://i.imgur.com/LX7PVc3.png
  41    :width: 500px
  42    :target: http://i.imgur.com/LX7PVc3.png
  43    :alt: ggtags.png
  44
  45 Why GNU Global
  46 ~~~~~~~~~~~~~~
  47
  48 The opengrok project composed a feature comparison `table
  49 <https://github.com/OpenGrok/OpenGrok/wiki/Comparison-with-Similar-Tools>`_
  50 between a few tools.
  51
  52 Install Global and plugins
  53 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  54
  55 1. Compile and install Global with ``exuberant-ctags``
  56 ::
  57
  58    ./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags
  59    make && make install
  60
  61 The executable ``ctags`` is unfortunately named because ``emacs`` also
  62 includes a command of the same name. So make sure it is from
  63 http://ctags.sourceforge.net. See ``plugin-factory/README`` in GNU
  64 Global source for further information.
  65
  66 2. Install ``pygments`` plugin
  67 ::
  68
  69    pip install pygments
  70    git clone https://github.com/yoshizow/global-pygments-plugin.git
  71    sh reconf.sh
  72    ./configure --prefix=<PREFIX> --with-exuberant-ctags=/usr/local/bin/ctags
  73    make && make install
  74    cp sample.globalrc $HOME/.globalrc
  75
  76 Make sure the value of ``<PREFIX>`` agree with step 1.
  77
  78 Config
  79 ~~~~~~
  80
  81 Global with ``exuberant-ctags`` and ``pygments`` plugins can support
  82 dozens of programming languages. For example, to enable
  83 ``ggtags-mode`` for C/C++/Java modes::
  84
  85     (add-hook 'c-mode-common-hook
  86               (lambda ()
  87                 (when (derived-mode-p 'c-mode 'c++-mode 'java-mode)
  88                   (ggtags-mode 1))))
  89
  90 Also see https://github.com/leoliu/ggtags/wiki for more examples.
  91
  92 Usage
  93 ~~~~~
  94
  95 Open any file in a project and type ``M-x ggtags-mode``. Use ``M-.``
  96 (``ggtags-find-tag-dwim``) to find the tag at point. If the project
  97 has not been indexed (i.e. no ``GTAGS`` file exists), ``ggtags`` will
  98 ask for the project root directory and index it recursively.
  99 Alternatively one can invoke ``ggtags-create-tags`` to index a
 100 directory. The mode line will display the directory name next to the
 101 buffer name. If point is at a valid definition tag, it is underlined.
 102
 103 ``ggtags`` is similar to the standard ``etags`` package. For example
 104 these keys ``M-.``, ``M-,``, ``M-*`` and ``C-M-.`` should work as
 105 expected in ``ggtags-mode``.
 106
 107 The following search commands are available:
 108
 109 ggtags-find-tag-dwim
 110
 111    Find a tag by context.
 112
 113    If point is at a definition tag, find references, and vice versa.
 114    If point is at a line that matches ``ggtags-include-pattern``, find
 115    the include file instead.
 116
 117    To force finding a definition tag, call it with a prefix (``C-u``).
 118
 119 ggtags-find-reference
 120
 121    Find references to a tag. With ``C-u`` ask for the tag name with
 122    completion.
 123
 124 ggtags-find-other-symbol
 125
 126    Find a tag that has no definition. With ``C-u`` ask for the tag
 127    name with completion.
 128
 129 ggtags-find-tag-regexp
 130
 131    Find definition tags matching a regexp. By default it lists all
 132    matching tags in the project. With ``C-u`` restrict the lists to a
 133    directory of choice.
 134
 135 ggtags-idutils-query
 136
 137    Use idutils to find matches.
 138
 139 ggtags-grep
 140
 141    Grep for lines matching a regexp. This is usually the slowest.
 142
 143 ggtags-find-file
 144
 145    Find a file from all the files indexed by ``gtags``.
 146
 147 ggtags-query-replace
 148
 149    Do a query replace in all files found in a search.
 150
 151 Handling multiple matches
 152 +++++++++++++++++++++++++
 153
 154 When a search finds multiple matches, a buffer named
 155 ``*ggtags-global*`` is popped up and ``ggtags-navigation-mode`` is
 156 turned on to facilitate locating the right match.
 157 ``ggtags-navigation-mode`` makes a few commands in the
 158 ``*ggtags-global*`` buffer globally accessible:
 159
 160 ``M-n``
 161
 162    Move to the next match.
 163
 164 ``M-p``
 165
 166    Move to the previous match.
 167
 168 ``M-}``
 169
 170    Move to next file.
 171
 172 ``M-{``
 173
 174    Move to previous file.
 175
 176 ``M-<``
 177
 178    Move to the first match.
 179
 180 ``M->``
 181
 182    Move to the last match.
 183
 184 ``C-M-s``
 185
 186    Use ``isearch`` to find the match.
 187
 188 ``RET``
 189
 190    Found the right match so exit the navigation mode. Resumable by
 191    ``M-,`` (``tags-loop-continue``).
 192
 193 ``M-*``
 194
 195    Abort and go back to the location where the search was started.
 196
 197 Miscellaneous commands
 198 ++++++++++++++++++++++
 199
 200 Commands are made avaiable via the ``Ggtags`` menu in ``ggtags-mode``.
 201
 202 ggtags-prev-mark
 203
 204    Move to the previously (older) visited location. Unlike ``M-*``
 205    this doesn't delete the location from the tag ring.
 206
 207 ggtags-next-mark
 208
 209    Move to the next (newer) visited location.
 210
 211 ggtags-view-tag-history
 212
 213    Pop to a buffer listing all visited locations from newest to
 214    oldest. Use ``TAB`` and ``S-TAB`` to move to next/prev entry and
 215    ``RET`` to visit it.
 216
 217 ggtags-global-rerun-search
 218
 219    Re-run a search from search history as kept in
 220    ``ggtags-global-search-history``.
 221
 222 ggtags-kill-file-buffers
 223
 224    Kill all file-visiting buffers of current project.
 225
 226 ggtags-toggle-project-read-only
 227
 228    Toggle opening files in ``read-only`` mode. Handy if the main
 229    purpose of source navigation is to read code.
 230
 231 ggtags-visit-project-root
 232
 233    Open the project root directory in ``dired``.
 234
 235 ggtags-delete-tag-files
 236
 237    Delete the GTAGS, GRTAGS, GPATH and ID files of current project.
 238
 239 ggtags-browse-file-as-hypertext
 240
 241    Use ``htags`` to generate HTML of the source tree. This allows
 242    browsing the porject in a browser with cross-references.
 243
 244 Bugs
 245 ~~~~
 246
 247 https://github.com/leoliu/ggtags/issues