-
Notifications
You must be signed in to change notification settings - Fork 175
/
gutentags.txt
754 lines (614 loc) · 37.3 KB
/
gutentags.txt
1
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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
*gutentags.txt* Automatic ctags management for VIM
___ ___ ___ ___ ___
/\__\ /\ \ /\__\ /\__\ /\ \
/:/ _/_ \:\ \ /:/ / /:/ _/_ \:\ \
/:/ /\ \ \:\ \ /:/__/ /:/ /\__\ \:\ \
/:/ /::\ \ ___ \:\ \ /::\ \ /:/ /:/ _/_ _____\:\ \
/:/__\/\:\__\ /\ \ \:\__\ /:/\:\ \ /:/_/:/ /\__\ /::::::::\__\
\:\ \ /:/ / \:\ \ /:/ / \/__\:\ \ \:\/:/ /:/ / \:\~~\~~\/__/
\:\ /:/ / \:\ /:/ / \:\__\ \::/_/:/ / \:\ \
\:\/:/ / \:\/:/ / \/__/ \:\/:/ / \:\ \
\::/ / \::/ / \::/ / \:\__\
\/__/ \/__/ \/__/ \/__/
___ ___ ___ ___
/\__\ /\ \ /\__\ /\__\
/:/ / /::\ \ /:/ _/_ /:/ _/_
/:/__/ /:/\:\ \ /:/ /\ \ /:/ /\ \
/::\ \ /:/ /::\ \ /:/ /::\ \ /:/ /::\ \
/:/\:\ \ /:/_/:/\:\__\ /:/__\/\:\__\ /:/_/:/\:\__\
\/__\:\ \ \:\/:/ \/__/ \:\ \ /:/ / \:\/:/ /:/ /
\:\__\ \::/__/ \:\ /:/ / \::/ /:/ /
\/__/ \:\ \ \:\/:/ / \/_/:/ /
\:\__\ \::/ / /:/ /
\/__/ \/__/ \/__/
GUTENTAGS REFERENCE MANUAL
by Ludovic Chabant
*gutentags*
1. Introduction |gutentags-intro|
2. Commands |gutentags-commands|
3. Status Line |gutentags-status-line|
4. Global Settings |gutentags-settings|
5. Project Settings |gutentags-project-settings|
=============================================================================
1. Introduction *gutentags-intro*
Gutentags is a plugin that takes care of the much needed management of tags
files in Vim. It will (re)generate tag files as you work while staying
completely out of your way. It will even do its best to keep those tag files
out of your way too. It has no dependencies and just works.
In order to generate tag files, Gutentags will have to figure out what's in
your project. To do this, it will locate well-known project root markers like
SCM folders (.git, .hg, etc.), any custom tags you define (with
|gutentags_project_root|), and even things you may have defined already with
other plugins, like CtrlP.
If the current file you're editing is found to be in such a project, Gutentags
will make sure the tag file for that project is up to date. Then, as you work
in files in that project, it will partially re-generate the tag file. Every
time you save, it will silently, in the background, update the tags for that
file.
Usually, `ctags` can only append tags to an existing tag file, so Gutentags
removes the tags for the current file first, to make sure the tag file is
always consistent with the source code.
Also, Gutentags is clever enough to not stumble upon itself by triggering
multiple ctags processes if you save files too fast, or if your project is
really big.
1.1 Requirements
*gutentags-ctags-requirements*
If you're using the `ctags` modules (which is the default and only working one
at this point, really), you will need a `tags` generator that supports the
following arguments:
* `-f` (to specify the output file)
* `--append` (to append to an existing file while keeping it sorted)
* `--exclude` (to exclude file patterns)
* `--options` (to specify an options file)
This means you probably want Exuberant Ctags or Universal Ctags. The basic
old BSD Ctags WON'T WORK. Other language-specific versions may or may not
work. Check with their help or man page.
1.2 Similar Plugins
*gutentags-similar-plugins*
There are some similar Vim plugins out there ("vim-tags", "vim-autotag",
"vim-automatic-ctags", etc.). They all fail on one or more of the requirements
I set for myself with Gutentags:
* No other dependency than running Vim: no Python, Ruby, or whatever.
* Cross-platform: should work on at least Mac and Windows.
* Incremental tags generation: don't re-generate the whole project all the
time. This may be fine for small projects, but it doesn't scale.
* External process management: if the ctags process is taking a long time,
don't run another one because I saved the file again.
* Keep the tag file consistent: don't just append the current file's tags to
the tag file, otherwise you will still "see" tags for deleted or renamed
classes and functions.
* Automatically create the tag file: you open something from a freshly forked
project, it should start indexing it automatically, just like in Sublime Text
or Visual Studio or any other IDE.
=============================================================================
2. Commands *gutentags-commands*
*gutentags-project-commands*
The following commands are only available in buffers that have been found to
belong to a project that should be managed by Gutentags. See
|gutentags_project_root| for how Gutentags figures out the project a file
belongs to. When no project is found (i.e. the file is not under any of the
known project markers), Gutentags is disabled for that buffer, and the
following commands and remarks don't apply.
If you want to force-disable Gutentags for a given project even though it does
match one of the items in |gutentags_project_root|, create a file named
"`.notags`" at the root of the project.
The tag file that Gutentags creates and manages will be named after
|gutentags_ctags_tagfile|, relative to the project's root directory. When
Gutentags finds a valid project root, it will prepend the tag file's path to
'tags', unless |gutentags_ctags_auto_set_tags| is set to 0. This is to make
sure Vim will use that file first.
If a file managed by Gutentags is opened and no tag file already exists,
Gutentags will start generating it right away in the background, unless
|gutentags_generate_on_missing| is set to 0. If you have a large project, you
may want to know when Gutentags is generating tags: see
|gutentags-status-line| to display an indicator in your status line.
When a file managed by Gutentags is saved, the tag file will be incrementally
updated, i.e. references to the recently saved file are removed, and that file
is re-parsed for tags, with the result being merged into the tag file. This
makes the tag file 100% consistent with the latest changes. This doesn't
happen however if |gutentags_generate_on_write| is set to 0, in which case you
have to run |GutentagsUpdate| manually.
*:GutentagsUpdate*
:GutentagsUpdate
Forces an update of the current tag file with the
current buffer. If tags are already being generated,
you will be notified and the command will abort.
:GutentagsUpdate!
Like |GutentagsUpdate|, but updates the current tags
file with the whole project instead of just the
current buffer.
Some debugging/troubleshooting commands are also available if the
|gutentags_define_advanced_commands| global setting is set to 1.
*:GutentagsToggleEnabled*
:GutentagsToggleEnabled
Disables and re-enables Gutentags.
When Gutentags is disabled, it won't update your tag
file when you save a buffer. It will however still
look for project markers as you open new buffers so
that they can start working again when you re-enable
Gutentags.
{only available when
|gutentags_define_advanced_commands| is set}
*GutentagsToggleTrace*
:GutentagsToggleTrace
If you want to keep an eye on what Gutentags is doing,
you can enable tracing. This will show messages every
time Gutentags does something. It can get annoying
quickly, since it will require you to press a key to
dismiss those messages, but it can be useful to
troubleshoot a problem.
In addition to messages in Vim, it will also make
Gutentags redirect the output of the tag generation
script to a `.log` file in the project root.
{only available when
|gutentags_define_advanced_commands| is set}
Gutentags also has some user auto-commands (see |User| and |:doautocmd|):
*GutentagsUpdating*
GutentagsUpdating
This auto-command is triggered when a background
update job has started.
*GutentagsUpdated*
GutentagsUpdated
This auto-command is triggered when a background
update job has finished.
=============================================================================
3. Status Line *gutentags-status-line*
Tag file generation can take a while if you're working on a project big
enough. In that case, you may want to know when `ctags` is running, so you
have a heads up if some of the tags aren't recognized yet.
*gutentags#statusline()*
You can display an indicator of tag generation progress in your |status-line|
with the following function: >
:set statusline+=%{gutentags#statusline()}
The function will, by default, print a list of modules in the status line. So
if the `ctags` module (see |g:gutentags_modules|) is currently generating
a tags file, you will see "ctags" printed in the status line. If nothing is
happening, nothing will be printed in the status line.
You can pass some parameters to customize this:
1. A prefix string (defaults to `""`).
2. A suffix string (defaults to `""`).
3. The text to print (defaults to the names of modules currently generating
something).
So using `gutentags#statusline('[', ']')` would print `"[ctags]"` instead of
`"ctags"`.
Because Gutentags runs the tag generation in the background, the statusline
indicator might stay there even after the background process has ended. It
would only go away when Vim decides to refresh the statusline. You can force
refresh it in a callback on |GutentagsUpdating| and |GutentagsUpdated|.
For instance, with the `lightline` plugin:
augroup MyGutentagsStatusLineRefresher
autocmd!
autocmd User GutentagsUpdating call lightline#update()
autocmd User GutentagsUpdated call lightline#update()
augroup END
*gutentags#statusline_cb*
As an alternative to the previous function, `gutentags#statusline_cb` takes
a single parameter which should be a |Funcref| or a function name. This
function should take a list of active module names, and return a string. This
lets you completely control what the status line will print.
For instance:
function! s:get_gutentags_status(mods) abort
let l:msg = ''
if index(a:mods, 'ctags') >= 0
let l:msg .= '♨'
endif
if index(a:mods, 'cscope') >= 0
let l:msg .= '♺'
endif
return l:msg
endfunction
:set statusline+=%{gutentags#statusline_cb(
\function('<SID>get_gutentags_status'))}
By default, the callback function doesn't get called if no tags generation is
currently happening. You can pass `1` as a second argument so that the
callback function is always called.
=============================================================================
4. Global Settings *gutentags-settings*
The following settings can be defined in your |vimrc| to change the default
behaviour of Gutentags.
*gutentags_enabled*
g:gutentags_enabled
Defines whether Gutentags should be enabled. When
disabled, Gutentags will still scan for project root
markers when opening buffers. This is so that when you
re-enable Gutentags, you won't have some buffers
mysteriously working while others (those open last)
don't.
Defaults to `1`.
*gutentags_trace*
g:gutentags_trace
When true, Gutentags will spit out debugging
information as Vim messages (which you can later read
with |:messages|). It also runs its background scripts
with extra parameters to log activity to a `tags.log`
file that you can also inspect for more information.
Note: you can run `:verbose GutentagsUpdate` to
temporarily set |g:gutentags_trace| to `1` for that
update only.
Defaults to `0`.
*gutentags_dont_load*
g:gutentags_dont_load
Prevents Gutentags from loading at all on Vim startup.
The difference between this and |gutentags_enabled| is
that |gutentags_enabled| can be turned on and off in
the same Vim session -- Gutentags as a plugin stays
loaded and will keep track of what happened while it
was disabled. However, |gutentags_dont_load| only
works on Vim startup and will prevent Gutentags from
loading at all, as if it wasn't there.
*gutentags_modules*
g:gutentags_modules
A list of modules to load with Gutentags. Each module
is responsible for generating a specific type of tags
file.
Valid values are:
- `ctags`: generates a `tags` file using
a `ctags`-compatible program like Exhuberant Ctags
or Universal Ctags.
- `cscope`: generates a code database file using
`cscope`.
- `pycscope`: generates a code database file using
`pycscope`.
- `gtags_cscope`: same as `cscope` but uses GNU's
`gtags` executable and database.
- `cscope_maps`: same as `cscope`. Supports
`cscope_maps.nvim`.
Defaults to `[ctags]`.
*gutentags_project_root*
g:gutentags_project_root
When a buffer is loaded, Gutentags will figure out if
it's part of a project that should have tags managed
automatically. To do this, it looks for "root markers"
in the current file's directory and its parent
directories. If it finds any of those markers,
Gutentags will be enabled for the project, and a tags
file named after |gutentags_ctags_tagfile| will be
created at the project root.
Defaults to `[]` (an empty |List|).
A list of default markers will be appended to the
user-defined ones unless
|gutentags_add_default_project_roots| is set to 0.
*gutentags_add_default_project_roots*
g:gutentags_add_default_project_roots
Defines whether Gutentags should always define some
default project roots (see |gutentags_project_root|).
This can be useful to prevent unnecessary disk access
when Gutentags searches for a project root.
The default markers are:
`['.git', '.hg', '.svn', '.bzr', '_darcs', '_darcs', '_FOSSIL_', '.fslckout']`
*gutentags_add_ctrlp_root_markers*
g:gutentags_add_ctrlp_root_markers
If Gutentags finds `g:ctrlp_root_markers` (used by the
CtrlP plugin), it will append those root markers to
the existing ones (see |g:gutentags_project_root|).
Set this to 0 to stop it from happening.
Defaults to 1.
*gutentags_exclude_filetypes*
g:gutentags_exclude_filetypes
A |List| of file types (see |'filetype'|) that Gutentags
should ignore. When a buffer is opened, if its
'filetype' is found in this list, Gutentags features
won't be available for this buffer.
Defaults to an empty list (`[]`).
*gutentags_exclude_project_root*
g:gutentags_exclude_project_root
A list of project roots to generally ignore. If a file
is opened inside one of those projects, Gutentags
won't be activated. This is similar to placing
a `.notags` file in the root of those projects, but
can be useful when you don't want to, or can't, place
such a file there.
Defaults to `['/usr/local', '/opt/homebrew', '/home/linuxbrew/.linuxbrew']`,
which are the folders where Homebrew is known to
create a Git repository by default.
*gutentags_project_root_finder*
g:gutentags_project_root_finder
When a buffer is loaded, Gutentags uses a default
(internal) implementation to find that file's
project's root directory, using settings like
|g:gutentags_project_root|. When you specify
|g:gutentags_project_root_finder|, you can tell
Gutentags to use a custom implementation, such as
`vim-projectroot`. The value of this setting must be
the name of a function that takes a single string
argument (the path to the current buffer's file) and
returns a string value (the project's root directory).
Defaults to `''`.
Note: when set, the called implementation will
possibly ignore |g:gutentags_project_root|.
Note: an implementation can fallback to the default
behaviour by calling
`gutentags#default_get_project_root`.
*gutentags_generate_on_missing*
g:gutentags_generate_on_missing
If set to 1, Gutentags will start generating an initial
tag file if a file is open in a project where no tags
file is found. See |gutentags_project_root| for how
Gutentags locates the project.
When set to 0, Gutentags will only generate the first
time the file is saved (if
|gutentags_generate_on_write| is set to 1), or when
|GutentagsUpdate| or |GutentagsGenerate| is run.
Defaults to 1.
*gutentags_generate_on_new*
g:gutentags_generate_on_new
If set to 1, Gutentags will start generating the tag
file when a new project is open. A new project is
considered open when a buffer is created for a file
whose corresponding tag file has not been "seen" yet
in the current Vim session -- which pretty much means
when you open the first file in a given source control
repository.
When set to 0, Gutentags won't do anything special.
See also |gutentags_generate_on_missing| and
|gutentags_generate_on_write|.
Defaults to 1.
*gutentags_generate_on_write*
g:gutentags_generate_on_write
If set to 1, Gutentags will update the current
project's tag file when a file inside that project is
saved. See |gutentags_project_root| for how Gutentags
locates the project.
When set to 0, Gutentags won't do anything on save.
This means that the project's tag file won't reflect
the latest changes, and you will have to run
|GutentagsUpdate| manually.
Defaults to 1.
*gutentags_generate_on_empty_buffer*
g:gutentags_generate_on_empty_buffer
If set to 1, Gutentags will start generating the tag
file even if there's no buffer currently open, as long
as the current working directory (as returned by
|:cd|) is inside a known project.
This is useful if you want Gutentags to generate the
tag file right after opening Vim.
Defaults to 0.
*gutentags_background_update*
g:gutentags_background_update
Specifies whether the process that updates the tags
file should be run in the background or in the
foreground. If run in the foreground, Vim will block
until the process is complete.
Defaults to 1.
*gutentags_cache_dir*
g:gutentags_cache_dir
Specifies a directory in which to create all the tags
files, instead of writing them at the root of each
project. This is handy to keep tags files from
polluting many directories all across your computer.
*gutentags_resolve_symlinks*
g:gutentags_resolve_symlinks
When set to 1, Gutentags will resolve any symlinks in
the current buffer's path in order to find the project
it belongs to. This is what you want if you're editing
a symlink located outside of the project, and it
points to a file inside the project. However, this is
maybe not what you want if the symlink itself is
part of the project.
Defaults to 0.
*gutentags_init_user_func*
g:gutentags_init_user_func
When set to a non-empty string, it is expected to be
the name of a function that will be called when a file
is opened in a project. The function gets passed the
path of the file and if it returns 0, Gutentags won't
be enabled for that file.
You can use this to manually set buffer-local
settings:
* `b:gutentags_ctags_tagfile` (see |gutentags_ctags_tagfile|).
This setting was previously called
`gutentags_enabled_user_func`. The old setting is
still used as a fallback.
Defaults to "".
*gutentags_define_advanced_commands*
g:gutentags_define_advanced_commands
Defines some advanced commands like
|GutentagsToggleEnabled| and |GutentagsUnlock|.
*gutentags_project_info*
g:gutentags_project_info
Defines ways for Gutentags to figure out what kind of
project any given file belongs to. This should be
a list of dictionaries:
let g:gutentags_project_info = []
call add(g:gutentags_project_info, {...})
Each dictionary item must contain at least a `type`
key, indicating the type of project:
{"type": "python"}
Other items will be used to figure out if a project is
of the given type.
"file": any existing file with this path (relative to
the project root) will make the current project match
the given info.
"glob": any result found with this glob pattern
(relative to the project root) will make the current
project match the given info. See |glob()| for more
information.
Gutentags adds by default the following definitions:
call add(g:gutentags_project_info, {'type': 'python', 'file': 'setup.py'})
call add(g:gutentags_project_info, {'type': 'ruby', 'file': 'Gemfile'})
This means, for example, that you can use
`g:gutentags_ctags_executable_ruby` out of the box.
See |gutentags_ctags_executable_{filetype}| for more
information.
*gutentags_file_list_command*
g:gutentags_file_list_command
Specifies command(s) to use to list files for which
tags should be generated, instead of recursively
examining all files within the project root. When
invoked, file list commands will execute in the
project root directory.
This setting is useful in projects using source
control to restrict tag generation to only files
tracked in the repository.
This variable may be set in one of two ways. If
set as a |String|, the specified command will be used to
list files for all projects. For example: >
let g:gutentags_file_list_command = 'find . -type f'
<
If set as a |Dictionary|, this variable should be set
as a mapping of project root markers to the desired
file list command for that root marker. (See
|gutentags_project_root| for how Gutentags uses root
markers to locate the project.) For example: >
let g:gutentags_file_list_command = {
\ 'markers': {
\ '.git': 'git ls-files',
\ '.hg': 'hg files',
\ },
\ }
<
Note: If a custom ctags executable is specified, it
must support the '-L' command line option in order to
read the list of files to be examined.
The following settings are valid for the `ctags` module.
*gutentags_ctags_executable*
g:gutentags_ctags_executable
Specifies the ctags executable to launch.
Defaults to `ctags`.
*gutentags_ctags_executable_{filetype}*
g:gutentags_ctags_executable_{type}
Specifies the ctags executable to launch for a project
of type {type}. See |gutentags_project_info| for more
information.
IMPORTANT: please see |gutentags-ctags-requirements|.
Example: >
let g:gutentags_ctags_executable_ruby = 'ripper-tags'
<
*gutentags_ctags_tagfile*
g:gutentags_ctags_tagfile
Specifies the name of the tag file to create. This
will be appended to the project's root. See
|gutentags_project_root| for how Gutentags locates the
project.
Defaults to `tags`.
*gutentags_ctags_exclude*
g:gutentags_ctags_exclude
A list of file patterns to pass to the
|gutentags_ctags_executable| so that they will be
excluded from parsing for the tags generation.
See also |gutentags_ctags_exclude_wildignore|.
Defaults to `[]` (an empty |List|).
*gutentags_ctags_exclude_wildignore*
g:gutentags_ctags_exclude_wildignore
When 1, Gutentags will automatically pass your
'wildignore' file patterns to the
|gutentags_ctags_executable| so that they are ignored.
Set also |gutentags_ctags_exclude| to pass custom
patterns.
Defaults to 1.
*gutentags_ctags_auto_set_tags*
g:gutentags_ctags_auto_set_tags
If set to 1, Gutentags will automatically prepend
'tags' with the exact path to the tag file for the
current project. See |gutentags_project_root| for how
Gutentags locates the project.
When set to 0, Gutentags doesn't change 'tags', and
this means that whatever tag file it generates may
not be picked up by Vim. See |tagfiles()| to know what
tag files Vim knows about.
Defaults to 1.
*gutentags_ctags_extra_args*
g:gutentags_ctags_extra_args
A list of arguments to pass to `ctags`.
Defaults to `[]`.
*gutentags_ctags_post_process_cmd*
g:gutentags_ctags_post_process_cmd
If defined, the tags generation script will run the
command with an argument that points to a temporary
copy of the tags file. If the post-process step is
modifying the tags file, it needs to do so in-place.
This is useful for cleaning up a tags file that may
contain tags with non-ASCII names that somehow upsets
Vim.
Defaults to `""` (an empty |String|).
The following settings are valid for the `cscope` module.
*gutentags_cscope_executable*
g:gutentags_cscope_executable
Specifies the name or path of the `cscope` executable
to use to generate the code database.
Defaults to `"cscope"`.
*gutentags_scopefile*
g:gutentags_scopefile
Specifies the name of the scope file to create. This
will be appended to the project's root. See
|gutentags_project_root| for how Gutentags locates the
project.
Defaults to `"cscope.out"`.
*gutentags_auto_add_cscope*
g:gutentags_auto_add_cscope
If set to 1, Gutentags will automatically add the
generated code database to Vim by running `:cs add`
(see |:cscope|).
Defaults to 1.
*gutentags_cscope_build_inverted_index*
g:gutentags_cscope_build_inverted_index
If set to 1, Gutentags will make `cscope` build an
inverted index.
Defaults to 0.
The following settings are valid for the `pycscope` module.
*gutentags_pycscope_executable*
g:gutentags_pycscope_executable
Specifies the name or path of the `pycscope` executable
to use to generate the code database.
Defaults to `"pycscope"`.
*gutentags_auto_add_pycscope*
g:gutentags_auto_add_pycscope
If set to 1, Gutentags will automatically add the
generated code database to Vim by running `:cs add`
(see |:pycscope|).
Defaults to 1.
The following settings are valid for the `gtags_cscope` module.
*gutentags_gtags_executable*
g:gutentags_gtags_executable
Specifies the name or path of the `gtags` executable
to use to generate the code database.
Defaults to `"gtags"`.
*gutentags_gtags_cscope_executable*
g:gutentags_gtags_cscope_executable
Specifies the name or path of the `gtags-cscope`
executable to use to generate the code database.
Defaults to `"gtags-cscope"`.
*gutentags_gtags_dbpath*
g:gutentags_gtags_dbpath
Path from the cache directory (|gutentags_cache_dir|
or project root) to the folder containing the
definition database file (usually called `GTAGS`).
Defaults to `""`.
*gutentags_gtags_options_file*
g:gutentags_gtags_options_file
The name of a file that will be looked for in
a project root directory. The file is expected to
contain `gtags` options (one per line).
Defaults to `".gutgtags"`.
*gutentags_auto_add_gtags_cscope*
g:gutentags_auto_add_gtags_cscope
If set to 1, Gutentags will automatically add the
generated code database to Vim by running `:cs add`
(see |:cscope|).
Defaults to 1.
People using `cscope`, `pycscope` or `gtags_cscope` across multiple projects in the same
Vim instance might be interested in the `gutentags_plus` plugin, which handles
switching databases automatically before performing a query.
See https://github.com/skywind3000/gutentags_plus.
=============================================================================
5. Project Settings *gutentags-project-settings*
Gutentags can be customized to some extent on a per-project basis with the
following files present in the project root directory:
*gutentags-.gutctags*
`.gutctags`: if this file exists, Ctags will be told to load additional
command-line parameters by reading it line by line (see the Ctags
documentation for more information). This will override the default options
file, which adds `--recurse=yes`, so unless you are using
|gutentags_file_list_command| you will want to include `--recurse=yes` in your
`.gutctags` file.
Note that for complex reasons, Gutentags can't run `ctags` from the project
root if you're using |gutentags_cache_dir|, so if the `.gutctags` file exists,
it will be pre-processed in order to make all `--exclude=` clauses into
absolute paths (by prepending the project root). The resulting file will be
saved into the cache directory, and passed to `ctags` via the `--options=`
parameter. If you're _not_ using |gutentags_cache_dir|, the `.gutctags` file
is _not_ pre-processed, and is passed as-is via the `--options=` parameter.
*gutentags-.notags*
`.notags`: if this file exists, Gutentags will be disabled completely for that
project.
vim:tw=78:et:ft=help:norl: