vim-gutentags: doc/gutentags.txt annotate

annotate doc/gutentags.txt @ 191:22cd3334cf43

Add documentation on the `GutentagsUpdated` auto-command.

author	Ludovic Chabant <ludovic@chabant.com>
date	Thu, 27 Jul 2017 21:50:08 -0700
parents	6dc4bb6c53ba
children	b50b6d0f82dd

rev	line source
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	1 gutentags.txt Automatic ctags management for VIM
188 676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	2 ___ ___ ___ ___ ___
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	3 /\__\ /\ \ /\__\ /\__\ /\ \
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	4 /:/ _/_ \:\ \ /:/ / /:/ _/_ \:\ \
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	5 /:/ /\ \ \:\ \ /:/__/ /:/ /\__\ \:\ \
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	6 /:/ /::\ \ ___ \:\ \ /::\ \ /:/ /:/ _/_ _____\:\ \
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	7 /:/__\/\:\__\ /\ \ \:\__\ /:/\:\ \ /:/_/:/ /\__\ /::::::::\__\
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	8 \:\ \ /:/ / \:\ \ /:/ / \/__\:\ \ \:\/:/ /:/ / \:\~~\~~\/__/
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	9 \:\ /:/ / \:\ /:/ / \:\__\ \::/_/:/ / \:\ \
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	10 \:\/:/ / \:\/:/ / \/__/ \:\/:/ / \:\ \
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	11 \::/ / \::/ / \::/ / \:\__\
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	12 \/__/ \/__/ \/__/ \/__/
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	13 ___ ___ ___ ___
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	14 /\__\ /\ \ /\__\ /\__\
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	15 /:/ / /::\ \ /:/ _/_ /:/ _/_
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	16 /:/__/ /:/\:\ \ /:/ /\ \ /:/ /\ \
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	17 /::\ \ /:/ /::\ \ /:/ /::\ \ /:/ /::\ \
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	18 /:/\:\ \ /:/_/:/\:\__\ /:/__\/\:\__\ /:/_/:/\:\__\
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	19 \/__\:\ \ \:\/:/ \/__/ \:\ \ /:/ / \:\/:/ /:/ /
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	20 \:\__\ \::/__/ \:\ /:/ / \::/ /:/ /
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	21 \/__/ \:\ \ \:\/:/ / \/_/:/ /
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	22 \:\__\ \::/ / /:/ /
676fe2ea919f Move T's in the ASCII art up a bit. Toni Kunic <tkunic@rocketmail.com> parents: 182 diff changeset	23 \/__/ \/__/ \/__/
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	24
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	25
24 bab5f37faa1e More renaming. Ludovic Chabant <ludovic@chabant.com> parents: 22 diff changeset	26 GUTENTAGS REFERENCE MANUAL
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	27 by Ludovic Chabant
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	28
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	29 gutentags
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	30
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	31 1. Introduction \|gutentags-intro\|
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	32 2. Commands \|gutentags-commands\|
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	33 3. Status Line \|gutentags-status-line\|
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	34 4. Global Settings \|gutentags-settings\|
49 70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	35 5. Project Settings \|gutentags-project-settings\|
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	36
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	37 =============================================================================
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	38 1. Introduction gutentags-intro
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	39
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	40 Gutentags is a plugin that takes care of the much needed management of tags
7 49e3cb99ab27 Small edits. Ludovic Chabant <ludovic@chabant.com> parents: 4 diff changeset	41 files in Vim. It will (re)generate tag files as you work while staying
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	42 completely out of your way. It will even do its best to keep those tag files
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	43 out of your way too. It has no dependencies and just works.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	44
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	45 In order to generate tag files, Gutentags will have to figure out what's in
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	46 your project. To do this, it will locate well-known project root markers like
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	47 SCM folders (.git, .hg, etc.), any custom tags you define (with
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	48 \|gutentags_project_root\|), and even things you may have defined already with
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	49 other plugins, like CtrlP.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	50
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	51 If the current file you're editing is found to be in such a project, Gutentags
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	52 will make sure the tag file for that project is up to date. Then, as you work
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	53 in files in that project, it will partially re-generate the tag file. Every
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	54 time you save, it will silently, in the background, update the tags for that
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	55 file.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	56
129 48045d81f25a Fix some typos in the docs. Ludovic Chabant <ludovic@chabant.com> parents: 128 diff changeset	57 Usually, `ctags` can only append tags to an existing tag file, so Gutentags
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	58 removes the tags for the current file first, to make sure the tag file is
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	59 always consistent with the source code.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	60
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	61 Also, Gutentags is clever enough to not stumble upon itself by triggering
139 ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	62 multiple ctags processes if you save files too fast, or if your project is
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	63 really big.
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	64
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	65
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	66 1.1 Requirements
140 95092f4fbc4b Add some cross-referencing to the help file. Ludovic Chabant <ludovic@chabant.com> parents: 139 diff changeset	67 gutentags-ctags-requirements
139 ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	68
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	69 If you're using the `ctags` modules (which is the default and only working one
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	70 at this point, really), you will need a `tags` generator that supports the
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	71 following arguments:
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	72
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	73 * `-f` (to specify the output file)
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	74 * `--append` (to append to an existing file while keeping it sorted)
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	75 * `--exclude` (to exclude file patterns)
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	76 * `--options` (to specify an options file)
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	77
190 6dc4bb6c53ba minor typos minusf <minusf@gmail.com> parents: 188 diff changeset	78 This means you probably want Exuberant Ctags or Universal Ctags. The basic
139 ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	79 old BSD Ctags WON'T WORK. Other language-specific versions may or may not
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	80 work. Check with their help or man page.
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	81
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	82
ed43e3a87ffd Add `ctags` executable requirements to the documentation page. Ludovic Chabant <ludovic@chabant.com> parents: 138 diff changeset	83 1.2 Similar Plugins
140 95092f4fbc4b Add some cross-referencing to the help file. Ludovic Chabant <ludovic@chabant.com> parents: 139 diff changeset	84 gutentags-similar-plugins
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	85
7 49e3cb99ab27 Small edits. Ludovic Chabant <ludovic@chabant.com> parents: 4 diff changeset	86 There are some similar Vim plugins out there ("vim-tags", "vim-autotag",
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	87 "vim-automatic-ctags", etc.). They all fail on one or more of the requirements
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	88 I set for myself with Gutentags:
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	89
7 49e3cb99ab27 Small edits. Ludovic Chabant <ludovic@chabant.com> parents: 4 diff changeset	90 * No other dependency than running Vim: no Python, Ruby, or whatever.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	91 * Cross-platform: should work on at least Mac and Windows.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	92 * Incremental tags generation: don't re-generate the whole project all the
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	93 time. This may be fine for small projects, but it doesn't scale.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	94 * External process management: if the ctags process is taking a long time,
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	95 don't run another one because I saved the file again.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	96 * Keep the tag file consistent: don't just append the current file's tags to
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	97 the tag file, otherwise you will still "see" tags for deleted or renamed
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	98 classes and functions.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	99 * Automatically create the tag file: you open something from a freshly forked
129 48045d81f25a Fix some typos in the docs. Ludovic Chabant <ludovic@chabant.com> parents: 128 diff changeset	100 project, it should start indexing it automatically, just like in Sublime Text
48045d81f25a Fix some typos in the docs. Ludovic Chabant <ludovic@chabant.com> parents: 128 diff changeset	101 or Visual Studio or any other IDE.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	102
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	103
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	104 =============================================================================
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	105 2. Commands gutentags-commands
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	106
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	107 gutentags-project-commands
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	108 The following commands are only available in buffers that have been found to
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	109 belong to a project that should be managed by Gutentags. See
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	110 \|gutentags_project_root\| for how Gutentags figures out the project a file
142 d4c09aa41e80 Typo nblock <nblock@users.noreply.github.com> parents: 140 diff changeset	111 belongs to. When no project is found (i.e. the file is not under any of the
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	112 known project markers), Gutentags is disabled for that buffer, and the
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	113 following commands and remarks don't apply.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	114
47 7b419abf7fba Add ability to disable Gutentags if a `.notags` file is at the root. Ludovic Chabant <ludovic@chabant.com> parents: 46 diff changeset	115 If you want to force-disable Gutentags for a given project even though it does
7b419abf7fba Add ability to disable Gutentags if a `.notags` file is at the root. Ludovic Chabant <ludovic@chabant.com> parents: 46 diff changeset	116 match one of the items in \|gutentags_project_root\|, create a file named
7b419abf7fba Add ability to disable Gutentags if a `.notags` file is at the root. Ludovic Chabant <ludovic@chabant.com> parents: 46 diff changeset	117 "`.notags`" at the root of the project.
7b419abf7fba Add ability to disable Gutentags if a `.notags` file is at the root. Ludovic Chabant <ludovic@chabant.com> parents: 46 diff changeset	118
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	119 The tag file that Gutentags creates and manages will be named after
165 cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	120 \|gutentags_ctags_tagfile\|, relative to the project's root directory. When
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	121 Gutentags finds a valid project root, it will prepend the tag file's path to
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	122 'tags', unless \|gutentags_ctags_auto_set_tags\| is set to 0. This is to make
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	123 sure Vim will use that file first.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	124
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	125 If a file managed by Gutentags is opened and no tag file already exists,
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	126 Gutentags will start generating it right away in the background, unless
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	127 \|gutentags_generate_on_missing\| is set to 0. If you have a large project, you
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	128 may want to know when Gutentags is generating tags: see
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	129 \|gutentags-status-line\| to display an indicator in your status line.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	130
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	131 When a file managed by Gutentags is saved, the tag file will be incrementally
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	132 updated, i.e. references to the recently saved file are removed, and that file
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	133 is re-parsed for tags, with the result being merged into the tag file. This
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	134 makes the tag file 100% consistent with the latest changes. This doesn't
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	135 happen however if \|gutentags_generate_on_write\| is set to 0, in which case you
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	136 have to run \|GutentagsUpdate\| manually.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	137
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	138
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	139 :GutentagsUpdate
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	140 :GutentagsUpdate
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	141 Forces an update of the current tag file with the
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	142 current buffer. If tags are already being generated,
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	143 you will be notified and the command will abort.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	144
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	145 :GutentagsUpdate!
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	146 Like \|GutentagsUpdate\|, but updates the current tags
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	147 file with the whole project instead of just the
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	148 current buffer.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	149
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	150
46 c0f56e4d52bd Make a bunch of advanced commands opt-in only. Ludovic Chabant <ludovic@chabant.com> parents: 43 diff changeset	151 Some debugging/troubleshooting commands are also available if the
c0f56e4d52bd Make a bunch of advanced commands opt-in only. Ludovic Chabant <ludovic@chabant.com> parents: 43 diff changeset	152 \|gutentags_define_advanced_commands\| global setting is set to 1.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	153
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	154 :GutentagsToggleEnabled
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	155 :GutentagsToggleEnabled
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	156 Disables and re-enables Gutentags.
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	157 When Gutentags is disabled, it won't update your tag
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	158 file when you save a buffer. It will however still
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	159 look for project markers as you open new buffers so
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	160 that they can start working again when you re-enable
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	161 Gutentags.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	162
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	163 GutentagsToggleTrace
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	164 :GutentagsToggleTrace
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	165 If you want to keep an eye on what Gutentags is doing,
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	166 you can enable tracing. This will show messages every
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	167 time Gutentags does something. It can get annoying
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	168 quickly, since it will require you to press a key to
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	169 dismiss those messages, but it can be useful to
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	170 troubleshoot a problem.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	171 In addition to messages in Vim, it will also make
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	172 Gutentags redirect the output of the tag generation
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	173 script to a `.log` file in the project root.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	174
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	175 :GutentagsUnlock
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	176 :GutentagsUnlock
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	177 Gutentags uses a `.lock` file to know when tag
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	178 generation is running. If something goes wrong with
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	179 that process, that lock file could be left behind. You
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	180 could just remove it manually from the root of your
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	181 project, but you can also run \|:GutentagsUnlock\| so
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	182 that Vim does it for you.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	183 If you find that you need to use this more than a
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	184 couple times ever, there's probably a bug with
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	185 Gutentags, or something otherwise wrong or unexpected
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	186 with your system. Please file a bug.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	187
49 70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	188
191 22cd3334cf43 Add documentation on the `GutentagsUpdated` auto-command. Ludovic Chabant <ludovic@chabant.com> parents: 190 diff changeset	189 Gutentags also has some user auto-commands (see \|User\| and \|:doautocmd\|):
22cd3334cf43 Add documentation on the `GutentagsUpdated` auto-command. Ludovic Chabant <ludovic@chabant.com> parents: 190 diff changeset	190
22cd3334cf43 Add documentation on the `GutentagsUpdated` auto-command. Ludovic Chabant <ludovic@chabant.com> parents: 190 diff changeset	191 GutentagsUpdated
22cd3334cf43 Add documentation on the `GutentagsUpdated` auto-command. Ludovic Chabant <ludovic@chabant.com> parents: 190 diff changeset	192 GutentagsUpdated
22cd3334cf43 Add documentation on the `GutentagsUpdated` auto-command. Ludovic Chabant <ludovic@chabant.com> parents: 190 diff changeset	193 This auto-command is triggered when a background
22cd3334cf43 Add documentation on the `GutentagsUpdated` auto-command. Ludovic Chabant <ludovic@chabant.com> parents: 190 diff changeset	194 update job has been started.
22cd3334cf43 Add documentation on the `GutentagsUpdated` auto-command. Ludovic Chabant <ludovic@chabant.com> parents: 190 diff changeset	195
22cd3334cf43 Add documentation on the `GutentagsUpdated` auto-command. Ludovic Chabant <ludovic@chabant.com> parents: 190 diff changeset	196
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	197 =============================================================================
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	198 3. Status Line gutentags-status-line
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	199
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	200 Tag file generation can take a while if you're working on a project big
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	201 enough. In that case, you may want to know when `ctags` is running, so you
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	202 have a heads up if some of the tags aren't recognized yet.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	203
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	204 gutentags#statusline()
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	205 You can display and indicator of tag generation progress in your \|status-line\|
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	206 with the following function: >
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	207 :set statusline+=%{gutentags#statusline()}
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	208
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	209 This won't print anything unless Gutentags figures that `ctags` is running in
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	210 the background. This is done by checking a `.lock` file next to the tag file,
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	211 but there's also some optimization before that to not slow down Vim. Note that
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	212 the `.lock` file can sometimes be left around incorrectly by the background
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	213 process, and you may need to clean it up. See \|:GutentagsUnlock\|.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	214
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	215 When Gutentags thinks `ctags` is still running, it will print the string
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	216 "TAGS" by default. You can customize it: >
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	217 :set statusline+=%{gutentags#statusline('[Generating...]')}
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	218
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	219 This will print the string "[Generating...]" when tags are being generated.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	220
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	221
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	222 =============================================================================
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	223 4. Global Settings gutentags-settings
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	224
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	225 The following settings can be defined in your \|vimrc\| to change the default
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	226 behaviour of Gutentags.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	227
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	228 gutentags_enabled
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	229 g:gutentags_enabled
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	230 Defines whether Gutentags should be enabled. When
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	231 disabled, Gutentags will still scan for project root
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	232 markers when opening buffers. This is so that when you
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	233 re-enable Gutentags, you won't have some buffers
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	234 mysteriously working while others (those open last)
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	235 don't.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	236 Defaults to 1.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	237
149 f915393ff68d Add `g:gutentags_dont_load` setting. Ludovic Chabant <ludovic@chabant.com> parents: 145 diff changeset	238 gutentags_dont_load
f915393ff68d Add `g:gutentags_dont_load` setting. Ludovic Chabant <ludovic@chabant.com> parents: 145 diff changeset	239 g:gutentags_dont_load
f915393ff68d Add `g:gutentags_dont_load` setting. Ludovic Chabant <ludovic@chabant.com> parents: 145 diff changeset	240 Prevents Gutentags from loading at all on Vim startup.
f915393ff68d Add `g:gutentags_dont_load` setting. Ludovic Chabant <ludovic@chabant.com> parents: 145 diff changeset	241
f915393ff68d Add `g:gutentags_dont_load` setting. Ludovic Chabant <ludovic@chabant.com> parents: 145 diff changeset	242 The difference between this and \|gutentags_enabled\| is
f915393ff68d Add `g:gutentags_dont_load` setting. Ludovic Chabant <ludovic@chabant.com> parents: 145 diff changeset	243 that \|gutentags_enabled\| can be turned on and off in
f915393ff68d Add `g:gutentags_dont_load` setting. Ludovic Chabant <ludovic@chabant.com> parents: 145 diff changeset	244 the same Vim session -- Gutentags as a plugin stays
f915393ff68d Add `g:gutentags_dont_load` setting. Ludovic Chabant <ludovic@chabant.com> parents: 145 diff changeset	245 loaded and will keep track of what happened while it
f915393ff68d Add `g:gutentags_dont_load` setting. Ludovic Chabant <ludovic@chabant.com> parents: 145 diff changeset	246 was disabled. However, \|gutentags_dont_load\| only
f915393ff68d Add `g:gutentags_dont_load` setting. Ludovic Chabant <ludovic@chabant.com> parents: 145 diff changeset	247 works on Vim startup and will prevent Gutentags from
f915393ff68d Add `g:gutentags_dont_load` setting. Ludovic Chabant <ludovic@chabant.com> parents: 145 diff changeset	248 loading at all, as if it wasn't there.
f915393ff68d Add `g:gutentags_dont_load` setting. Ludovic Chabant <ludovic@chabant.com> parents: 145 diff changeset	249
43 7000d598a2a7 Documentation changes for some options that changed names. Ludovic Chabant <ludovic@chabant.com> parents: 24 diff changeset	250 gutentags_ctags_executable
7000d598a2a7 Documentation changes for some options that changed names. Ludovic Chabant <ludovic@chabant.com> parents: 24 diff changeset	251 g:gutentags_ctags_executable
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	252 Specifies the ctags executable to launch.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	253 Defaults to `ctags`.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	254
68 ca61487b3215 Add docs about ctags executable per filetype marc <marc@lamarciana.com> parents: 60 diff changeset	255 gutentags_ctags_executable_{filetype}
89 8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	256 g:gutentags_ctags_executable_{type}
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	257 Specifies the ctags executable to launch for a project
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	258 of type {type}. See \|gutentags_project_info\| for more
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	259 information.
144 8a93fca41a38 Fix typo Daniel Campoverde [alx741] <alx@sillybytes.net> parents: 142 diff changeset	260 IMPORTANT: please see \|gutentags-ctags-requirements\|.
68 ca61487b3215 Add docs about ctags executable per filetype marc <marc@lamarciana.com> parents: 60 diff changeset	261 Example: >
140 95092f4fbc4b Add some cross-referencing to the help file. Ludovic Chabant <ludovic@chabant.com> parents: 139 diff changeset	262 let g:gutentags_ctags_executable_ruby = 'foobar'
68 ca61487b3215 Add docs about ctags executable per filetype marc <marc@lamarciana.com> parents: 60 diff changeset	263 <
ca61487b3215 Add docs about ctags executable per filetype marc <marc@lamarciana.com> parents: 60 diff changeset	264
165 cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	265 gutentags_ctags_tagfile
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	266 g:gutentags_ctags_tagfile
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	267 Specifies the name of the tag file to create. This
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	268 will be appended to the project's root. See
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	269 \|gutentags_project_root\| for how Gutentags locates the
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	270 project.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	271 Defaults to `tags`.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	272
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	273 gutentags_project_root
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	274 g:gutentags_project_root
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	275 When a buffer is loaded, Gutentags will figure out if
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	276 it's part of a project that should have tags managed
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	277 automatically. To do this, it looks for "root markers"
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	278 in the current file's directory and its parent
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	279 directories. If it finds any of those markers,
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	280 Gutentags will be enabled for the project, and a tags
165 cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	281 file named after \|gutentags_ctags_tagfile\| will be
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	282 created at the project root.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	283 Defaults to `[]` (an empty \|List\|).
128 e673026faa56 Add option to not append the default project root markers. Ludovic Chabant <ludovic@chabant.com> parents: 124 diff changeset	284 A list of default markers will be appended to the
e673026faa56 Add option to not append the default project root markers. Ludovic Chabant <ludovic@chabant.com> parents: 124 diff changeset	285 user-defined ones unless
e673026faa56 Add option to not append the default project root markers. Ludovic Chabant <ludovic@chabant.com> parents: 124 diff changeset	286 \|gutentags_add_default_project_roots\| is set to 0.
e673026faa56 Add option to not append the default project root markers. Ludovic Chabant <ludovic@chabant.com> parents: 124 diff changeset	287
e673026faa56 Add option to not append the default project root markers. Ludovic Chabant <ludovic@chabant.com> parents: 124 diff changeset	288 gutentags_add_default_project_roots
e673026faa56 Add option to not append the default project root markers. Ludovic Chabant <ludovic@chabant.com> parents: 124 diff changeset	289 g:gutentags_add_default_project_roots
e673026faa56 Add option to not append the default project root markers. Ludovic Chabant <ludovic@chabant.com> parents: 124 diff changeset	290 Defines whether Gutentags should always define some
e673026faa56 Add option to not append the default project root markers. Ludovic Chabant <ludovic@chabant.com> parents: 124 diff changeset	291 default project roots (see \|gutentags_project_root\|).
e673026faa56 Add option to not append the default project root markers. Ludovic Chabant <ludovic@chabant.com> parents: 124 diff changeset	292 This can be useful to prevent unnecessary disk access
e673026faa56 Add option to not append the default project root markers. Ludovic Chabant <ludovic@chabant.com> parents: 124 diff changeset	293 when Gutentags searches for a project root.
e673026faa56 Add option to not append the default project root markers. Ludovic Chabant <ludovic@chabant.com> parents: 124 diff changeset	294 The default markers are:
e673026faa56 Add option to not append the default project root markers. Ludovic Chabant <ludovic@chabant.com> parents: 124 diff changeset	295 `['.git', '.hg', '.bzr', '_darcs', '_darcs', '_FOSSIL_', '.fslckout']`
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	296
118 2838af9ff980 Add `g:gutentags_exclude_project_root`. Ludovic Chabant <ludovic@chabant.com> parents: 98 diff changeset	297 gutentags_exclude_project_root
2838af9ff980 Add `g:gutentags_exclude_project_root`. Ludovic Chabant <ludovic@chabant.com> parents: 98 diff changeset	298 g:gutentags_exclude_project_root
2838af9ff980 Add `g:gutentags_exclude_project_root`. Ludovic Chabant <ludovic@chabant.com> parents: 98 diff changeset	299 A list of project roots to generally ignore. If a file
2838af9ff980 Add `g:gutentags_exclude_project_root`. Ludovic Chabant <ludovic@chabant.com> parents: 98 diff changeset	300 is opened inside one of those projects, Gutentags
2838af9ff980 Add `g:gutentags_exclude_project_root`. Ludovic Chabant <ludovic@chabant.com> parents: 98 diff changeset	301 won't be activated. This is similar to placing
2838af9ff980 Add `g:gutentags_exclude_project_root`. Ludovic Chabant <ludovic@chabant.com> parents: 98 diff changeset	302 a `.notags` file in the root of those projects, but
2838af9ff980 Add `g:gutentags_exclude_project_root`. Ludovic Chabant <ludovic@chabant.com> parents: 98 diff changeset	303 can be useful when you don't want to, or can't, place
2838af9ff980 Add `g:gutentags_exclude_project_root`. Ludovic Chabant <ludovic@chabant.com> parents: 98 diff changeset	304 such a file there.
132 a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	305 Defaults to `['/usr/local']`, which is the folder where
118 2838af9ff980 Add `g:gutentags_exclude_project_root`. Ludovic Chabant <ludovic@chabant.com> parents: 98 diff changeset	306 Homebrew is known to create a Git directory by default
2838af9ff980 Add `g:gutentags_exclude_project_root`. Ludovic Chabant <ludovic@chabant.com> parents: 98 diff changeset	307 on MacOS.
2838af9ff980 Add `g:gutentags_exclude_project_root`. Ludovic Chabant <ludovic@chabant.com> parents: 98 diff changeset	308
132 a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	309 gutentags_project_root_finder
a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	310 g:gutentags_project_root_finder
a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	311 When a buffer is loaded, Gutentags uses a default
a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	312 (internal) implementation to find that file's
a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	313 project's root directory, using settings like
a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	314 \|g:gutentags_project_root\|. When you specify
a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	315 \|g:gutentags_project_root_finder\|, you can tell
a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	316 Gutentags to use a custom implementation, such as
a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	317 `vim-projectroot`. The value of this setting must be
a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	318 the name of a function that takes a single string
a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	319 argument (the path to the current buffer's file) and
a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	320 returns a string value (the project's root directory).
a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	321 Defaults to `''`.
a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	322 Note: when set, the called implementation will most
a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	323 likely ignore \|g:gutentags_project_root\|.
a6ef1c860d07 Add support for custom root finders like `vim-projectroot`. Ludovic Chabant <ludovic@chabant.com> parents: 129 diff changeset	324
165 cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	325 gutentags_ctags_exclude
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	326 g:gutentags_ctags_exclude
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	327 A list of file patterns to pass to the
60 9e768b83d701 Fix missing renames of `gutentags_ctags_executable`. Ludovic Chabant <ludovic@chabant.com> parents: 49 diff changeset	328 \|gutentags_ctags_executable\| so that they will be
9e768b83d701 Fix missing renames of `gutentags_ctags_executable`. Ludovic Chabant <ludovic@chabant.com> parents: 49 diff changeset	329 excluded from parsing for the tags generation.
165 cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	330 See also \|gutentags_ctags_exclude_wildignore\|.
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	331 Defaults to `[]` (an empty \|List\|).
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	332
165 cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	333 gutentags_ctags_exclude_wildignore
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	334 g:gutentags_ctags_exclude_wildignore
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	335 When 1, Gutentags will automatically pass your
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	336 'wildignore' file patterns to the
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	337 \|gutentags_ctags_executable\| so that they are ignored.
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	338 Set also \|gutentags_ctags_exclude\| to pass custom
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	339 patterns.
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	340 Defaults to 1.
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	341
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	342 gutentags_ctags_auto_set_tags
cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	343 g:gutentags_ctags_auto_set_tags
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	344 If set to 1, Gutentags will automatically prepend
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	345 'tags' with the exact path to the tag file for the
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	346 current project. See \|gutentags_project_root\| for how
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	347 Gutentags locates the project.
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	348 When set to 0, Gutentags doesn't change 'tags', and
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	349 this means that whatever tag file it generates may
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	350 not be picked up by Vim. See \|tagfiles()\| to know what
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	351 tag files Vim knows about.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	352 Defaults to 1.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	353
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	354 gutentags_generate_on_missing
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	355 g:gutentags_generate_on_missing
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	356 If set to 1, Gutentags will start generating an initial
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	357 tag file if a file is open in a project where no tags
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	358 file is found. See \|gutentags_project_root\| for how
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	359 Gutentags locates the project.
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	360 When set to 0, Gutentags will only generate the first
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	361 time the file is saved (if
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	362 \|gutentags_generate_on_write\| is set to 1), or when
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	363 \|GutentagsUpdate\| or \|GutentagsGenerate\| is run.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	364 Defaults to 1.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	365
61 735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	366 gutentags_generate_on_new
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	367 g:gutentags_generate_on_new
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	368 If set to 1, Gutentags will start generating the tag
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	369 file when a new project is open. A new project is
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	370 considered open when a buffer is created for a file
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	371 whose corresponding tag file has not been "seen" yet
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	372 in the current Vim session -- which pretty much means
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	373 when you open the first file in a given source control
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	374 repository.
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	375 When set to 0, Gutentags won't do anything special.
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	376 See also \|gutentags_generate_on_missing\| and
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	377 \|gutentags_generate_on_write\|.
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	378 Defaults to 1.
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	379
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	380 gutentags_generate_on_write
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	381 g:gutentags_generate_on_write
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	382 If set to 1, Gutentags will update the current
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	383 project's tag file when a file inside that project is
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	384 saved. See \|gutentags_project_root\| for how Gutentags
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	385 locates the project.
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	386 When set to 0, Gutentags won't do anything on save.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	387 This means that the project's tag file won't reflect
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	388 the latest changes, and you will have to run
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	389 \|GutentagsUpdate\| manually.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	390 Defaults to 1.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	391
182 2489b4b54d5c Add `g:gutentags_generate_on_empty_buffer` setting. Ludovic Chabant <ludovic@chabant.com> parents: 165 diff changeset	392 gutentags_generate_on_empty_buffer
2489b4b54d5c Add `g:gutentags_generate_on_empty_buffer` setting. Ludovic Chabant <ludovic@chabant.com> parents: 165 diff changeset	393 g:gutentags_generate_on_empty_buffer
2489b4b54d5c Add `g:gutentags_generate_on_empty_buffer` setting. Ludovic Chabant <ludovic@chabant.com> parents: 165 diff changeset	394 If set to 1, Gutentags will start generating the tag
2489b4b54d5c Add `g:gutentags_generate_on_empty_buffer` setting. Ludovic Chabant <ludovic@chabant.com> parents: 165 diff changeset	395 file even if there's no buffer currently open, as long
2489b4b54d5c Add `g:gutentags_generate_on_empty_buffer` setting. Ludovic Chabant <ludovic@chabant.com> parents: 165 diff changeset	396 as the current working directory (as returned by
2489b4b54d5c Add `g:gutentags_generate_on_empty_buffer` setting. Ludovic Chabant <ludovic@chabant.com> parents: 165 diff changeset	397 \|:cd\|) is inside a known project.
2489b4b54d5c Add `g:gutentags_generate_on_empty_buffer` setting. Ludovic Chabant <ludovic@chabant.com> parents: 165 diff changeset	398 This is useful if you want Gutentags to generate the
2489b4b54d5c Add `g:gutentags_generate_on_empty_buffer` setting. Ludovic Chabant <ludovic@chabant.com> parents: 165 diff changeset	399 tag file right after opening Vim.
2489b4b54d5c Add `g:gutentags_generate_on_empty_buffer` setting. Ludovic Chabant <ludovic@chabant.com> parents: 165 diff changeset	400 Defaults to 0.
2489b4b54d5c Add `g:gutentags_generate_on_empty_buffer` setting. Ludovic Chabant <ludovic@chabant.com> parents: 165 diff changeset	401
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	402 gutentags_background_update
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	403 g:gutentags_background_update
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	404 Specifies whether the process that updates the tags
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	405 file should be run in the background or in the
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	406 foreground. If run in the foreground, Vim will block
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	407 until the process is complete.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	408 Defaults to 1.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	409
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	410 gutentags_cache_dir
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	411 g:gutentags_cache_dir
20 bd136cb41034 Update documentation. Ludovic Chabant <ludovic@chabant.com> parents: 17 diff changeset	412 Specifies a directory in which to create all the tags
bd136cb41034 Update documentation. Ludovic Chabant <ludovic@chabant.com> parents: 17 diff changeset	413 files, instead of writing them at the root of each
bd136cb41034 Update documentation. Ludovic Chabant <ludovic@chabant.com> parents: 17 diff changeset	414 project. This is handy to keep tags files from
bd136cb41034 Update documentation. Ludovic Chabant <ludovic@chabant.com> parents: 17 diff changeset	415 polluting many directories all across your computer.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	416
85 0424970d81f8 Add a `g:gutentags_resolve_symlinks` option to resolve symlinks at setup time. Ludovic Chabant <ludovic@chabant.com> parents: 74 diff changeset	417 gutentags_resolve_symlinks
0424970d81f8 Add a `g:gutentags_resolve_symlinks` option to resolve symlinks at setup time. Ludovic Chabant <ludovic@chabant.com> parents: 74 diff changeset	418 g:gutentags_resolve_symlinks
0424970d81f8 Add a `g:gutentags_resolve_symlinks` option to resolve symlinks at setup time. Ludovic Chabant <ludovic@chabant.com> parents: 74 diff changeset	419 When set to 1, Gutentags will resolve any symlinks in
0424970d81f8 Add a `g:gutentags_resolve_symlinks` option to resolve symlinks at setup time. Ludovic Chabant <ludovic@chabant.com> parents: 74 diff changeset	420 the current buffer's path in order to find the project
0424970d81f8 Add a `g:gutentags_resolve_symlinks` option to resolve symlinks at setup time. Ludovic Chabant <ludovic@chabant.com> parents: 74 diff changeset	421 it belongs to. This is what you want if you're editing
0424970d81f8 Add a `g:gutentags_resolve_symlinks` option to resolve symlinks at setup time. Ludovic Chabant <ludovic@chabant.com> parents: 74 diff changeset	422 a symlink located outside of the project, and it
0424970d81f8 Add a `g:gutentags_resolve_symlinks` option to resolve symlinks at setup time. Ludovic Chabant <ludovic@chabant.com> parents: 74 diff changeset	423 points to a file inside the project. However, this is
0424970d81f8 Add a `g:gutentags_resolve_symlinks` option to resolve symlinks at setup time. Ludovic Chabant <ludovic@chabant.com> parents: 74 diff changeset	424 maybe not what you want if the symlink itself is
0424970d81f8 Add a `g:gutentags_resolve_symlinks` option to resolve symlinks at setup time. Ludovic Chabant <ludovic@chabant.com> parents: 74 diff changeset	425 part of the project.
0424970d81f8 Add a `g:gutentags_resolve_symlinks` option to resolve symlinks at setup time. Ludovic Chabant <ludovic@chabant.com> parents: 74 diff changeset	426 Defaults to 0.
88 073e63cc0456 Add `gutentags_enabled_user_func` callback. Ludovic Chabant <ludovic@chabant.com> parents: 85 diff changeset	427
141 7bc4df0225d1 Add support for specifying buffer-specific tagfiles. Ludovic Chabant <ludovic@chabant.com> parents: 140 diff changeset	428 gutentags_init_user_func
7bc4df0225d1 Add support for specifying buffer-specific tagfiles. Ludovic Chabant <ludovic@chabant.com> parents: 140 diff changeset	429 g:gutentags_init_user_func
88 073e63cc0456 Add `gutentags_enabled_user_func` callback. Ludovic Chabant <ludovic@chabant.com> parents: 85 diff changeset	430 When set to a non-empty string, it is expected to be
073e63cc0456 Add `gutentags_enabled_user_func` callback. Ludovic Chabant <ludovic@chabant.com> parents: 85 diff changeset	431 the name of a function that will be called when a file
123 76a4822aab76 Use existing b:gutentags_root Daniel Hahler <git@thequod.de> parents: 98 diff changeset	432 is opened in a project. The function gets passed the
88 073e63cc0456 Add `gutentags_enabled_user_func` callback. Ludovic Chabant <ludovic@chabant.com> parents: 85 diff changeset	433 path of the file and if it returns 0, Gutentags won't
073e63cc0456 Add `gutentags_enabled_user_func` callback. Ludovic Chabant <ludovic@chabant.com> parents: 85 diff changeset	434 be enabled for that file.
141 7bc4df0225d1 Add support for specifying buffer-specific tagfiles. Ludovic Chabant <ludovic@chabant.com> parents: 140 diff changeset	435
7bc4df0225d1 Add support for specifying buffer-specific tagfiles. Ludovic Chabant <ludovic@chabant.com> parents: 140 diff changeset	436 You can use this to manually set buffer-local
7bc4df0225d1 Add support for specifying buffer-specific tagfiles. Ludovic Chabant <ludovic@chabant.com> parents: 140 diff changeset	437 settings:
7bc4df0225d1 Add support for specifying buffer-specific tagfiles. Ludovic Chabant <ludovic@chabant.com> parents: 140 diff changeset	438
165 cbc1ebe23ef1 Rename all ctags-related options to have "ctags" in their name. Ludovic Chabant <ludovic@chabant.com> parents: 149 diff changeset	439 * `b:gutentags_ctags_tagfile` (see \|gutentags_ctags_tagfile\|).
141 7bc4df0225d1 Add support for specifying buffer-specific tagfiles. Ludovic Chabant <ludovic@chabant.com> parents: 140 diff changeset	440
7bc4df0225d1 Add support for specifying buffer-specific tagfiles. Ludovic Chabant <ludovic@chabant.com> parents: 140 diff changeset	441 This setting was previously called
7bc4df0225d1 Add support for specifying buffer-specific tagfiles. Ludovic Chabant <ludovic@chabant.com> parents: 140 diff changeset	442 `gutentags_enabled_user_func`. The old setting is
7bc4df0225d1 Add support for specifying buffer-specific tagfiles. Ludovic Chabant <ludovic@chabant.com> parents: 140 diff changeset	443 still used as a fallback.
7bc4df0225d1 Add support for specifying buffer-specific tagfiles. Ludovic Chabant <ludovic@chabant.com> parents: 140 diff changeset	444
88 073e63cc0456 Add `gutentags_enabled_user_func` callback. Ludovic Chabant <ludovic@chabant.com> parents: 85 diff changeset	445 Defaults to "".
85 0424970d81f8 Add a `g:gutentags_resolve_symlinks` option to resolve symlinks at setup time. Ludovic Chabant <ludovic@chabant.com> parents: 74 diff changeset	446
46 c0f56e4d52bd Make a bunch of advanced commands opt-in only. Ludovic Chabant <ludovic@chabant.com> parents: 43 diff changeset	447 gutentags_define_advanced_commands
c0f56e4d52bd Make a bunch of advanced commands opt-in only. Ludovic Chabant <ludovic@chabant.com> parents: 43 diff changeset	448 g:gutentags_define_advanced_commands
c0f56e4d52bd Make a bunch of advanced commands opt-in only. Ludovic Chabant <ludovic@chabant.com> parents: 43 diff changeset	449 Defines some advanced commands like
c0f56e4d52bd Make a bunch of advanced commands opt-in only. Ludovic Chabant <ludovic@chabant.com> parents: 43 diff changeset	450 \|GutentagsToggleEnabled\| and \|GutentagsUnlock\|.
c0f56e4d52bd Make a bunch of advanced commands opt-in only. Ludovic Chabant <ludovic@chabant.com> parents: 43 diff changeset	451
89 8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	452 gutentags_project_info
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	453 g:gutentags_project_info
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	454 Defines ways for Gutentags to figure out what kind of
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	455 project any given file belongs to. This should be
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	456 a list of dictionaries:
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	457
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	458 let g:gutentags_project_info = []
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	459 call add(g:gutentags_project_info, {...})
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	460
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	461 Each dictionary item must contain at least a `type`
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	462 key, indicating the type of project:
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	463
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	464 {"type": "python"}
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	465
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	466 Other items will be used to figure out if a project is
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	467 of the given type.
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	468
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	469 "file": any existing file with this path (relative to
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	470 the project root) will make the current project match
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	471 the given info.
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	472
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	473 "glob": any result found with this glob pattern
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	474 (relative to the project root) will make the current
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	475 project match the given info. See \|glob()\| for more
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	476 information.
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	477
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	478 Gutentags adds by default the following definitions:
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	479
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	480 call add(g:gutentags_project_info, {'type': 'python', 'file': 'setup.py'})
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	481 call add(g:gutentags_project_info, {'type': 'ruby', 'file': 'Gemfile'})
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	482
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	483 This means, for example, that you can use
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	484 `g:gutentags_ctags_executable_ruby` out of the box.
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	485 See \|gutentags_ctags_executable_{filetype}\| for more
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	486 information.
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	487
136 286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	488 gutentags_file_list_command
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	489 g:gutentags_file_list_command
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	490 Specifies command(s) to use to list files for which
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	491 tags should be generated, instead of recursively
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	492 examining all files within the project root. When
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	493 invoked, file list commands will execute in the
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	494 project root directory.
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	495
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	496 This setting is useful in projects using source
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	497 control to restrict tag generation to only files
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	498 tracked in the repository.
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	499
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	500 This variable may be set in one of two ways. If
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	501 set as a \|String\|, the specified command will be used to
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	502 list files for all projects. For example: >
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	503
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	504 let g:gutentags_file_list_command = 'find . -type f'
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	505 <
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	506 If set as a \|Dictionary\|, this variable should be set
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	507 as a mapping of project root markers to the desired
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	508 file list command for that root marker. (See
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	509 \|gutentags_project_root\| for how Gutentags uses root
190 6dc4bb6c53ba minor typos minusf <minusf@gmail.com> parents: 188 diff changeset	510 markers to locate the project.) For example: >
136 286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	511
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	512 let g:gutentags_file_list_command = {
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	513 \ 'markers': {
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	514 \ '.git': 'git ls-files',
138 851aec42057d Use `hg files` in the example (`locate` is deprecated). Ludovic Chabant <ludovic@chabant.com> parents: 136 diff changeset	515 \ '.hg': 'hg files',
136 286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	516 \ },
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	517 \ }
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	518 <
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	519 Note: If a custom ctags executable is specified, it
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	520 must support the '-L' command line option in order to
286e5b3095d0 Allow restricting tag generation to files listed by custom commands Stephen Kent <smkent@smkent.net> parents: 132 diff changeset	521 read the list of files to be examined.
0 a3a37124558b Initial commit. Ludovic Chabant <ludovic@chabant.com> parents: diff changeset	522
49 70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	523 =============================================================================
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	524 5. Project Settings gutentags-project-settings
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	525
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	526 Gutentags can be customized to some extent on a per-project basis with the
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	527 following files present in the project root directory:
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	528
74 cb1cf815052e Fix the documentation about the project settings file. Ludovic Chabant <ludovic@chabant.com> parents: 69 diff changeset	529 gutentags-.gutctags
cb1cf815052e Fix the documentation about the project settings file. Ludovic Chabant <ludovic@chabant.com> parents: 69 diff changeset	530 `.gutctags`: if this file exists, Ctags will be told to load additional
49 70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	531 command-line parameters by reading it line by line (see the Ctags
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	532 documentation for more information).
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	533
74 cb1cf815052e Fix the documentation about the project settings file. Ludovic Chabant <ludovic@chabant.com> parents: 69 diff changeset	534 Note that for complex reasons, Gutentags can't run `ctags` from the project
cb1cf815052e Fix the documentation about the project settings file. Ludovic Chabant <ludovic@chabant.com> parents: 69 diff changeset	535 root if you're using \|gutentags_cache_dir\|, so if the `.gutctags` file exists,
cb1cf815052e Fix the documentation about the project settings file. Ludovic Chabant <ludovic@chabant.com> parents: 69 diff changeset	536 it will be pre-processed in order to make all `--exclude=` clauses into
cb1cf815052e Fix the documentation about the project settings file. Ludovic Chabant <ludovic@chabant.com> parents: 69 diff changeset	537 absolute paths (by prepending the project root). The resulting file will be
cb1cf815052e Fix the documentation about the project settings file. Ludovic Chabant <ludovic@chabant.com> parents: 69 diff changeset	538 saved into the cache directory, and passed to `ctags` via the `--options=`
cb1cf815052e Fix the documentation about the project settings file. Ludovic Chabant <ludovic@chabant.com> parents: 69 diff changeset	539 parameter. If you're _not_ using \|gutentags_cache_dir\|, the `.gutctags` file
cb1cf815052e Fix the documentation about the project settings file. Ludovic Chabant <ludovic@chabant.com> parents: 69 diff changeset	540 is _not_ pre-processed, and is passed as-is via the `--options=` parameter.
49 70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	541
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	542 gutentags-.notags
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	543 `.notags`: if this file exists, Gutentags will be disabled completely for that
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	544 project.
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	545
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	546
0 a3a37124558b Initial commit. Ludovic Chabant <ludovic@chabant.com> parents: diff changeset	547 vim:tw=78:et:ft=help:norl:

Mercurial > vim-gutentags

annotate doc/gutentags.txt @ 191:22cd3334cf43