Mercurial > vim-gutentags
comparison README.md @ 6:ec87439fc784
Add README file.
| author | Ludovic Chabant <ludovic@chabant.com> |
|---|---|
| date | Sun, 20 Jul 2014 14:39:03 -0700 |
| parents | |
| children | b13e1141aa5c |
comparison
equal
deleted
inserted
replaced
| 5:12f4f50f4d3a | 6:ec87439fc784 |
|---|---|
| 1 | |
| 2 # Autotags | |
| 3 | |
| 4 Autotags is a plugin that takes care of the much needed management of tags | |
| 5 files in Vim. It will (re)generate tag files as you work while staying | |
| 6 completely out of your way. It will even do its best to keep those tag files | |
| 7 out of your way too. It has no dependencies and just works. | |
| 8 | |
| 9 ## How? | |
| 10 | |
| 11 Install Autotags like any other Vim plugin. I recommend something like | |
| 12 [Pathogen][], so you can go: | |
| 13 | |
| 14 cd ~/.vim/bundle | |
| 15 hg clone https://bitbucket.org/ludovicchabant/vim-autotags | |
| 16 | |
| 17 Then you only need to do a `:call pathogen#helptags()` to generate the | |
| 18 documentation tags (how ironic, eh?) and you can access Autotag's help pages | |
| 19 with `help autotags`. | |
| 20 | |
| 21 | |
| 22 ## What? | |
| 23 | |
| 24 In order to generate tag files, Autotags will have to figure out what's in | |
| 25 your project. To do this, it will locate well-known project root markers like | |
| 26 SCM folders (`.git`, `.hg`, etc.), any custom tags you define (with | |
| 27 `autotags_project_root`), and even things you may have defined already with | |
| 28 other plugins, like [CtrlP][]. | |
| 29 | |
| 30 If the current file you're editing is found to be in such a project, Autotags | |
| 31 will make sure the tag file for that project is up to date. Then, as you work | |
| 32 in files in that project, it will partially re-generate the tag file. Every | |
| 33 time you save, it will silently, in the background, update the tags for that | |
| 34 file. | |
| 35 | |
| 36 Usually, ctags can only append tags to an existing tag file, so Autotags | |
| 37 removes the tags for the current file first, to make sure the tag file is | |
| 38 always consistent with the source code. | |
| 39 | |
| 40 Also, Autotags is clever enough to not stumble upon itself by triggering | |
| 41 multiple ctags processes if you save files to fast, or your project is really | |
| 42 big. | |
| 43 | |
| 44 | |
| 45 ## Why? | |
| 46 | |
| 47 There are some similar Vim plugins out there ("vim-tags", "vim-autotag", | |
| 48 "vim-automatic-ctags", etc.). They all fail on one or more of the requirements | |
| 49 I set for myself with Autotags: | |
| 50 | |
| 51 * No other dependency than running Vim: no Python, Ruby, or whatever. | |
| 52 * Cross-platform: should work on at least Mac and Windows. | |
| 53 * Incremental tags generation: don't re-generate the whole project all the | |
| 54 time. This may be fine for small projects, but it doesn't scale. | |
| 55 * External process management: if the ctags process is taking a long time, | |
| 56 don't run another one because I saved the file again. | |
| 57 * Keep the tag file consistent: don't just append the current file's tags to | |
| 58 the tag file, otherwise you will still "see" tags for deleted or renamed | |
| 59 classes and functions. | |
| 60 * Automatically create the tag file: you open something from a freshly forked | |
| 61 project, it should start indexing it automatically, just in Sublime Text or | |
| 62 Visual Studio or any other IDE. | |
| 63 | |
| 64 I hope Autotags will bring you as much closure as me regarding tag files. I know | |
| 65 I don't want to think about it, and probably neither do you. | |
| 66 | |
| 67 | |
| 68 [ctrlp]: https://github.com/kien/ctrlp.vim | |
| 69 |