Mercurial > vim-gutentags
changeset 22:4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
| author | Ludovic Chabant <ludovic@chabant.com> |
|---|---|
| date | Tue, 02 Sep 2014 10:31:09 -0700 |
| parents | 1f6ecd4258d7 |
| children | ba9a9ebdd345 |
| files | README.md doc/autotags.txt doc/gutentags.txt plugin/autotags.vim plugin/gutentags.vim |
| diffstat | 5 files changed, 826 insertions(+), 826 deletions(-) [+] |
line wrap: on
line diff
--- a/README.md Mon Sep 01 08:48:48 2014 -0700 +++ b/README.md Tue Sep 02 10:31:09 2014 -0700 @@ -1,43 +1,43 @@ -# Autotags +# Gutentags -Autotags is a plugin that takes care of the much needed management of tags +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. ## How? -Install Autotags like any other Vim plugin. I recommend something like +Install Gutentags like any other Vim plugin. I recommend something like [Pathogen][], so you can go: cd ~/.vim/bundle - hg clone https://bitbucket.org/ludovicchabant/vim-autotags + hg clone https://bitbucket.org/ludovicchabant/vim-gutentags Then you only need to do a `:call pathogen#helptags()` to generate the documentation tags (how ironic, eh?) and you can access Autotag's help pages -with `help autotags`. +with `help gutentags`. ## What? -In order to generate tag files, Autotags will have to figure out what's in +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 -`autotags_project_root`), and even things you may have defined already 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, Autotags +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 Autotags +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, Autotags is clever enough to not stumble upon itself by triggering +Also, Gutentags is clever enough to not stumble upon itself by triggering multiple ctags processes if you save files to fast, or your project is really big. @@ -46,7 +46,7 @@ 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 Autotags: +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. @@ -61,7 +61,7 @@ project, it should start indexing it automatically, just like in Sublime Text or Visual Studio or any other IDE. -I hope Autotags will bring you as much closure as me regarding tag files. I know +I hope Gutentags will bring you as much closure as me regarding tag files. I know I don't want to have to think about it, and probably neither do you.
--- a/doc/autotags.txt Mon Sep 01 08:48:48 2014 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,311 +0,0 @@ -*autotags.txt* Automatic ctags management for VIM - - ___ ___ ___ - /\ \ /\ \ /\ \ - /::\ \ \:\ \ ___ /::\ \ - /:/\:\ \ \:\ \ /\__\ /:/\:\ \ - /:/ /::\ \ ___ \:\ \ /:/ / /:/ \:\ \ - /:/_/:/\:\__\ /\ \ \:\__\ /:/__/ /:/__/ \:\__\ - \:\/:/ \/__/ \:\ \ /:/ / /::\ \ \:\ \ /:/ / - \::/__/ \:\ /:/ / /:/\:\ \ \:\ /:/ / - \:\ \ \:\/:/ / \/__\:\ \ \:\/:/ / - \:\__\ \::/ / \:\__\ \::/ / - \/__/ \/__/ _\/__/ \/__/ - /\ \ /\__\ /\__\ - ___ /::\ \ /:/ _/_ /:/ _/_ - /\__\ /:/\:\ \ /:/ /\ \ /:/ /\ \ - /:/ / /:/ /::\ \ /:/ /::\ \ /:/ /::\ \ - /:/__/ /:/_/:/\:\__\ /:/__\/\:\__\ /:/_/:/\:\__\ - /::\ \ \:\/:/ \/__/ \:\ \ /:/ / \:\/:/ /:/ / - /:/\:\ \ \::/__/ \:\ /:/ / \::/ /:/ / - \/__\:\ \ \:\ \ \:\/:/ / \/_/:/ / - \:\__\ \:\__\ \::/ / /:/ / - \/__/ \/__/ \/__/ \/__/ - - - AUTOTAGS REFERENCE MANUAL - by Ludovic Chabant - - *autotags* - -1. Introduction |autotags-intro| -2. Commands |autotags-commands| -3. Status Line |autotags-status-line| -4. Global Settings |autotags-settings| - -============================================================================= -1. Introduction *autotags-intro* - -Autotags 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, Autotags 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 -|autotags_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, Autotags -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 Autotags -removes the tags for the current file first, to make sure the tag file is -always consistent with the source code. - -Also, Autotags is clever enough to not stumble upon itself by triggering -multiple ctags processes if you save files to fast, or your project is really -big. - -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 Autotags: - -* 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 in Sublime Text or - Visual Studio or any other IDE. - - -============================================================================= -2. Commands *autotags-commands* - - *autotags-global-commands* -The following commands are always available, whatever buffer you currently -have open: - - *:AutotagsGenerate* -:AutotagsGenerate {tagsfile} - Generates a tag file named {tagsfile}. Tags will be - generated for all the files in the same directory as - {tagsfile} and below (i.e. recursive from {tagsfile}'s - own directory). - - - *autotags-project-commands* -The following commands are only available in buffers that have been found to -belong to a project that should be managed by Autotags. See -|autotags_project_root| for how Autotags figures out the project a file -belongs to. When not project is found (i.e. the file is not under any of the -known project markers), Autotags is disabled for that buffer, and the -following commands and remarks don't apply. - -The tag file that Autotags creates and manages will be named after -|autotags_tagfile|, relative to the project's root directory. When Autotags -finds a valid project root, it will prepend the tag file's path to 'tags', -unless |autotags_auto_set_tags| is set to 0. This is to make sure Vim will use -that file first. - -If a file managed by Autotags is opened and no tag file already exists, -Autotags will start generating it right away in the background, unless -|autotags_generate_on_missing| is set to 0. If you have a large project, you -may want to know when Autotags is generating tags: see -|autotags-status-line| to display an indicator in your status line. - -When a file managed by Autotags 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 |autotags_generate_on_write| is set to 0, in which case you -have to run |AutotagsUpdate| manually. - - - *:AutotagsUpdate* -:AutotagsUpdate - 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. - -:AutotagsUpdate! - Like |AutotagsUpdate|, but updates the current tags - file with the whole project instead of just the - current buffer. - - -Some debugging/troubleshooting commands are also available. - - *:AutotagsToggleEnabled* -:AutotagsToggleEnabled - Disables and re-enables Autotags. - When Autotags 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 - Autotags. - - *AutotagsToggleTrace* -:AutotagsToggleTrace - If you want to keep an eye on what Autotags is doing, - you can enable tracing. This will show messages every - time Autotags 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 - Autotags redirect the output of the tag generation - script to a `.log` file in the project root. - - *:AutotagsUnlock* -:AutotagsUnlock - Autotags 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 |:AutotagsUnlock| 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 - Autotags, or something otherwise wrong or unexpected - with your system. Please file a bug. - -============================================================================= -3. Status Line *autotags-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. - - *autotags#statusline()* -You can display and indicator of tag generation progress in your |status-line| -with the following function: > - :set statusline+=%{autotags#statusline()} - -This won't print anything unless Autotags 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 |:AutotagsUnlock|. - -When Autotags thinks `ctags` is still running, it will print the string -"TAGS" by default. You can customize it: > - :set statusline+=%{autotags#statusline('[Generating...]')} - -This will print the string "[Generating...]" when tags are being generated. - - -============================================================================= -4. Global Settings *autotags-settings* - -The following settings can be defined in your |vimrc| to change the default -behaviour of Autotags. - - *autotags_enabled* -g:autotags_enabled - Defines whether Autotags should be enabled. When - disabled, Autotags will still scan for project root - markers when opening buffers. This is so that when you - re-enable Autotags, you won't have some buffers - mysteriously working while others (those open last) - don't. - Defaults to 1. - - *autotags_executable* -g:autotags_executable - Specifies the ctags executable to launch. - Defaults to `ctags`. - - *autotags_tagfile* -g:autotags_tagfile - Specifies the name of the tag file to create. This - will be appended to the project's root. See - |autotags_project_root| for how Autotags locates the - project. - Defaults to `tags`. - - *autotags_project_root* -g:autotags_project_root - When a buffer is loaded, Autotags 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, - Autotags will be enabled for the project, and a tags - file named after |autotags_tagfile| will be created at - the project root. - Defaults to `[]` (an empty |List|). - A list of default markers will always be appended to - the user-defined ones: ['.git', '.hg', '.bzr', - '_darcs']. - - *autotags_exclude* -g:autotags_exclude - A list of file patterns to pass to the - |autotags_executable| so that they will be excluded - from parsing for the tags generation. - Defaults to `[]` (an empty |List|). - Patterns defined in 'wildignore' will also be given as - exclude patterns to the `ctags` executable. - - *autotags_options_file* -g:autotags_options_file - The path to an options file that will be passed to - the `ctags` executable with the `--options` option. - In general you can put options in a `$HOME/.ctags` - file, but this lets you specify a custom file - specifically for Vim/Autotags. - - *autotags_auto_set_tags* -g:autotags_auto_set_tags - If set to 1, Autotags will automatically prepend - 'tags' with the exact path to the tag file for the - current project. See |autotags_project_root| for how - Autotags locates the project. - When set to 0, Autotags 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. - - *autotags_generate_on_missing* -g:autotags_generate_on_missing - If set to 1, Autotags will start generating an initial - tag file if a file is open in a project where no tags - file is found. See |autotags_project_root| for how - Autotags locates the project. - When set to 0, Autotags will only generate the first - time the file is saved (if - |autotags_generate_on_write| is set to 1), or when - |AutotagsUpdate| or |AutotagsGenerate| is run. - Defaults to 1. - - *autotags_generate_on_write* -g:autotags_generate_on_write - If set to 1, Autotags will update the current - project's tag file when a file inside that project is - saved. See |autotags_project_root| for how Autotags - locates the project. - When set to 0, Autotags 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 - |AutotagsUpdate| manually. - Defaults to 1. - - *autotags_background_update* -g:autotags_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. - - *autotags_cache_dir* -g:autotags_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. - - - vim:tw=78:et:ft=help:norl:
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/gutentags.txt Tue Sep 02 10:31:09 2014 -0700 @@ -0,0 +1,311 @@ +*gutentags.txt* Automatic ctags management for VIM + + ___ ___ ___ + /\ \ /\ \ /\ \ + /::\ \ \:\ \ ___ /::\ \ + /:/\:\ \ \:\ \ /\__\ /:/\:\ \ + /:/ /::\ \ ___ \:\ \ /:/ / /:/ \:\ \ + /:/_/:/\:\__\ /\ \ \:\__\ /:/__/ /:/__/ \:\__\ + \:\/:/ \/__/ \:\ \ /:/ / /::\ \ \:\ \ /:/ / + \::/__/ \:\ /:/ / /:/\:\ \ \:\ /:/ / + \:\ \ \:\/:/ / \/__\:\ \ \:\/:/ / + \:\__\ \::/ / \:\__\ \::/ / + \/__/ \/__/ _\/__/ \/__/ + /\ \ /\__\ /\__\ + ___ /::\ \ /:/ _/_ /:/ _/_ + /\__\ /:/\:\ \ /:/ /\ \ /:/ /\ \ + /:/ / /:/ /::\ \ /:/ /::\ \ /:/ /::\ \ + /:/__/ /:/_/:/\:\__\ /:/__\/\:\__\ /:/_/:/\:\__\ + /::\ \ \:\/:/ \/__/ \:\ \ /:/ / \:\/:/ /:/ / + /:/\:\ \ \::/__/ \:\ /:/ / \::/ /:/ / + \/__\:\ \ \:\ \ \:\/:/ / \/_/:/ / + \:\__\ \:\__\ \::/ / /:/ / + \/__/ \/__/ \/__/ \/__/ + + + AUTOTAGS 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| + +============================================================================= +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 to fast, or your project is really +big. + +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 in Sublime Text or + Visual Studio or any other IDE. + + +============================================================================= +2. Commands *gutentags-commands* + + *gutentags-global-commands* +The following commands are always available, whatever buffer you currently +have open: + + *:GutentagsGenerate* +:GutentagsGenerate {tagsfile} + Generates a tag file named {tagsfile}. Tags will be + generated for all the files in the same directory as + {tagsfile} and below (i.e. recursive from {tagsfile}'s + own directory). + + + *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 not 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. + +The tag file that Gutentags creates and manages will be named after +|gutentags_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_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. + + *: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_executable* +g:gutentags_executable + Specifies the ctags executable to launch. + Defaults to `ctags`. + + *gutentags_tagfile* +g:gutentags_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_tagfile| will be created at + the project root. + Defaults to `[]` (an empty |List|). + A list of default markers will always be appended to + the user-defined ones: ['.git', '.hg', '.bzr', + '_darcs']. + + *gutentags_exclude* +g:gutentags_exclude + A list of file patterns to pass to the + |gutentags_executable| so that they will be excluded + from parsing for the tags generation. + Defaults to `[]` (an empty |List|). + Patterns defined in 'wildignore' will also be given as + exclude patterns to the `ctags` executable. + + *gutentags_options_file* +g:gutentags_options_file + The path to an options file that will be passed to + the `ctags` executable with the `--options` option. + In general you can put options in a `$HOME/.ctags` + file, but this lets you specify a custom file + specifically for Vim/Gutentags. + + *gutentags_auto_set_tags* +g:gutentags_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_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. + + + vim:tw=78:et:ft=help:norl:
--- a/plugin/autotags.vim Mon Sep 01 08:48:48 2014 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,503 +0,0 @@ -" autotags.vim - Automatic ctags management for Vim -" Maintainer: Ludovic Chabant <http://ludovic.chabant.com> -" Version: 0.0.1 - -" Globals {{{ - -if !exists('g:autotags_debug') - let g:autotags_debug = 0 -endif - -if (exists('g:loaded_autotags') || &cp) && !g:autotags_debug - finish -endif -if (exists('g:loaded_autotags') && g:autotags_debug) - echom "Reloaded autotags." -endif -let g:loaded_autotags = 1 - -if !exists('g:autotags_trace') - let g:autotags_trace = 0 -endif - -if !exists('g:autotags_fake') - let g:autotags_fake = 0 -endif - -if !exists('g:autotags_background_update') - let g:autotags_background_update = 1 -endif - -if !exists('g:autotags_pause_after_update') - let g:autotags_pause_after_update = 0 -endif - -if !exists('g:autotags_enabled') - let g:autotags_enabled = 1 -endif - -if !exists('g:autotags_executable') - let g:autotags_executable = 'ctags' -endif - -if !exists('g:autotags_tagfile') - let g:autotags_tagfile = 'tags' -endif - -if !exists('g:autotags_project_root') - let g:autotags_project_root = [] -endif -let g:autotags_project_root += ['.git', '.hg', '.bzr', '_darcs'] - -if !exists('g:autotags_options_file') - let g:autotags_options_file = '' -endif - -if !exists('g:autotags_exclude') - let g:autotags_exclude = [] -endif - -if !exists('g:autotags_generate_on_new') - let g:autotags_generate_on_new = 1 -endif - -if !exists('g:autotags_generate_on_missing') - let g:autotags_generate_on_missing = 1 -endif - -if !exists('g:autotags_generate_on_write') - let g:autotags_generate_on_write = 1 -endif - -if !exists('g:autotags_auto_set_tags') - let g:autotags_auto_set_tags = 1 -endif - -if !exists('g:autotags_cache_dir') - let g:autotags_cache_dir = '' -else - let g:autotags_cache_dir = fnamemodify(g:autotags_cache_dir, ':s?[/\\]$??') -endif - -if g:autotags_cache_dir != '' && !isdirectory(g:autotags_cache_dir) - call mkdir(g:autotags_cache_dir, 'p') -endif - -" }}} - -" Utilities {{{ - -" Throw an exception message. -function! s:throw(message) - let v:errmsg = "autotags: " . a:message - throw v:errmsg -endfunction - -" Prints a message if debug tracing is enabled. -function! s:trace(message, ...) - if g:autotags_trace || (a:0 && a:1) - let l:message = "autotags: " . a:message - echom l:message - endif -endfunction - -" Strips the ending slash in a path. -function! s:stripslash(path) - return fnamemodify(a:path, ':s?[/\\]$??') -endfunction - -" Normalizes the slashes in a path. -function! s:normalizepath(path) - if exists('+shellslash') && &shellslash - return substitute(a:path, '\v/', '\\', 'g') - elseif has('win32') - return substitute(a:path, '\v/', '\\', 'g') - else - return a:path - endif -endfunction - -" Shell-slashes the path (opposite of `normalizepath`). -function! s:shellslash(path) - if exists('+shellslash') && !&shellslash - return substitute(a:path, '\v\\', '/', 'g') - else - return a:path - endif -endfunction - -" }}} - -" Autotags Setup {{{ - -let s:known_tagfiles = [] - -" Finds the first directory with a project marker by walking up from the given -" file path. -function! s:get_project_root(path) abort - let l:path = s:stripslash(a:path) - let l:previous_path = "" - let l:markers = g:autotags_project_root[:] - if exists('g:ctrlp_root_markers') - let l:markers += g:ctrlp_root_markers - endif - while l:path != l:previous_path - for root in g:autotags_project_root - if getftype(l:path . '/' . root) != "" - return simplify(fnamemodify(l:path, ':p')) - endif - endfor - let l:previous_path = l:path - let l:path = fnamemodify(l:path, ':h') - endwhile - call s:throw("Can't figure out what tag file to use for: " . a:path) -endfunction - -" Get the tag filename for a given project root. -function! s:get_tagfile(root_dir) abort - let l:tag_path = s:stripslash(a:root_dir) . '/' . g:autotags_tagfile - if g:autotags_cache_dir != "" - " Put the tag file in the cache dir instead of inside the - " projet root. - let l:tag_path = g:autotags_cache_dir . '/' . - \tr(l:tag_path, '\/:', '---') - let l:tag_path = substitute(l:tag_path, '/\-', '/', '') - endif - let l:tag_path = s:normalizepath(l:tag_path) - return l:tag_path -endfunction - -" Setup autotags for the current buffer. -function! s:setup_autotags() abort - if exists('b:autotags_file') && !g:autotags_debug - " This buffer already has autotags support. - return - endif - - " Try and find what tags file we should manage. - call s:trace("Scanning buffer '" . bufname('%') . "' for autotags setup...") - try - let b:autotags_root = s:get_project_root(expand('%:h')) - let b:autotags_file = s:get_tagfile(b:autotags_root) - catch /^autotags\:/ - call s:trace("Can't figure out what tag file to use... no autotags support.") - return - endtry - - " We know what tags file to manage! Now set things up. - call s:trace("Setting autotags for buffer '" . bufname('%') . "' with tagfile: " . b:autotags_file) - - " Set the tags file for Vim to use. - if g:autotags_auto_set_tags - execute 'setlocal tags^=' . b:autotags_file - endif - - " Autocommands for updating the tags on save. - let l:bn = bufnr('%') - execute 'augroup autotags_buffer_' . l:bn - execute ' autocmd!' - execute ' autocmd BufWritePost <buffer=' . l:bn . '> call s:write_triggered_update_tags()' - execute 'augroup end' - - " Miscellaneous commands. - command! -buffer -bang AutotagsUpdate :call s:manual_update_tags(<bang>0) - - " Add this tags file to the known tags files if it wasn't there already. - let l:found = index(s:known_tagfiles, b:autotags_file) - if l:found < 0 - call add(s:known_tagfiles, b:autotags_file) - - " Generate this new file depending on settings and stuff. - if g:autotags_generate_on_missing && !filereadable(b:autotags_file) - call s:trace("Generating missing tags file: " . b:autotags_file) - call s:update_tags(1, 0) - elseif g:autotags_generate_on_new - call s:trace("Generating tags file: " . b:autotags_file) - call s:update_tags(1, 0) - endif - endif -endfunction - -augroup autotags_detect - autocmd! - autocmd BufNewFile,BufReadPost * call s:setup_autotags() - autocmd VimEnter * if expand('<amatch>')==''|call s:setup_autotags()|endif -augroup end - -" }}} - -" Tags File Management {{{ - -let s:runner_exe = expand('<sfile>:h:h') . '/plat/unix/update_tags.sh' -if has('win32') - let s:runner_exe = expand('<sfile>:h:h') . '\plat\win32\update_tags.cmd' -endif - -let s:update_queue = [] -let s:maybe_in_progress = {} - -" Get how to execute an external command depending on debug settings. -function! s:get_execute_cmd() abort - if has('win32') - let l:cmd = '!start ' - if g:autotags_background_update - let l:cmd .= '/b ' - endif - return l:cmd - else - return '!' - endif -endfunction - -" Get the suffix for how to execute an external command. -function! s:get_execute_cmd_suffix() abort - if has('win32') - return '' - else - return ' &' - endif -endfunction - -" (Re)Generate the tags file for the current buffer's file. -function! s:manual_update_tags(bang) abort - call s:update_tags(a:bang, 0) -endfunction - -" (Re)Generate the tags file for a buffer that just go saved. -function! s:write_triggered_update_tags() abort - if g:autotags_enabled && g:autotags_generate_on_write - call s:update_tags(0, 1) - endif -endfunction - -" Update the tags file for the current buffer's file. -" write_mode: -" 0: update the tags file if it exists, generate it otherwise. -" 1: always generate (overwrite) the tags file. -" -" queue_mode: -" 0: if an update is already in progress, report it and abort. -" 1: if an update is already in progress, queue another one. -" -" An additional argument specifies where to write the tags file. If nothing -" is specified, it will go to the autotags-defined file. -function! s:update_tags(write_mode, queue_mode, ...) abort - " Figure out where to save. - if a:0 == 1 - let l:tags_file = a:1 - let l:proj_dir = fnamemodify(a:1, ':h') - else - let l:tags_file = b:autotags_file - let l:proj_dir = b:autotags_root - endif - - " Check that there's not already an update in progress. - let l:lock_file = l:tags_file . '.lock' - if filereadable(l:lock_file) - if a:queue_mode == 1 - let l:idx = index(s:update_queue, l:tags_file) - if l:idx < 0 - call add(s:update_queue, l:tags_file) - endif - call s:trace("Tag file '" . l:tags_file . "' is already being updated. Queuing it up...") - call s:trace("") - else - echom "autotags: The tags file is already being updated, please try again later." - echom "" - endif - return - endif - - " Switch to the project root to make the command line smaller, and make - " it possible to get the relative path of the filename to parse if we're - " doing an incremental update. - let l:prev_cwd = getcwd() - let l:work_dir = fnamemodify(l:tags_file, ':h') - execute "chdir " . l:work_dir - - try - " Build the command line. - let l:cmd = s:get_execute_cmd() . s:runner_exe - let l:cmd .= ' -e "' . g:autotags_executable . '"' - let l:cmd .= ' -t "' . l:tags_file . '"' - let l:cmd .= ' -p "' . l:proj_dir . '"' - if a:write_mode == 0 && filereadable(l:tags_file) - let l:full_path = expand('%:p') - let l:cmd .= ' -s "' . l:full_path . '"' - endif - for ign in split(&wildignore, ',') - let l:cmd .= ' -x ' . ign - endfor - for exc in g:autotags_exclude - let l:cmd .= ' -x ' . exc - endfor - if g:autotags_pause_after_update - let l:cmd .= ' -p' - endif - if len(g:autotags_options_file) - let l:cmd .= ' -o "' . g:autotags_options_file . '"' - endif - if g:autotags_trace - if has('win32') - let l:cmd .= ' -l "' . l:tags_file . '.log"' - else - let l:cmd .= ' > "' . l:tags_file . '.log" 2>&1' - endif - else - if !has('win32') - let l:cmd .= ' > /dev/null 2>&1' - endif - endif - let l:cmd .= s:get_execute_cmd_suffix() - - call s:trace("Running: " . l:cmd) - call s:trace("In: " . l:work_dir) - if !g:autotags_fake - " Run the background process. - if !g:autotags_trace - silent execute l:cmd - else - execute l:cmd - endif - - " Flag this tags file as being in progress - let l:full_tags_file = fnamemodify(l:tags_file, ':p') - let s:maybe_in_progress[l:full_tags_file] = localtime() - else - call s:trace("(fake... not actually running)") - endif - call s:trace("") - finally - " Restore the current directory... - execute "chdir " . l:prev_cwd - endtry -endfunction - -" }}} - -" Manual Tagfile Generation {{{ - -function! s:generate_tags(bang, ...) abort - call s:update_tags(1, 0, a:1) -endfunction - -command! -bang -nargs=1 -complete=file AutotagsGenerate :call s:generate_tags(<bang>0, <f-args>) - -" }}} - -" Toggles and Miscellaneous Commands {{{ - -command! AutotagsToggleEnabled :let g:autotags_enabled=!g:autotags_enabled -command! AutotagsToggleTrace :call autotags#trace() -command! AutotagsUnlock :call delete(b:autotags_file . '.lock') - -if g:autotags_debug - command! AutotagsToggleFake :call autotags#fake() -endif - -" }}} - -" Autoload Functions {{{ - -function! autotags#rescan(...) - if exists('b:autotags_file') - unlet b:autotags_file - endif - if a:0 && a:1 - let l:trace_backup = g:autotags_trace - let l:autotags_trace = 1 - endif - call s:setup_autotags() - if a:0 && a:1 - let g:autotags_trace = l:trace_backup - endif -endfunction - -function! autotags#trace(...) - let g:autotags_trace = !g:autotags_trace - if a:0 > 0 - let g:autotags_trace = a:1 - endif - if g:autotags_trace - echom "autotags: Tracing is enabled." - else - echom "autotags: Tracing is disabled." - endif - echom "" -endfunction - -function! autotags#fake(...) - let g:autotags_fake = !g:autotags_fake - if a:0 > 0 - let g:autotags_fake = a:1 - endif - if g:autotags_fake - echom "autotags: Now faking autotags." - else - echom "autotags: Now running autotags for real." - endif - echom "" -endfunction - -function! autotags#inprogress() - echom "autotags: generations in progress:" - for mip in keys(s:maybe_in_progress) - echom mip - endfor - echom "" -endfunction - -" }}} - -" Statusline Functions {{{ - -" Prints whether a tag file is being generated right now for the current -" buffer in the status line. -" -" Arguments can be passed: -" - args 1 and 2 are the prefix and suffix, respectively, of whatever output, -" if any, is going to be produced. -" (defaults to empty strings) -" - arg 3 is the text to be shown if tags are currently being generated. -" (defaults to 'TAGS') - -function! autotags#statusline(...) abort - if !exists('b:autotags_file') - " This buffer doesn't have autotags. - return '' - endif - - " Figure out what the user is customizing. - let l:gen_msg = 'TAGS' - if a:0 >= 0 - let l:gen_msg = a:1 - endif - - " To make this function as fast as possible, we first check whether the - " current buffer's tags file is 'maybe' being generated. This provides a - " nice and quick bail out for 99.9% of cases before we need to this the - " file-system to check the lock file. - let l:abs_tag_file = fnamemodify(b:autotags_file, ':p') - let l:timestamp = get(s:maybe_in_progress, l:abs_tag_file) - if l:timestamp == 0 - return '' - endif - " It's maybe generating! Check if the lock file is still there... but - " don't do it too soon after the script was originally launched, because - " there can be a race condition where we get here just before the script - " had a chance to write the lock file. - if (localtime() - l:timestamp) > 1 && - \!filereadable(l:abs_tag_file . '.lock') - call remove(s:maybe_in_progress, l:abs_tag_file) - return '' - endif - " It's still there! So probably `ctags` is still running... - " (although there's a chance it crashed, or the script had a problem, and - " the lock file has been left behind... we could try and run some - " additional checks here to see if it's legitimately running, and - " otherwise delete the lock file... maybe in the future...) - return l:gen_msg -endfunction - -" }}} -
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/plugin/gutentags.vim Tue Sep 02 10:31:09 2014 -0700 @@ -0,0 +1,503 @@ +" gutentags.vim - Automatic ctags management for Vim +" Maintainer: Ludovic Chabant <http://ludovic.chabant.com> +" Version: 0.0.1 + +" Globals {{{ + +if !exists('g:gutentags_debug') + let g:gutentags_debug = 0 +endif + +if (exists('g:loaded_gutentags') || &cp) && !g:gutentags_debug + finish +endif +if (exists('g:loaded_gutentags') && g:gutentags_debug) + echom "Reloaded gutentags." +endif +let g:loaded_gutentags = 1 + +if !exists('g:gutentags_trace') + let g:gutentags_trace = 0 +endif + +if !exists('g:gutentags_fake') + let g:gutentags_fake = 0 +endif + +if !exists('g:gutentags_background_update') + let g:gutentags_background_update = 1 +endif + +if !exists('g:gutentags_pause_after_update') + let g:gutentags_pause_after_update = 0 +endif + +if !exists('g:gutentags_enabled') + let g:gutentags_enabled = 1 +endif + +if !exists('g:gutentags_executable') + let g:gutentags_executable = 'ctags' +endif + +if !exists('g:gutentags_tagfile') + let g:gutentags_tagfile = 'tags' +endif + +if !exists('g:gutentags_project_root') + let g:gutentags_project_root = [] +endif +let g:gutentags_project_root += ['.git', '.hg', '.bzr', '_darcs'] + +if !exists('g:gutentags_options_file') + let g:gutentags_options_file = '' +endif + +if !exists('g:gutentags_exclude') + let g:gutentags_exclude = [] +endif + +if !exists('g:gutentags_generate_on_new') + let g:gutentags_generate_on_new = 1 +endif + +if !exists('g:gutentags_generate_on_missing') + let g:gutentags_generate_on_missing = 1 +endif + +if !exists('g:gutentags_generate_on_write') + let g:gutentags_generate_on_write = 1 +endif + +if !exists('g:gutentags_auto_set_tags') + let g:gutentags_auto_set_tags = 1 +endif + +if !exists('g:gutentags_cache_dir') + let g:gutentags_cache_dir = '' +else + let g:gutentags_cache_dir = fnamemodify(g:gutentags_cache_dir, ':s?[/\\]$??') +endif + +if g:gutentags_cache_dir != '' && !isdirectory(g:gutentags_cache_dir) + call mkdir(g:gutentags_cache_dir, 'p') +endif + +" }}} + +" Utilities {{{ + +" Throw an exception message. +function! s:throw(message) + let v:errmsg = "gutentags: " . a:message + throw v:errmsg +endfunction + +" Prints a message if debug tracing is enabled. +function! s:trace(message, ...) + if g:gutentags_trace || (a:0 && a:1) + let l:message = "gutentags: " . a:message + echom l:message + endif +endfunction + +" Strips the ending slash in a path. +function! s:stripslash(path) + return fnamemodify(a:path, ':s?[/\\]$??') +endfunction + +" Normalizes the slashes in a path. +function! s:normalizepath(path) + if exists('+shellslash') && &shellslash + return substitute(a:path, '\v/', '\\', 'g') + elseif has('win32') + return substitute(a:path, '\v/', '\\', 'g') + else + return a:path + endif +endfunction + +" Shell-slashes the path (opposite of `normalizepath`). +function! s:shellslash(path) + if exists('+shellslash') && !&shellslash + return substitute(a:path, '\v\\', '/', 'g') + else + return a:path + endif +endfunction + +" }}} + +" Gutentags Setup {{{ + +let s:known_tagfiles = [] + +" Finds the first directory with a project marker by walking up from the given +" file path. +function! s:get_project_root(path) abort + let l:path = s:stripslash(a:path) + let l:previous_path = "" + let l:markers = g:gutentags_project_root[:] + if exists('g:ctrlp_root_markers') + let l:markers += g:ctrlp_root_markers + endif + while l:path != l:previous_path + for root in g:gutentags_project_root + if getftype(l:path . '/' . root) != "" + return simplify(fnamemodify(l:path, ':p')) + endif + endfor + let l:previous_path = l:path + let l:path = fnamemodify(l:path, ':h') + endwhile + call s:throw("Can't figure out what tag file to use for: " . a:path) +endfunction + +" Get the tag filename for a given project root. +function! s:get_tagfile(root_dir) abort + let l:tag_path = s:stripslash(a:root_dir) . '/' . g:gutentags_tagfile + if g:gutentags_cache_dir != "" + " Put the tag file in the cache dir instead of inside the + " projet root. + let l:tag_path = g:gutentags_cache_dir . '/' . + \tr(l:tag_path, '\/:', '---') + let l:tag_path = substitute(l:tag_path, '/\-', '/', '') + endif + let l:tag_path = s:normalizepath(l:tag_path) + return l:tag_path +endfunction + +" Setup gutentags for the current buffer. +function! s:setup_gutentags() abort + if exists('b:gutentags_file') && !g:gutentags_debug + " This buffer already has gutentags support. + return + endif + + " Try and find what tags file we should manage. + call s:trace("Scanning buffer '" . bufname('%') . "' for gutentags setup...") + try + let b:gutentags_root = s:get_project_root(expand('%:h')) + let b:gutentags_file = s:get_tagfile(b:gutentags_root) + catch /^gutentags\:/ + call s:trace("Can't figure out what tag file to use... no gutentags support.") + return + endtry + + " We know what tags file to manage! Now set things up. + call s:trace("Setting gutentags for buffer '" . bufname('%') . "' with tagfile: " . b:gutentags_file) + + " Set the tags file for Vim to use. + if g:gutentags_auto_set_tags + execute 'setlocal tags^=' . b:gutentags_file + endif + + " Autocommands for updating the tags on save. + let l:bn = bufnr('%') + execute 'augroup gutentags_buffer_' . l:bn + execute ' autocmd!' + execute ' autocmd BufWritePost <buffer=' . l:bn . '> call s:write_triggered_update_tags()' + execute 'augroup end' + + " Miscellaneous commands. + command! -buffer -bang GutentagsUpdate :call s:manual_update_tags(<bang>0) + + " Add this tags file to the known tags files if it wasn't there already. + let l:found = index(s:known_tagfiles, b:gutentags_file) + if l:found < 0 + call add(s:known_tagfiles, b:gutentags_file) + + " Generate this new file depending on settings and stuff. + if g:gutentags_generate_on_missing && !filereadable(b:gutentags_file) + call s:trace("Generating missing tags file: " . b:gutentags_file) + call s:update_tags(1, 0) + elseif g:gutentags_generate_on_new + call s:trace("Generating tags file: " . b:gutentags_file) + call s:update_tags(1, 0) + endif + endif +endfunction + +augroup gutentags_detect + autocmd! + autocmd BufNewFile,BufReadPost * call s:setup_gutentags() + autocmd VimEnter * if expand('<amatch>')==''|call s:setup_gutentags()|endif +augroup end + +" }}} + +" Tags File Management {{{ + +let s:runner_exe = expand('<sfile>:h:h') . '/plat/unix/update_tags.sh' +if has('win32') + let s:runner_exe = expand('<sfile>:h:h') . '\plat\win32\update_tags.cmd' +endif + +let s:update_queue = [] +let s:maybe_in_progress = {} + +" Get how to execute an external command depending on debug settings. +function! s:get_execute_cmd() abort + if has('win32') + let l:cmd = '!start ' + if g:gutentags_background_update + let l:cmd .= '/b ' + endif + return l:cmd + else + return '!' + endif +endfunction + +" Get the suffix for how to execute an external command. +function! s:get_execute_cmd_suffix() abort + if has('win32') + return '' + else + return ' &' + endif +endfunction + +" (Re)Generate the tags file for the current buffer's file. +function! s:manual_update_tags(bang) abort + call s:update_tags(a:bang, 0) +endfunction + +" (Re)Generate the tags file for a buffer that just go saved. +function! s:write_triggered_update_tags() abort + if g:gutentags_enabled && g:gutentags_generate_on_write + call s:update_tags(0, 1) + endif +endfunction + +" Update the tags file for the current buffer's file. +" write_mode: +" 0: update the tags file if it exists, generate it otherwise. +" 1: always generate (overwrite) the tags file. +" +" queue_mode: +" 0: if an update is already in progress, report it and abort. +" 1: if an update is already in progress, queue another one. +" +" An additional argument specifies where to write the tags file. If nothing +" is specified, it will go to the gutentags-defined file. +function! s:update_tags(write_mode, queue_mode, ...) abort + " Figure out where to save. + if a:0 == 1 + let l:tags_file = a:1 + let l:proj_dir = fnamemodify(a:1, ':h') + else + let l:tags_file = b:gutentags_file + let l:proj_dir = b:gutentags_root + endif + + " Check that there's not already an update in progress. + let l:lock_file = l:tags_file . '.lock' + if filereadable(l:lock_file) + if a:queue_mode == 1 + let l:idx = index(s:update_queue, l:tags_file) + if l:idx < 0 + call add(s:update_queue, l:tags_file) + endif + call s:trace("Tag file '" . l:tags_file . "' is already being updated. Queuing it up...") + call s:trace("") + else + echom "gutentags: The tags file is already being updated, please try again later." + echom "" + endif + return + endif + + " Switch to the project root to make the command line smaller, and make + " it possible to get the relative path of the filename to parse if we're + " doing an incremental update. + let l:prev_cwd = getcwd() + let l:work_dir = fnamemodify(l:tags_file, ':h') + execute "chdir " . l:work_dir + + try + " Build the command line. + let l:cmd = s:get_execute_cmd() . s:runner_exe + let l:cmd .= ' -e "' . g:gutentags_executable . '"' + let l:cmd .= ' -t "' . l:tags_file . '"' + let l:cmd .= ' -p "' . l:proj_dir . '"' + if a:write_mode == 0 && filereadable(l:tags_file) + let l:full_path = expand('%:p') + let l:cmd .= ' -s "' . l:full_path . '"' + endif + for ign in split(&wildignore, ',') + let l:cmd .= ' -x ' . ign + endfor + for exc in g:gutentags_exclude + let l:cmd .= ' -x ' . exc + endfor + if g:gutentags_pause_after_update + let l:cmd .= ' -p' + endif + if len(g:gutentags_options_file) + let l:cmd .= ' -o "' . g:gutentags_options_file . '"' + endif + if g:gutentags_trace + if has('win32') + let l:cmd .= ' -l "' . l:tags_file . '.log"' + else + let l:cmd .= ' > "' . l:tags_file . '.log" 2>&1' + endif + else + if !has('win32') + let l:cmd .= ' > /dev/null 2>&1' + endif + endif + let l:cmd .= s:get_execute_cmd_suffix() + + call s:trace("Running: " . l:cmd) + call s:trace("In: " . l:work_dir) + if !g:gutentags_fake + " Run the background process. + if !g:gutentags_trace + silent execute l:cmd + else + execute l:cmd + endif + + " Flag this tags file as being in progress + let l:full_tags_file = fnamemodify(l:tags_file, ':p') + let s:maybe_in_progress[l:full_tags_file] = localtime() + else + call s:trace("(fake... not actually running)") + endif + call s:trace("") + finally + " Restore the current directory... + execute "chdir " . l:prev_cwd + endtry +endfunction + +" }}} + +" Manual Tagfile Generation {{{ + +function! s:generate_tags(bang, ...) abort + call s:update_tags(1, 0, a:1) +endfunction + +command! -bang -nargs=1 -complete=file GutentagsGenerate :call s:generate_tags(<bang>0, <f-args>) + +" }}} + +" Toggles and Miscellaneous Commands {{{ + +command! GutentagsToggleEnabled :let g:gutentags_enabled=!g:gutentags_enabled +command! GutentagsToggleTrace :call gutentags#trace() +command! GutentagsUnlock :call delete(b:gutentags_file . '.lock') + +if g:gutentags_debug + command! GutentagsToggleFake :call gutentags#fake() +endif + +" }}} + +" Autoload Functions {{{ + +function! gutentags#rescan(...) + if exists('b:gutentags_file') + unlet b:gutentags_file + endif + if a:0 && a:1 + let l:trace_backup = g:gutentags_trace + let l:gutentags_trace = 1 + endif + call s:setup_gutentags() + if a:0 && a:1 + let g:gutentags_trace = l:trace_backup + endif +endfunction + +function! gutentags#trace(...) + let g:gutentags_trace = !g:gutentags_trace + if a:0 > 0 + let g:gutentags_trace = a:1 + endif + if g:gutentags_trace + echom "gutentags: Tracing is enabled." + else + echom "gutentags: Tracing is disabled." + endif + echom "" +endfunction + +function! gutentags#fake(...) + let g:gutentags_fake = !g:gutentags_fake + if a:0 > 0 + let g:gutentags_fake = a:1 + endif + if g:gutentags_fake + echom "gutentags: Now faking gutentags." + else + echom "gutentags: Now running gutentags for real." + endif + echom "" +endfunction + +function! gutentags#inprogress() + echom "gutentags: generations in progress:" + for mip in keys(s:maybe_in_progress) + echom mip + endfor + echom "" +endfunction + +" }}} + +" Statusline Functions {{{ + +" Prints whether a tag file is being generated right now for the current +" buffer in the status line. +" +" Arguments can be passed: +" - args 1 and 2 are the prefix and suffix, respectively, of whatever output, +" if any, is going to be produced. +" (defaults to empty strings) +" - arg 3 is the text to be shown if tags are currently being generated. +" (defaults to 'TAGS') + +function! gutentags#statusline(...) abort + if !exists('b:gutentags_file') + " This buffer doesn't have gutentags. + return '' + endif + + " Figure out what the user is customizing. + let l:gen_msg = 'TAGS' + if a:0 >= 0 + let l:gen_msg = a:1 + endif + + " To make this function as fast as possible, we first check whether the + " current buffer's tags file is 'maybe' being generated. This provides a + " nice and quick bail out for 99.9% of cases before we need to this the + " file-system to check the lock file. + let l:abs_tag_file = fnamemodify(b:gutentags_file, ':p') + let l:timestamp = get(s:maybe_in_progress, l:abs_tag_file) + if l:timestamp == 0 + return '' + endif + " It's maybe generating! Check if the lock file is still there... but + " don't do it too soon after the script was originally launched, because + " there can be a race condition where we get here just before the script + " had a chance to write the lock file. + if (localtime() - l:timestamp) > 1 && + \!filereadable(l:abs_tag_file . '.lock') + call remove(s:maybe_in_progress, l:abs_tag_file) + return '' + endif + " It's still there! So probably `ctags` is still running... + " (although there's a chance it crashed, or the script had a problem, and + " the lock file has been left behind... we could try and run some + " additional checks here to see if it's legitimately running, and + " otherwise delete the lock file... maybe in the future...) + return l:gen_msg +endfunction + +" }}} +