vim-gutentags: doc/autotags.txt annotate

annotate doc/autotags.txt @ 20:bd136cb41034

Update documentation.

author	Ludovic Chabant <ludovic@chabant.com>
date	Sun, 31 Aug 2014 21:47:39 -0700
parents	b73466268844
children

rev	line source
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	1 autotags.txt Automatic ctags management for VIM
0 a3a37124558b Initial commit. Ludovic Chabant <ludovic@chabant.com> parents: diff changeset	2
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	3 ___ ___ ___
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	4 /\ \ /\ \ /\ \
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	5 /::\ \ \:\ \ ___ /::\ \
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	6 /:/\:\ \ \:\ \ /\__\ /:/\:\ \
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	7 /:/ /::\ \ ___ \:\ \ /:/ / /:/ \:\ \
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	8 /:/_/:/\:\__\ /\ \ \:\__\ /:/__/ /:/__/ \:\__\
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	9 \:\/:/ \/__/ \:\ \ /:/ / /::\ \ \:\ \ /:/ /
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	10 \::/__/ \:\ /:/ / /:/\:\ \ \:\ /:/ /
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	11 \:\ \ \:\/:/ / \/__\:\ \ \:\/:/ /
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	12 \:\__\ \::/ / \:\__\ \::/ /
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	13 \/__/ \/__/ _\/__/ \/__/
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
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	26 AUTOTAGS REFERENCE MANUAL
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
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	29 autotags
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	30
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	31 1. Introduction \|autotags-intro\|
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	32 2. Commands \|autotags-commands\|
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	33 3. Status Line \|autotags-status-line\|
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	34 4. Global Settings \|autotags-settings\|
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	35
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 1. Introduction autotags-intro
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	38
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	39 Autotags 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	40 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	41 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	42 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	43
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	44 In order to generate tag files, Autotags will have to figure out what's in
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	45 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	46 SCM folders (.git, .hg, etc.), any custom tags you define (with
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	47 \|autotags_project_root\|), and even things you may have defined already with
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	48 other plugins, like CtrlP.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	49
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	50 If the current file you're editing is found to be in such a project, Autotags
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	51 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	52 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	53 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	54 file.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	55
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	56 Usually, ctags can only append tags to an existing tag file, so Autotags
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	57 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	58 always consistent with the source code.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	59
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	60 Also, Autotags is clever enough to not stumble upon itself by triggering
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	61 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	62 big.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	63
7 49e3cb99ab27 Small edits. Ludovic Chabant <ludovic@chabant.com> parents: 4 diff changeset	64 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	65 "vim-automatic-ctags", etc.). They all fail on one or more of the requirements
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	66 I set for myself with Autotags:
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	67
7 49e3cb99ab27 Small edits. Ludovic Chabant <ludovic@chabant.com> parents: 4 diff changeset	68 * 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	69 * Cross-platform: should work on at least Mac and Windows.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	70 * 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	71 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	72 * 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	73 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	74 * 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	75 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	76 classes and functions.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	77 * 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	78 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	79 Visual Studio or any other IDE.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	80
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 2. Commands autotags-commands
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	84
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	85 autotags-global-commands
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	86 The following commands are always available, whatever buffer you currently
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	87 have open:
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	88
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	89 :AutotagsGenerate
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	90 :AutotagsGenerate {tagsfile}
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	91 Generates a tag file named {tagsfile}. Tags will be
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	92 generated for all the files in the same directory as
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	93 {tagsfile} and below (i.e. recursive from {tagsfile}'s
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	94 own directory).
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	95
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 autotags-project-commands
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	98 The following commands are only available in buffers that have been found to
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	99 belong to a project that should be managed by Autotags. See
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	100 \|autotags_project_root\| for how Autotags figures out the project a file
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	101 belongs to. When not project is found (i.e. the file is not under any of the
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	102 known project markers), Autotags is disabled for that buffer, and the
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	103 following commands and remarks don't apply.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	104
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	105 The tag file that Autotags creates and manages will be named after
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	106 \|autotags_tagfile\|, relative to the project's root directory. When Autotags
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	107 finds a valid project root, it will prepend the tag file's path to 'tags',
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	108 unless \|autotags_auto_set_tags\| is set to 0. This is to make sure Vim will use
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	109 that file first.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	110
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	111 If a file managed by Autotags is opened and no tag file already exists,
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	112 Autotags will start generating it right away in the background, unless
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	113 \|autotags_generate_on_missing\| is set to 0. If you have a large project, you
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	114 may want to know when Autotags is generating tags: see
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	115 \|autotags-status-line\| to display an indicator in your status line.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	116
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	117 When a file managed by Autotags is saved, the tag file will be incrementally
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	118 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	119 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	120 makes the tag file 100% consistent with the latest changes. This doesn't
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	121 happen however if \|autotags_generate_on_write\| is set to 0, in which case you
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	122 have to run \|AutotagsUpdate\| manually.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	123
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	124
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	125 :AutotagsUpdate
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	126 :AutotagsUpdate
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	127 Forces an update of the current tag file with the
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	128 current buffer. If tags are already being generated,
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	129 you will be notified and the command will abort.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	130
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	131 :AutotagsUpdate!
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	132 Like \|AutotagsUpdate\|, but updates the current tags
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	133 file with the whole project instead of just the
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	134 current buffer.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	135
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	136
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	137 Some debugging/troubleshooting commands are also available.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	138
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	139 :AutotagsToggleEnabled
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	140 :AutotagsToggleEnabled
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	141 Disables and re-enables Autotags.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	142 When Autotags is disabled, it won't update your tag
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	143 file when you save a buffer. It will however still
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	144 look for project markers as you open new buffers so
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	145 that they can start working again when you re-enable
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	146 Autotags.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	147
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	148 AutotagsToggleTrace
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	149 :AutotagsToggleTrace
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	150 If you want to keep an eye on what Autotags is doing,
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	151 you can enable tracing. This will show messages every
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	152 time Autotags does something. It can get annoying
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	153 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	154 dismiss those messages, but it can be useful to
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	155 troubleshoot a problem.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	156 In addition to messages in Vim, it will also make
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	157 Autotags redirect the output of the tag generation
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	158 script to a `.log` file in the project root.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	159
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	160 :AutotagsUnlock
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	161 :AutotagsUnlock
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	162 Autotags uses a `.lock` file to know when tag
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	163 generation is running. If something goes wrong with
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	164 that process, that lock file could be left behind. You
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	165 could just remove it manually from the root of your
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	166 project, but you can also run \|:AutotagsUnlock\| so
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	167 that Vim does it for you.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	168 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	169 couple times ever, there's probably a bug with
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	170 Autotags, or something otherwise wrong or unexpected
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	171 with your system. Please file a bug.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	172
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	173 =============================================================================
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	174 3. Status Line autotags-status-line
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	175
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	176 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	177 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	178 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	179
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	180 autotags#statusline()
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	181 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	182 with the following function: >
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	183 :set statusline+=%{autotags#statusline()}
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	184
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	185 This won't print anything unless Autotags figures that `ctags` is running in
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	186 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	187 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	188 the `.lock` file can sometimes be left around incorrectly by the background
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	189 process, and you may need to clean it up. See \|:AutotagsUnlock\|.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	190
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	191 When Autotags thinks `ctags` is still running, it will print the string
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	192 "TAGS" by default. You can customize it: >
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	193 :set statusline+=%{autotags#statusline('[Generating...]')}
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	194
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	195 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	196
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	197
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	198 =============================================================================
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	199 4. Global Settings autotags-settings
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	200
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	201 The following settings can be defined in your \|vimrc\| to change the default
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	202 behaviour of Autotags.
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 autotags_enabled
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	205 g:autotags_enabled
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	206 Defines whether Autotags should be enabled. When
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	207 disabled, Autotags will still scan for project root
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	208 markers when opening buffers. This is so that when you
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	209 re-enable Autotags, you won't have some buffers
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	210 mysteriously working while others (those open last)
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	211 don't.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	212 Defaults to 1.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	213
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	214 autotags_executable
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	215 g:autotags_executable
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	216 Specifies the ctags executable to launch.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	217 Defaults to `ctags`.
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 autotags_tagfile
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	220 g:autotags_tagfile
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	221 Specifies the name of the tag file to create. This
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	222 will be appended to the project's root. See
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	223 \|autotags_project_root\| for how Autotags locates the
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	224 project.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	225 Defaults to `tags`.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	226
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	227 autotags_project_root
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	228 g:autotags_project_root
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	229 When a buffer is loaded, Autotags will figure out if
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	230 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	231 automatically. To do this, it looks for "root markers"
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	232 in the current file's directory and its parent
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	233 directories. If it finds any of those markers,
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	234 Autotags will be enabled for the project, and a tags
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	235 file named after \|autotags_tagfile\| will be created at
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	236 the project root.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	237 Defaults to `[]` (an empty \|List\|).
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	238 A list of default markers will always be appended to
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	239 the user-defined ones: ['.git', '.hg', '.bzr',
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	240 '_darcs'].
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	241
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	242 autotags_exclude
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	243 g:autotags_exclude
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	244 A list of file patterns to pass to the
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	245 \|autotags_executable\| so that they will be excluded
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	246 from parsing for the tags generation.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	247 Defaults to `[]` (an empty \|List\|).
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	248 Patterns defined in 'wildignore' will also be given as
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	249 exclude patterns to the `ctags` executable.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	250
17 b73466268844 Updated documentation. Ludovic Chabant <ludovic@chabant.com> parents: 7 diff changeset	251 autotags_options_file
b73466268844 Updated documentation. Ludovic Chabant <ludovic@chabant.com> parents: 7 diff changeset	252 g:autotags_options_file
b73466268844 Updated documentation. Ludovic Chabant <ludovic@chabant.com> parents: 7 diff changeset	253 The path to an options file that will be passed to
b73466268844 Updated documentation. Ludovic Chabant <ludovic@chabant.com> parents: 7 diff changeset	254 the `ctags` executable with the `--options` option.
b73466268844 Updated documentation. Ludovic Chabant <ludovic@chabant.com> parents: 7 diff changeset	255 In general you can put options in a `$HOME/.ctags`
b73466268844 Updated documentation. Ludovic Chabant <ludovic@chabant.com> parents: 7 diff changeset	256 file, but this lets you specify a custom file
b73466268844 Updated documentation. Ludovic Chabant <ludovic@chabant.com> parents: 7 diff changeset	257 specifically for Vim/Autotags.
b73466268844 Updated documentation. Ludovic Chabant <ludovic@chabant.com> parents: 7 diff changeset	258
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	259 autotags_auto_set_tags
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	260 g:autotags_auto_set_tags
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	261 If set to 1, Autotags will automatically prepend
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	262 'tags' with the exact path to the tag file for the
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	263 current project. See \|autotags_project_root\| for how
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	264 Autotags locates the project.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	265 When set to 0, Autotags doesn't change 'tags', and
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	266 this means that whatever tag file it generates may
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	267 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	268 tag files Vim knows about.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	269 Defaults to 1.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	270
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	271 autotags_generate_on_missing
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	272 g:autotags_generate_on_missing
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	273 If set to 1, Autotags will start generating an initial
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	274 tag file if a file is open in a project where no tags
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	275 file is found. See \|autotags_project_root\| for how
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	276 Autotags locates the project.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	277 When set to 0, Autotags will only generate the first
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	278 time the file is saved (if
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	279 \|autotags_generate_on_write\| is set to 1), or when
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	280 \|AutotagsUpdate\| or \|AutotagsGenerate\| is run.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	281 Defaults to 1.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	282
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	283 autotags_generate_on_write
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	284 g:autotags_generate_on_write
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	285 If set to 1, Autotags will update the current
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	286 project's tag file when a file inside that project is
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	287 saved. See \|autotags_project_root\| for how Autotags
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	288 locates the project.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	289 When set to 0, Autotags won't do anything on save.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	290 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	291 the latest changes, and you will have to run
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	292 \|AutotagsUpdate\| manually.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	293 Defaults to 1.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	294
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	295 autotags_background_update
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	296 g:autotags_background_update
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	297 Specifies whether the process that updates the tags
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	298 file should be run in the background or in the
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	299 foreground. If run in the foreground, Vim will block
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	300 until the process is complete.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	301 Defaults to 1.
512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	302
20 bd136cb41034 Update documentation. Ludovic Chabant <ludovic@chabant.com> parents: 17 diff changeset	303 autotags_cache_dir
bd136cb41034 Update documentation. Ludovic Chabant <ludovic@chabant.com> parents: 17 diff changeset	304 g:autotags_cache_dir
bd136cb41034 Update documentation. Ludovic Chabant <ludovic@chabant.com> parents: 17 diff changeset	305 Specifies a directory in which to create all the tags
bd136cb41034 Update documentation. Ludovic Chabant <ludovic@chabant.com> parents: 17 diff changeset	306 files, instead of writing them at the root of each
bd136cb41034 Update documentation. Ludovic Chabant <ludovic@chabant.com> parents: 17 diff changeset	307 project. This is handy to keep tags files from
bd136cb41034 Update documentation. Ludovic Chabant <ludovic@chabant.com> parents: 17 diff changeset	308 polluting many directories all across your computer.
4 512eaa56c7db First pass at documentation. Ludovic Chabant <ludovic@chabant.com> parents: 0 diff changeset	309
0 a3a37124558b Initial commit. Ludovic Chabant <ludovic@chabant.com> parents: diff changeset	310
a3a37124558b Initial commit. Ludovic Chabant <ludovic@chabant.com> parents: diff changeset	311 vim:tw=78:et:ft=help:norl:

Mercurial > vim-gutentags

annotate doc/autotags.txt @ 20:bd136cb41034