vim-gutentags: doc/gutentags.txt annotate

annotate doc/gutentags.txt @ 89:8bf96f9f649c

Add support for project types.

author	Ludovic Chabant <ludovic@chabant.com>
date	Tue, 01 Dec 2015 22:04:45 -0800
parents	073e63cc0456
children	54355724204b

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
24 bab5f37faa1e More renaming. Ludovic Chabant <ludovic@chabant.com> parents: 22 diff changeset	2 ___ ___ ___ ___
bab5f37faa1e More renaming. Ludovic Chabant <ludovic@chabant.com> parents: 22 diff changeset	3 /\__\ /\ \ /\__\ /\ \
bab5f37faa1e More renaming. Ludovic Chabant <ludovic@chabant.com> parents: 22 diff changeset	4 /:/ _/_ \:\ \ ___ /:/ _/_ \:\ \
bab5f37faa1e More renaming. Ludovic Chabant <ludovic@chabant.com> parents: 22 diff changeset	5 /:/ /\ \ \:\ \ /\__\ /:/ /\__\ \:\ \
bab5f37faa1e More renaming. Ludovic Chabant <ludovic@chabant.com> parents: 22 diff changeset	6 /:/ /::\ \ ___ \:\ \ /:/ / /:/ /:/ _/_ _____\:\ \
bab5f37faa1e More renaming. Ludovic Chabant <ludovic@chabant.com> parents: 22 diff changeset	7 /:/__\/\:\__\ /\ \ \:\__\ /:/__/ /:/_/:/ /\__\ /::::::::\__\
bab5f37faa1e More renaming. Ludovic Chabant <ludovic@chabant.com> parents: 22 diff changeset	8 \:\ \ /:/ / \:\ \ /:/ / /::\ \ \:\/:/ /:/ / \:\~~\~~\/__/
bab5f37faa1e More renaming. Ludovic Chabant <ludovic@chabant.com> parents: 22 diff changeset	9 \:\ /:/ / \:\ /:/ / /:/\:\ \ \::/_/:/ / \:\ \
bab5f37faa1e More renaming. Ludovic Chabant <ludovic@chabant.com> parents: 22 diff changeset	10 \:\/:/ / \:\/:/ / \/__\:\ \ \:\/:/ / \:\ \
bab5f37faa1e More renaming. Ludovic Chabant <ludovic@chabant.com> parents: 22 diff changeset	11 \::/ / \::/ / \:\__\ \::/ / \:\__\
bab5f37faa1e More renaming. Ludovic Chabant <ludovic@chabant.com> parents: 22 diff changeset	12 \/__/ \/__/ \/__/ \/__/ \/__/
bab5f37faa1e More renaming. Ludovic Chabant <ludovic@chabant.com> parents: 22 diff changeset	13 ___ ___ ___
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	14 /\ \ /\__\ /\__\
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	15 ___ /::\ \ /:/ _/_ /:/ _/_
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	16 /\__\ /:/\:\ \ /:/ /\ \ /:/ /\ \
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	17 /:/ / /:/ /::\ \ /:/ /::\ \ /:/ /::\ \
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	18 /:/__/ /:/_/:/\:\__\ /:/__\/\:\__\ /:/_/:/\:\__\
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	19 /::\ \ \:\/:/ \/__/ \:\ \ /:/ / \:\/:/ /:/ /
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	20 /:/\:\ \ \::/__/ \:\ /:/ / \::/ /:/ /
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	21 \/__\:\ \ \:\ \ \:\/:/ / \/_/:/ /
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	22 \:\__\ \:\__\ \::/ / /:/ /
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	23 \/__/ \/__/ \/__/ \/__/
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
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 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
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	62 multiple ctags processes if you save files to fast, or your project is really
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	63 big.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	64
7 49e3cb99ab27 Small edits. Ludovic Chabant <ludovic@chabant.com> parents: 4 diff changeset	65 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	66 "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	67 I set for myself with Gutentags:
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	68
7 49e3cb99ab27 Small edits. Ludovic Chabant <ludovic@chabant.com> parents: 4 diff changeset	69 * 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	70 * Cross-platform: should work on at least Mac and Windows.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	71 * 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	72 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	73 * 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	74 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	75 * 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	76 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	77 classes and functions.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	78 * Automatically create the tag file: you open something from a freshly forked
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	79 project, it should start indexing it automatically, just in Sublime Text or
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	80 Visual Studio or any other IDE.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	81
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	82
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	83 =============================================================================
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	84 2. Commands gutentags-commands
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	85
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	86 gutentags-global-commands
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	87 The following commands are always available, whatever buffer you currently
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	88 have open:
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	89
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	90 :GutentagsGenerate
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	91 :GutentagsGenerate {tagsfile}
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	92 Generates a tag file named {tagsfile}. Tags will be
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	93 generated for all the files in the same directory as
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	94 {tagsfile} and below (i.e. recursive from {tagsfile}'s
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	95 own directory).
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	96
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	97
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	98 gutentags-project-commands
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	99 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	100 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	101 \|gutentags_project_root\| for how Gutentags figures out the project a file
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	102 belongs to. When not 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	103 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	104 following commands and remarks don't apply.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	105
47 7b419abf7fba Add ability to disable Gutentags if a `.notags` file is at the root. Ludovic Chabant <ludovic@chabant.com> parents: 46 diff changeset	106 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	107 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	108 "`.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	109
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	110 The tag file that Gutentags creates and manages will be named after
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	111 \|gutentags_tagfile\|, relative to the project's root directory. When Gutentags
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	112 finds a valid project root, it will prepend the tag file's path to 'tags',
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	113 unless \|gutentags_auto_set_tags\| is set to 0. This is to make sure Vim will use
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	114 that file first.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	115
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	116 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	117 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	118 \|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	119 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	120 \|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	121
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	122 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	123 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	124 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	125 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	126 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	127 have to run \|GutentagsUpdate\| manually.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	128
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	129
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	130 :GutentagsUpdate
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	131 :GutentagsUpdate
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	132 Forces an update of the current tag file with the
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	133 current buffer. If tags are already being generated,
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	134 you will be notified and the command will abort.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	135
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	136 :GutentagsUpdate!
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	137 Like \|GutentagsUpdate\|, but updates the current tags
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	138 file with the whole project instead of just the
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	139 current buffer.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	140
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	141
46 c0f56e4d52bd Make a bunch of advanced commands opt-in only. Ludovic Chabant <ludovic@chabant.com> parents: 43 diff changeset	142 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	143 \|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	144
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	145 :GutentagsToggleEnabled
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	146 :GutentagsToggleEnabled
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	147 Disables and re-enables Gutentags.
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	148 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	149 file when you save a buffer. It will however still
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	150 look for project markers as you open new buffers so
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	151 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	152 Gutentags.
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 GutentagsToggleTrace
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	155 :GutentagsToggleTrace
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	156 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	157 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	158 time Gutentags does something. It can get annoying
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	159 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	160 dismiss those messages, but it can be useful to
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	161 troubleshoot a problem.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	162 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	163 Gutentags redirect the output of the tag generation
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	164 script to a `.log` file in the project root.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	165
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	166 :GutentagsUnlock
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	167 :GutentagsUnlock
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	168 Gutentags uses a `.lock` file to know when tag
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	169 generation is running. If something goes wrong with
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	170 that process, that lock file could be left behind. You
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	171 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	172 project, but you can also run \|:GutentagsUnlock\| so
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	173 that Vim does it for you.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	174 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	175 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	176 Gutentags, or something otherwise wrong or unexpected
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	177 with your system. Please file a bug.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	178
49 70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	179
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	180 =============================================================================
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	181 3. Status Line gutentags-status-line
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	182
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	183 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	184 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	185 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	186
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	187 gutentags#statusline()
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	188 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	189 with the following function: >
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	190 :set statusline+=%{gutentags#statusline()}
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	191
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	192 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	193 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	194 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	195 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	196 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	197
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	198 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	199 "TAGS" by default. You can customize it: >
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	200 :set statusline+=%{gutentags#statusline('[Generating...]')}
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	201
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	202 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	203
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	204
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	205 =============================================================================
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	206 4. Global Settings gutentags-settings
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	207
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	208 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	209 behaviour of Gutentags.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	210
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	211 gutentags_enabled
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	212 g:gutentags_enabled
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	213 Defines whether Gutentags should be enabled. When
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	214 disabled, Gutentags will still scan for project root
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	215 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	216 re-enable Gutentags, you won't have some buffers
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	217 mysteriously working while others (those open last)
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	218 don't.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	219 Defaults to 1.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	220
43 7000d598a2a7 Documentation changes for some options that changed names. Ludovic Chabant <ludovic@chabant.com> parents: 24 diff changeset	221 gutentags_ctags_executable
7000d598a2a7 Documentation changes for some options that changed names. Ludovic Chabant <ludovic@chabant.com> parents: 24 diff changeset	222 g:gutentags_ctags_executable
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	223 Specifies the ctags executable to launch.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	224 Defaults to `ctags`.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	225
68 ca61487b3215 Add docs about ctags executable per filetype marc <marc@lamarciana.com> parents: 60 diff changeset	226 gutentags_ctags_executable_{filetype}
89 8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	227 g:gutentags_ctags_executable_{type}
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	228 Specifies the ctags executable to launch for a project
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	229 of type {type}. See \|gutentags_project_info\| for more
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	230 information.
68 ca61487b3215 Add docs about ctags executable per filetype marc <marc@lamarciana.com> parents: 60 diff changeset	231 Example: >
ca61487b3215 Add docs about ctags executable per filetype marc <marc@lamarciana.com> parents: 60 diff changeset	232 let g:gutentags_ctags_executable_ruby = 'ripper-tags'
ca61487b3215 Add docs about ctags executable per filetype marc <marc@lamarciana.com> parents: 60 diff changeset	233 <
ca61487b3215 Add docs about ctags executable per filetype marc <marc@lamarciana.com> parents: 60 diff changeset	234
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	235 gutentags_tagfile
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	236 g:gutentags_tagfile
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	237 Specifies the name of the tag file to create. This
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	238 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	239 \|gutentags_project_root\| for how Gutentags locates the
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	240 project.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	241 Defaults to `tags`.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	242
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	243 gutentags_project_root
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	244 g:gutentags_project_root
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	245 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	246 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	247 automatically. To do this, it looks for "root markers"
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	248 in the current file's directory and its parent
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	249 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	250 Gutentags will be enabled for the project, and a tags
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	251 file named after \|gutentags_tagfile\| will be created at
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	252 the project root.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	253 Defaults to `[]` (an empty \|List\|).
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	254 A list of default markers will always be appended to
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	255 the user-defined ones: ['.git', '.hg', '.bzr',
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	256 '_darcs'].
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	257
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	258 gutentags_exclude
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	259 g:gutentags_exclude
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	260 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	261 \|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	262 excluded from parsing for the tags generation.
9e768b83d701 Fix missing renames of `gutentags_ctags_executable`. Ludovic Chabant <ludovic@chabant.com> parents: 49 diff changeset	263 Defaults to `[]` (an empty \|List\|). Patterns defined
9e768b83d701 Fix missing renames of `gutentags_ctags_executable`. Ludovic Chabant <ludovic@chabant.com> parents: 49 diff changeset	264 in 'wildignore' will also be given as exclude patterns
9e768b83d701 Fix missing renames of `gutentags_ctags_executable`. Ludovic Chabant <ludovic@chabant.com> parents: 49 diff changeset	265 to the `ctags` executable.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	266
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	267 gutentags_auto_set_tags
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	268 g:gutentags_auto_set_tags
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	269 If set to 1, Gutentags will automatically prepend
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	270 '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	271 current project. See \|gutentags_project_root\| for how
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	272 Gutentags locates the project.
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	273 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	274 this means that whatever tag file it generates may
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	275 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	276 tag files Vim knows about.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	277 Defaults to 1.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	278
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	279 gutentags_generate_on_missing
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	280 g:gutentags_generate_on_missing
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	281 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	282 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	283 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	284 Gutentags locates the project.
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	285 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	286 time the file is saved (if
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	287 \|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	288 \|GutentagsUpdate\| or \|GutentagsGenerate\| is run.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	289 Defaults to 1.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	290
61 735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	291 gutentags_generate_on_new
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	292 g:gutentags_generate_on_new
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	293 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	294 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	295 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	296 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	297 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	298 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	299 repository.
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	300 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	301 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	302 \|gutentags_generate_on_write\|.
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	303 Defaults to 1.
735fce322ae4 Add documentation for `g:gutentags_generate_on_new`. Ludovic Chabant <ludovic@chabant.com> parents: 60 diff changeset	304
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	305 gutentags_generate_on_write
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	306 g:gutentags_generate_on_write
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	307 If set to 1, Gutentags will update the current
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	308 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	309 saved. See \|gutentags_project_root\| for how Gutentags
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	310 locates the project.
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	311 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	312 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	313 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	314 \|GutentagsUpdate\| manually.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	315 Defaults to 1.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	316
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	317 gutentags_background_update
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	318 g:gutentags_background_update
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	319 Specifies whether the process that updates the tags
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	320 file should be run in the background or in the
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	321 foreground. If run in the foreground, Vim will block
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	322 until the process is complete.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	323 Defaults to 1.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	324
22 4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	325 gutentags_cache_dir
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!). Ludovic Chabant <ludovic@chabant.com> parents: 20 diff changeset	326 g:gutentags_cache_dir
20 bd136cb41034 Update documentation. Ludovic Chabant <ludovic@chabant.com> parents: 17 diff changeset	327 Specifies a directory in which to create all the tags
bd136cb41034 Update documentation. Ludovic Chabant <ludovic@chabant.com> parents: 17 diff changeset	328 files, instead of writing them at the root of each
bd136cb41034 Update documentation. Ludovic Chabant <ludovic@chabant.com> parents: 17 diff changeset	329 project. This is handy to keep tags files from
bd136cb41034 Update documentation. Ludovic Chabant <ludovic@chabant.com> parents: 17 diff changeset	330 polluting many directories all across your computer.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	331
85 0424970d81f8 Add a `g:gutentags_resolve_symlinks` option to resolve symlinks at setup time. Ludovic Chabant <ludovic@chabant.com> parents: 74 diff changeset	332 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	333 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	334 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	335 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	336 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	337 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	338 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	339 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	340 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	341 Defaults to 0.
88 073e63cc0456 Add `gutentags_enabled_user_func` callback. Ludovic Chabant <ludovic@chabant.com> parents: 85 diff changeset	342
073e63cc0456 Add `gutentags_enabled_user_func` callback. Ludovic Chabant <ludovic@chabant.com> parents: 85 diff changeset	343 gutentags_enabled_user_func
073e63cc0456 Add `gutentags_enabled_user_func` callback. Ludovic Chabant <ludovic@chabant.com> parents: 85 diff changeset	344 g:gutentags_enabled_user_func
073e63cc0456 Add `gutentags_enabled_user_func` callback. Ludovic Chabant <ludovic@chabant.com> parents: 85 diff changeset	345 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	346 the name of a function that will be called when a file
073e63cc0456 Add `gutentags_enabled_user_func` callback. Ludovic Chabant <ludovic@chabant.com> parents: 85 diff changeset	347 is open in a project. The function gets passed the
073e63cc0456 Add `gutentags_enabled_user_func` callback. Ludovic Chabant <ludovic@chabant.com> parents: 85 diff changeset	348 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	349 be enabled for that file.
073e63cc0456 Add `gutentags_enabled_user_func` callback. Ludovic Chabant <ludovic@chabant.com> parents: 85 diff changeset	350 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	351
46 c0f56e4d52bd Make a bunch of advanced commands opt-in only. Ludovic Chabant <ludovic@chabant.com> parents: 43 diff changeset	352 gutentags_define_advanced_commands
c0f56e4d52bd Make a bunch of advanced commands opt-in only. Ludovic Chabant <ludovic@chabant.com> parents: 43 diff changeset	353 g:gutentags_define_advanced_commands
c0f56e4d52bd Make a bunch of advanced commands opt-in only. Ludovic Chabant <ludovic@chabant.com> parents: 43 diff changeset	354 Defines some advanced commands like
c0f56e4d52bd Make a bunch of advanced commands opt-in only. Ludovic Chabant <ludovic@chabant.com> parents: 43 diff changeset	355 \|GutentagsToggleEnabled\| and \|GutentagsUnlock\|.
c0f56e4d52bd Make a bunch of advanced commands opt-in only. Ludovic Chabant <ludovic@chabant.com> parents: 43 diff changeset	356
89 8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	357 gutentags_project_info
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	358 g:gutentags_project_info
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	359 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	360 project any given file belongs to. This should be
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	361 a list of dictionaries:
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	362
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	363 let g:gutentags_project_info = []
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	364 call add(g:gutentags_project_info, {...})
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	365
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	366 Each dictionary item must contain at least a `type`
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	367 key, indicating the type of project:
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	368
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	369 {"type": "python"}
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	370
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	371 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	372 of the given type.
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	373
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	374 "file": any existing file with this path (relative to
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	375 the project root) will make the current project match
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	376 the given info.
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	377
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	378 "glob": any result found with this glob pattern
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	379 (relative to the project root) will make the current
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	380 project match the given info. See \|glob()\| for more
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	381 information.
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	382
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	383 Gutentags adds by default the following definitions:
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	384
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	385 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	386 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	387
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	388 This means, for example, that you can use
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	389 `g:gutentags_ctags_executable_ruby` out of the box.
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	390 See \|gutentags_ctags_executable_{filetype}\| for more
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	391 information.
8bf96f9f649c Add support for project types. Ludovic Chabant <ludovic@chabant.com> parents: 88 diff changeset	392
0 a3a37124558b Initial commit. Ludovic Chabant <ludovic@chabant.com> parents: diff changeset	393
49 70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	394 =============================================================================
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	395 5. Project Settings gutentags-project-settings
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	396
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	397 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	398 following files present in the project root directory:
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	399
74 cb1cf815052e Fix the documentation about the project settings file. Ludovic Chabant <ludovic@chabant.com> parents: 69 diff changeset	400 gutentags-.gutctags
cb1cf815052e Fix the documentation about the project settings file. Ludovic Chabant <ludovic@chabant.com> parents: 69 diff changeset	401 `.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	402 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	403 documentation for more information).
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	404
74 cb1cf815052e Fix the documentation about the project settings file. Ludovic Chabant <ludovic@chabant.com> parents: 69 diff changeset	405 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	406 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	407 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	408 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	409 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	410 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	411 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	412
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	413 gutentags-.notags
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	414 `.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	415 project.
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	416
70423c2202c5 Ctags options files changes Ludovic Chabant <ludovic@chabant.com> parents: 47 diff changeset	417
0 a3a37124558b Initial commit. Ludovic Chabant <ludovic@chabant.com> parents: diff changeset	418 vim:tw=78:et:ft=help:norl:

Mercurial > vim-gutentags

annotate doc/gutentags.txt @ 89:8bf96f9f649c