*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_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.



 vim:tw=78:et:ft=help:norl: