Mercurial > vim-gutentags
view doc/gutentags.txt @ 165:cbc1ebe23ef1
Rename all ctags-related options to have "ctags" in their name.
Add some stuff to handle old options so it doesn't break everybody.
| author | Ludovic Chabant <ludovic@chabant.com> |
|---|---|
| date | Sat, 18 Feb 2017 18:21:35 -0800 |
| parents | f915393ff68d |
| children | 2489b4b54d5c |
line wrap: on
line source
*gutentags.txt* Automatic ctags management for VIM ___ ___ ___ ___ /\__\ /\ \ /\__\ /\ \ /:/ _/_ \:\ \ ___ /:/ _/_ \:\ \ /:/ /\ \ \:\ \ /\__\ /:/ /\__\ \:\ \ /:/ /::\ \ ___ \:\ \ /:/ / /:/ /:/ _/_ _____\:\ \ /:/__\/\:\__\ /\ \ \:\__\ /:/__/ /:/_/:/ /\__\ /::::::::\__\ \:\ \ /:/ / \:\ \ /:/ / /::\ \ \:\/:/ /:/ / \:\~~\~~\/__/ \:\ /:/ / \:\ /:/ / /:/\:\ \ \::/_/:/ / \:\ \ \:\/:/ / \:\/:/ / \/__\:\ \ \:\/:/ / \:\ \ \::/ / \::/ / \:\__\ \::/ / \:\__\ \/__/ \/__/ \/__/ \/__/ \/__/ ___ ___ ___ /\ \ /\__\ /\__\ ___ /::\ \ /:/ _/_ /:/ _/_ /\__\ /:/\:\ \ /:/ /\ \ /:/ /\ \ /:/ / /:/ /::\ \ /:/ /::\ \ /:/ /::\ \ /:/__/ /:/_/:/\:\__\ /:/__\/\:\__\ /:/_/:/\:\__\ /::\ \ \:\/:/ \/__/ \:\ \ /:/ / \:\/:/ /:/ / /:/\:\ \ \::/__/ \:\ /:/ / \::/ /:/ / \/__\:\ \ \:\ \ \:\/:/ / \/_/:/ / \:\__\ \:\__\ \::/ / /:/ / \/__/ \/__/ \/__/ \/__/ GUTENTAGS REFERENCE MANUAL by Ludovic Chabant *gutentags* 1. Introduction |gutentags-intro| 2. Commands |gutentags-commands| 3. Status Line |gutentags-status-line| 4. Global Settings |gutentags-settings| 5. Project Settings |gutentags-project-settings| ============================================================================= 1. Introduction *gutentags-intro* Gutentags is a plugin that takes care of the much needed management of tags files in Vim. It will (re)generate tag files as you work while staying completely out of your way. It will even do its best to keep those tag files out of your way too. It has no dependencies and just works. In order to generate tag files, Gutentags will have to figure out what's in your project. To do this, it will locate well-known project root markers like SCM folders (.git, .hg, etc.), any custom tags you define (with |gutentags_project_root|), and even things you may have defined already with other plugins, like CtrlP. If the current file you're editing is found to be in such a project, Gutentags will make sure the tag file for that project is up to date. Then, as you work in files in that project, it will partially re-generate the tag file. Every time you save, it will silently, in the background, update the tags for that file. Usually, `ctags` can only append tags to an existing tag file, so Gutentags removes the tags for the current file first, to make sure the tag file is always consistent with the source code. Also, Gutentags is clever enough to not stumble upon itself by triggering multiple ctags processes if you save files too fast, or if your project is really big. 1.1 Requirements *gutentags-ctags-requirements* If you're using the `ctags` modules (which is the default and only working one at this point, really), you will need a `tags` generator that supports the following arguments: * `-f` (to specify the output file) * `--append` (to append to an existing file while keeping it sorted) * `--exclude` (to exclude file patterns) * `--options` (to specify an options file) This means you probably want Exhuberant Ctags or Universal Ctags. The basic old BSD Ctags WON'T WORK. Other language-specific versions may or may not work. Check with their help or man page. 1.2 Similar Plugins *gutentags-similar-plugins* There are some similar Vim plugins out there ("vim-tags", "vim-autotag", "vim-automatic-ctags", etc.). They all fail on one or more of the requirements I set for myself with Gutentags: * No other dependency than running Vim: no Python, Ruby, or whatever. * Cross-platform: should work on at least Mac and Windows. * Incremental tags generation: don't re-generate the whole project all the time. This may be fine for small projects, but it doesn't scale. * External process management: if the ctags process is taking a long time, don't run another one because I saved the file again. * Keep the tag file consistent: don't just append the current file's tags to the tag file, otherwise you will still "see" tags for deleted or renamed classes and functions. * Automatically create the tag file: you open something from a freshly forked project, it should start indexing it automatically, just like in Sublime Text or Visual Studio or any other IDE. ============================================================================= 2. Commands *gutentags-commands* *gutentags-project-commands* The following commands are only available in buffers that have been found to belong to a project that should be managed by Gutentags. See |gutentags_project_root| for how Gutentags figures out the project a file belongs to. When no project is found (i.e. the file is not under any of the known project markers), Gutentags is disabled for that buffer, and the following commands and remarks don't apply. If you want to force-disable Gutentags for a given project even though it does match one of the items in |gutentags_project_root|, create a file named "`.notags`" at the root of the project. The tag file that Gutentags creates and manages will be named after |gutentags_ctags_tagfile|, relative to the project's root directory. When Gutentags finds a valid project root, it will prepend the tag file's path to 'tags', unless |gutentags_ctags_auto_set_tags| is set to 0. This is to make sure Vim will use that file first. If a file managed by Gutentags is opened and no tag file already exists, Gutentags will start generating it right away in the background, unless |gutentags_generate_on_missing| is set to 0. If you have a large project, you may want to know when Gutentags is generating tags: see |gutentags-status-line| to display an indicator in your status line. When a file managed by Gutentags is saved, the tag file will be incrementally updated, i.e. references to the recently saved file are removed, and that file is re-parsed for tags, with the result being merged into the tag file. This makes the tag file 100% consistent with the latest changes. This doesn't happen however if |gutentags_generate_on_write| is set to 0, in which case you have to run |GutentagsUpdate| manually. *:GutentagsUpdate* :GutentagsUpdate Forces an update of the current tag file with the current buffer. If tags are already being generated, you will be notified and the command will abort. :GutentagsUpdate! Like |GutentagsUpdate|, but updates the current tags file with the whole project instead of just the current buffer. Some debugging/troubleshooting commands are also available if the |gutentags_define_advanced_commands| global setting is set to 1. *:GutentagsToggleEnabled* :GutentagsToggleEnabled Disables and re-enables Gutentags. When Gutentags is disabled, it won't update your tag file when you save a buffer. It will however still look for project markers as you open new buffers so that they can start working again when you re-enable Gutentags. *GutentagsToggleTrace* :GutentagsToggleTrace If you want to keep an eye on what Gutentags is doing, you can enable tracing. This will show messages every time Gutentags does something. It can get annoying quickly, since it will require you to press a key to dismiss those messages, but it can be useful to troubleshoot a problem. In addition to messages in Vim, it will also make Gutentags redirect the output of the tag generation script to a `.log` file in the project root. *:GutentagsUnlock* :GutentagsUnlock Gutentags uses a `.lock` file to know when tag generation is running. If something goes wrong with that process, that lock file could be left behind. You could just remove it manually from the root of your project, but you can also run |:GutentagsUnlock| so that Vim does it for you. If you find that you need to use this more than a couple times ever, there's probably a bug with Gutentags, or something otherwise wrong or unexpected with your system. Please file a bug. ============================================================================= 3. Status Line *gutentags-status-line* Tag file generation can take a while if you're working on a project big enough. In that case, you may want to know when `ctags` is running, so you have a heads up if some of the tags aren't recognized yet. *gutentags#statusline()* You can display and indicator of tag generation progress in your |status-line| with the following function: > :set statusline+=%{gutentags#statusline()} This won't print anything unless Gutentags figures that `ctags` is running in the background. This is done by checking a `.lock` file next to the tag file, but there's also some optimization before that to not slow down Vim. Note that the `.lock` file can sometimes be left around incorrectly by the background process, and you may need to clean it up. See |:GutentagsUnlock|. When Gutentags thinks `ctags` is still running, it will print the string "TAGS" by default. You can customize it: > :set statusline+=%{gutentags#statusline('[Generating...]')} This will print the string "[Generating...]" when tags are being generated. ============================================================================= 4. Global Settings *gutentags-settings* The following settings can be defined in your |vimrc| to change the default behaviour of Gutentags. *gutentags_enabled* g:gutentags_enabled Defines whether Gutentags should be enabled. When disabled, Gutentags will still scan for project root markers when opening buffers. This is so that when you re-enable Gutentags, you won't have some buffers mysteriously working while others (those open last) don't. Defaults to 1. *gutentags_dont_load* g:gutentags_dont_load Prevents Gutentags from loading at all on Vim startup. The difference between this and |gutentags_enabled| is that |gutentags_enabled| can be turned on and off in the same Vim session -- Gutentags as a plugin stays loaded and will keep track of what happened while it was disabled. However, |gutentags_dont_load| only works on Vim startup and will prevent Gutentags from loading at all, as if it wasn't there. *gutentags_ctags_executable* g:gutentags_ctags_executable Specifies the ctags executable to launch. Defaults to `ctags`. *gutentags_ctags_executable_{filetype}* g:gutentags_ctags_executable_{type} Specifies the ctags executable to launch for a project of type {type}. See |gutentags_project_info| for more information. IMPORTANT: please see |gutentags-ctags-requirements|. Example: > let g:gutentags_ctags_executable_ruby = 'foobar' < *gutentags_ctags_tagfile* g:gutentags_ctags_tagfile Specifies the name of the tag file to create. This will be appended to the project's root. See |gutentags_project_root| for how Gutentags locates the project. Defaults to `tags`. *gutentags_project_root* g:gutentags_project_root When a buffer is loaded, Gutentags will figure out if it's part of a project that should have tags managed automatically. To do this, it looks for "root markers" in the current file's directory and its parent directories. If it finds any of those markers, Gutentags will be enabled for the project, and a tags file named after |gutentags_ctags_tagfile| will be created at the project root. Defaults to `[]` (an empty |List|). A list of default markers will be appended to the user-defined ones unless |gutentags_add_default_project_roots| is set to 0. *gutentags_add_default_project_roots* g:gutentags_add_default_project_roots Defines whether Gutentags should always define some default project roots (see |gutentags_project_root|). This can be useful to prevent unnecessary disk access when Gutentags searches for a project root. The default markers are: `['.git', '.hg', '.bzr', '_darcs', '_darcs', '_FOSSIL_', '.fslckout']` *gutentags_exclude_project_root* g:gutentags_exclude_project_root A list of project roots to generally ignore. If a file is opened inside one of those projects, Gutentags won't be activated. This is similar to placing a `.notags` file in the root of those projects, but can be useful when you don't want to, or can't, place such a file there. Defaults to `['/usr/local']`, which is the folder where Homebrew is known to create a Git directory by default on MacOS. *gutentags_project_root_finder* g:gutentags_project_root_finder When a buffer is loaded, Gutentags uses a default (internal) implementation to find that file's project's root directory, using settings like |g:gutentags_project_root|. When you specify |g:gutentags_project_root_finder|, you can tell Gutentags to use a custom implementation, such as `vim-projectroot`. The value of this setting must be the name of a function that takes a single string argument (the path to the current buffer's file) and returns a string value (the project's root directory). Defaults to `''`. Note: when set, the called implementation will most likely ignore |g:gutentags_project_root|. *gutentags_ctags_exclude* g:gutentags_ctags_exclude A list of file patterns to pass to the |gutentags_ctags_executable| so that they will be excluded from parsing for the tags generation. See also |gutentags_ctags_exclude_wildignore|. Defaults to `[]` (an empty |List|). *gutentags_ctags_exclude_wildignore* g:gutentags_ctags_exclude_wildignore When 1, Gutentags will automatically pass your 'wildignore' file patterns to the |gutentags_ctags_executable| so that they are ignored. Set also |gutentags_ctags_exclude| to pass custom patterns. Defaults to 1. *gutentags_ctags_auto_set_tags* g:gutentags_ctags_auto_set_tags If set to 1, Gutentags will automatically prepend 'tags' with the exact path to the tag file for the current project. See |gutentags_project_root| for how Gutentags locates the project. When set to 0, Gutentags doesn't change 'tags', and this means that whatever tag file it generates may not be picked up by Vim. See |tagfiles()| to know what tag files Vim knows about. Defaults to 1. *gutentags_generate_on_missing* g:gutentags_generate_on_missing If set to 1, Gutentags will start generating an initial tag file if a file is open in a project where no tags file is found. See |gutentags_project_root| for how Gutentags locates the project. When set to 0, Gutentags will only generate the first time the file is saved (if |gutentags_generate_on_write| is set to 1), or when |GutentagsUpdate| or |GutentagsGenerate| is run. Defaults to 1. *gutentags_generate_on_new* g:gutentags_generate_on_new If set to 1, Gutentags will start generating the tag file when a new project is open. A new project is considered open when a buffer is created for a file whose corresponding tag file has not been "seen" yet in the current Vim session -- which pretty much means when you open the first file in a given source control repository. When set to 0, Gutentags won't do anything special. See also |gutentags_generate_on_missing| and |gutentags_generate_on_write|. Defaults to 1. *gutentags_generate_on_write* g:gutentags_generate_on_write If set to 1, Gutentags will update the current project's tag file when a file inside that project is saved. See |gutentags_project_root| for how Gutentags locates the project. When set to 0, Gutentags won't do anything on save. This means that the project's tag file won't reflect the latest changes, and you will have to run |GutentagsUpdate| manually. Defaults to 1. *gutentags_background_update* g:gutentags_background_update Specifies whether the process that updates the tags file should be run in the background or in the foreground. If run in the foreground, Vim will block until the process is complete. Defaults to 1. *gutentags_cache_dir* g:gutentags_cache_dir Specifies a directory in which to create all the tags files, instead of writing them at the root of each project. This is handy to keep tags files from polluting many directories all across your computer. *gutentags_resolve_symlinks* g:gutentags_resolve_symlinks When set to 1, Gutentags will resolve any symlinks in the current buffer's path in order to find the project it belongs to. This is what you want if you're editing a symlink located outside of the project, and it points to a file inside the project. However, this is maybe not what you want if the symlink itself is part of the project. Defaults to 0. *gutentags_init_user_func* g:gutentags_init_user_func When set to a non-empty string, it is expected to be the name of a function that will be called when a file is opened in a project. The function gets passed the path of the file and if it returns 0, Gutentags won't be enabled for that file. You can use this to manually set buffer-local settings: * `b:gutentags_ctags_tagfile` (see |gutentags_ctags_tagfile|). This setting was previously called `gutentags_enabled_user_func`. The old setting is still used as a fallback. Defaults to "". *gutentags_define_advanced_commands* g:gutentags_define_advanced_commands Defines some advanced commands like |GutentagsToggleEnabled| and |GutentagsUnlock|. *gutentags_project_info* g:gutentags_project_info Defines ways for Gutentags to figure out what kind of project any given file belongs to. This should be a list of dictionaries: let g:gutentags_project_info = [] call add(g:gutentags_project_info, {...}) Each dictionary item must contain at least a `type` key, indicating the type of project: {"type": "python"} Other items will be used to figure out if a project is of the given type. "file": any existing file with this path (relative to the project root) will make the current project match the given info. "glob": any result found with this glob pattern (relative to the project root) will make the current project match the given info. See |glob()| for more information. Gutentags adds by default the following definitions: call add(g:gutentags_project_info, {'type': 'python', 'file': 'setup.py'}) call add(g:gutentags_project_info, {'type': 'ruby', 'file': 'Gemfile'}) This means, for example, that you can use `g:gutentags_ctags_executable_ruby` out of the box. See |gutentags_ctags_executable_{filetype}| for more information. *gutentags_file_list_command* g:gutentags_file_list_command Specifies command(s) to use to list files for which tags should be generated, instead of recursively examining all files within the project root. When invoked, file list commands will execute in the project root directory. This setting is useful in projects using source control to restrict tag generation to only files tracked in the repository. This variable may be set in one of two ways. If set as a |String|, the specified command will be used to list files for all projects. For example: > let g:gutentags_file_list_command = 'find . -type f' < If set as a |Dictionary|, this variable should be set as a mapping of project root markers to the desired file list command for that root marker. (See |gutentags_project_root| for how Gutentags uses root markerts to locate the project.) For example: > let g:gutentags_file_list_command = { \ 'markers': { \ '.git': 'git ls-files', \ '.hg': 'hg files', \ }, \ } < Note: If a custom ctags executable is specified, it must support the '-L' command line option in order to read the list of files to be examined. ============================================================================= 5. Project Settings *gutentags-project-settings* Gutentags can be customized to some extent on a per-project basis with the following files present in the project root directory: *gutentags-.gutctags* `.gutctags`: if this file exists, Ctags will be told to load additional command-line parameters by reading it line by line (see the Ctags documentation for more information). Note that for complex reasons, Gutentags can't run `ctags` from the project root if you're using |gutentags_cache_dir|, so if the `.gutctags` file exists, it will be pre-processed in order to make all `--exclude=` clauses into absolute paths (by prepending the project root). The resulting file will be saved into the cache directory, and passed to `ctags` via the `--options=` parameter. If you're _not_ using |gutentags_cache_dir|, the `.gutctags` file is _not_ pre-processed, and is passed as-is via the `--options=` parameter. *gutentags-.notags* `.notags`: if this file exists, Gutentags will be disabled completely for that project. vim:tw=78:et:ft=help:norl: