Mercurial > vim-gutentags

comparison doc/autotags.txt @ 4:512eaa56c7db

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
First pass at documentation.
author Ludovic Chabant <ludovic@chabant.com>
date Sun, 20 Jul 2014 14:25:23 -0700
parents a3a37124558b
children 49e3cb99ab27
comparison
equal deleted inserted replaced
3:60adce96ac2d 4:512eaa56c7db
1 1 *autotags.txt* Automatic ctags management for VIM
2 TODO 2
3 ___ ___ ___
4 /\ \ /\ \ /\ \
5 /::\ \ \:\ \ ___ /::\ \
6 /:/\:\ \ \:\ \ /\__\ /:/\:\ \
7 /:/ /::\ \ ___ \:\ \ /:/ / /:/ \:\ \
8 /:/_/:/\:\__\ /\ \ \:\__\ /:/__/ /:/__/ \:\__\
9 \:\/:/ \/__/ \:\ \ /:/ / /::\ \ \:\ \ /:/ /
10 \::/__/ \:\ /:/ / /:/\:\ \ \:\ /:/ /
11 \:\ \ \:\/:/ / \/__\:\ \ \:\/:/ /
12 \:\__\ \::/ / \:\__\ \::/ /
13 \/__/ \/__/ _\/__/ \/__/
14 /\ \ /\__\ /\__\
15 ___ /::\ \ /:/ _/_ /:/ _/_
16 /\__\ /:/\:\ \ /:/ /\ \ /:/ /\ \
17 /:/ / /:/ /::\ \ /:/ /::\ \ /:/ /::\ \
18 /:/__/ /:/_/:/\:\__\ /:/__\/\:\__\ /:/_/:/\:\__\
19 /::\ \ \:\/:/ \/__/ \:\ \ /:/ / \:\/:/ /:/ /
20 /:/\:\ \ \::/__/ \:\ /:/ / \::/ /:/ /
21 \/__\:\ \ \:\ \ \:\/:/ / \/_/:/ /
22 \:\__\ \:\__\ \::/ / /:/ /
23 \/__/ \/__/ \/__/ \/__/
24
25
26 AUTOTAGS REFERENCE MANUAL
27 by Ludovic Chabant
28
29 *autotags*
30
31 1. Introduction |autotags-intro|
32 2. Commands |autotags-commands|
33 3. Status Line |autotags-status-line|
34 4. Global Settings |autotags-settings|
35
36 =============================================================================
37 1. Introduction *autotags-intro*
38
39 Autotags is a plugin that takes care of the much needed management of tags
40 files in VIM. It will (re)generate tag files as you work while staying
41 completely out of your way. It will even do its best to keep those tag files
42 out of your way too. It has no dependencies and just works.
43
44 In order to generate tag files, Autotags will have to figure out what's in
45 your project. To do this, it will locate well-known project root markers like
46 SCM folders (.git, .hg, etc.), any custom tags you define (with
47 |autotags_project_root|), and even things you may have defined already with
48 other plugins, like CtrlP.
49
50 If the current file you're editing is found to be in such a project, Autotags
51 will make sure the tag file for that project is up to date. Then, as you work
52 in files in that project, it will partially re-generate the tag file. Every
53 time you save, it will silently, in the background, update the tags for that
54 file.
55
56 Usually, ctags can only append tags to an existing tag file, so Autotags
57 removes the tags for the current file first, to make sure the tag file is
58 always consistent with the source code.
59
60 Also, Autotags is clever enough to not stumble upon itself by triggering
61 multiple ctags processes if you save files to fast, or your project is really
62 big.
63
64 There are some similar VIM plugins out there ("vim-tags", "vim-autotag",
65 "vim-automatic-ctags", etc.). They all fail on one or more of the requirements
66 I set for myself with Autotags:
67
68 * No other dependency than running VIM: no Python, Ruby, or whatever.
69 * Cross-platform: should work on at least Mac and Windows.
70 * Incremental tags generation: don't re-generate the whole project all the
71 time. This may be fine for small projects, but it doesn't scale.
72 * External process management: if the ctags process is taking a long time,
73 don't run another one because I saved the file again.
74 * Keep the tag file consistent: don't just append the current file's tags to
75 the tag file, otherwise you will still "see" tags for deleted or renamed
76 classes and functions.
77 * Automatically create the tag file: you open something from a freshly forked
78 project, it should start indexing it automatically, just in Sublime Text or
79 Visual Studio or any other IDE.
80
81
82 =============================================================================
83 2. Commands *autotags-commands*
84
85 *autotags-global-commands*
86 The following commands are always available, whatever buffer you currently
87 have open:
88
89 *:AutotagsGenerate*
90 :AutotagsGenerate {tagsfile}
91 Generates a tag file named {tagsfile}. Tags will be
92 generated for all the files in the same directory as
93 {tagsfile} and below (i.e. recursive from {tagsfile}'s
94 own directory).
95
96
97 *autotags-project-commands*
98 The following commands are only available in buffers that have been found to
99 belong to a project that should be managed by Autotags. See
100 |autotags_project_root| for how Autotags figures out the project a file
101 belongs to. When not project is found (i.e. the file is not under any of the
102 known project markers), Autotags is disabled for that buffer, and the
103 following commands and remarks don't apply.
104
105 The tag file that Autotags creates and manages will be named after
106 |autotags_tagfile|, relative to the project's root directory. When Autotags
107 finds a valid project root, it will prepend the tag file's path to 'tags',
108 unless |autotags_auto_set_tags| is set to 0. This is to make sure Vim will use
109 that file first.
110
111 If a file managed by Autotags is opened and no tag file already exists,
112 Autotags will start generating it right away in the background, unless
113 |autotags_generate_on_missing| is set to 0. If you have a large project, you
114 may want to know when Autotags is generating tags: see
115 |autotags-status-line| to display an indicator in your status line.
116
117 When a file managed by Autotags is saved, the tag file will be incrementally
118 updated, i.e. references to the recently saved file are removed, and that file
119 is re-parsed for tags, with the result being merged into the tag file. This
120 makes the tag file 100% consistent with the latest changes. This doesn't
121 happen however if |autotags_generate_on_write| is set to 0, in which case you
122 have to run |AutotagsUpdate| manually.
123
124
125 *:AutotagsUpdate*
126 :AutotagsUpdate
127 Forces an update of the current tag file with the
128 current buffer. If tags are already being generated,
129 you will be notified and the command will abort.
130
131 :AutotagsUpdate!
132 Like |AutotagsUpdate|, but updates the current tags
133 file with the whole project instead of just the
134 current buffer.
135
136
137 Some debugging/troubleshooting commands are also available.
138
139 *:AutotagsToggleEnabled*
140 :AutotagsToggleEnabled
141 Disables and re-enables Autotags.
142 When Autotags is disabled, it won't update your tag
143 file when you save a buffer. It will however still
144 look for project markers as you open new buffers so
145 that they can start working again when you re-enable
146 Autotags.
147
148 *AutotagsToggleTrace*
149 :AutotagsToggleTrace
150 If you want to keep an eye on what Autotags is doing,
151 you can enable tracing. This will show messages every
152 time Autotags does something. It can get annoying
153 quickly, since it will require you to press a key to
154 dismiss those messages, but it can be useful to
155 troubleshoot a problem.
156 In addition to messages in Vim, it will also make
157 Autotags redirect the output of the tag generation
158 script to a `.log` file in the project root.
159
160 *:AutotagsUnlock*
161 :AutotagsUnlock
162 Autotags uses a `.lock` file to know when tag
163 generation is running. If something goes wrong with
164 that process, that lock file could be left behind. You
165 could just remove it manually from the root of your
166 project, but you can also run |:AutotagsUnlock| so
167 that Vim does it for you.
168 If you find that you need to use this more than a
169 couple times ever, there's probably a bug with
170 Autotags, or something otherwise wrong or unexpected
171 with your system. Please file a bug.
172
173 =============================================================================
174 3. Status Line *autotags-status-line*
175
176 Tag file generation can take a while if you're working on a project big
177 enough. In that case, you may want to know when `ctags` is running, so you
178 have a heads up if some of the tags aren't recognized yet.
179
180 *autotags#statusline()*
181 You can display and indicator of tag generation progress in your |status-line|
182 with the following function: >
183 :set statusline+=%{autotags#statusline()}
184
185 This won't print anything unless Autotags figures that `ctags` is running in
186 the background. This is done by checking a `.lock` file next to the tag file,
187 but there's also some optimization before that to not slow down Vim. Note that
188 the `.lock` file can sometimes be left around incorrectly by the background
189 process, and you may need to clean it up. See |:AutotagsUnlock|.
190
191 When Autotags thinks `ctags` is still running, it will print the string
192 "TAGS" by default. You can customize it: >
193 :set statusline+=%{autotags#statusline('[Generating...]')}
194
195 This will print the string "[Generating...]" when tags are being generated.
196
197
198 =============================================================================
199 4. Global Settings *autotags-settings*
200
201 The following settings can be defined in your |vimrc| to change the default
202 behaviour of Autotags.
203
204 *autotags_enabled*
205 g:autotags_enabled
206 Defines whether Autotags should be enabled. When
207 disabled, Autotags will still scan for project root
208 markers when opening buffers. This is so that when you
209 re-enable Autotags, you won't have some buffers
210 mysteriously working while others (those open last)
211 don't.
212 Defaults to 1.
213
214 *autotags_executable*
215 g:autotags_executable
216 Specifies the ctags executable to launch.
217 Defaults to `ctags`.
218
219 *autotags_tagfile*
220 g:autotags_tagfile
221 Specifies the name of the tag file to create. This
222 will be appended to the project's root. See
223 |autotags_project_root| for how Autotags locates the
224 project.
225 Defaults to `tags`.
226
227 *autotags_project_root*
228 g:autotags_project_root
229 When a buffer is loaded, Autotags will figure out if
230 it's part of a project that should have tags managed
231 automatically. To do this, it looks for "root markers"
232 in the current file's directory and its parent
233 directories. If it finds any of those markers,
234 Autotags will be enabled for the project, and a tags
235 file named after |autotags_tagfile| will be created at
236 the project root.
237 Defaults to `[]` (an empty |List|).
238 A list of default markers will always be appended to
239 the user-defined ones: ['.git', '.hg', '.bzr',
240 '_darcs'].
241
242 *autotags_exclude*
243 g:autotags_exclude
244 A list of file patterns to pass to the
245 |autotags_executable| so that they will be excluded
246 from parsing for the tags generation.
247 Defaults to `[]` (an empty |List|).
248 Patterns defined in 'wildignore' will also be given as
249 exclude patterns to the `ctags` executable.
250
251 *autotags_auto_set_tags*
252 g:autotags_auto_set_tags
253 If set to 1, Autotags will automatically prepend
254 'tags' with the exact path to the tag file for the
255 current project. See |autotags_project_root| for how
256 Autotags locates the project.
257 When set to 0, Autotags doesn't change 'tags', and
258 this means that whatever tag file it generates may
259 not be picked up by Vim. See |tagfiles()| to know what
260 tag files Vim knows about.
261 Defaults to 1.
262
263 *autotags_generate_on_missing*
264 g:autotags_generate_on_missing
265 If set to 1, Autotags will start generating an initial
266 tag file if a file is open in a project where no tags
267 file is found. See |autotags_project_root| for how
268 Autotags locates the project.
269 When set to 0, Autotags will only generate the first
270 time the file is saved (if
271 |autotags_generate_on_write| is set to 1), or when
272 |AutotagsUpdate| or |AutotagsGenerate| is run.
273 Defaults to 1.
274
275 *autotags_generate_on_write*
276 g:autotags_generate_on_write
277 If set to 1, Autotags will update the current
278 project's tag file when a file inside that project is
279 saved. See |autotags_project_root| for how Autotags
280 locates the project.
281 When set to 0, Autotags won't do anything on save.
282 This means that the project's tag file won't reflect
283 the latest changes, and you will have to run
284 |AutotagsUpdate| manually.
285 Defaults to 1.
286
287 *autotags_background_update*
288 g:autotags_background_update
289 Specifies whether the process that updates the tags
290 file should be run in the background or in the
291 foreground. If run in the foreground, Vim will block
292 until the process is complete.
293 Defaults to 1.
294
295
3 296
4 vim:tw=78:et:ft=help:norl: 297 vim:tw=78:et:ft=help:norl: