Mercurial > vim-gutentags
annotate README.md @ 37:0c67b56abc63
Attempt at better error handling with the Windows update script.
* Use `call` to run Ctags because apparently, the way Vim runs background
Windows scripts means the whole thing will abort if there's an error.
But here we want to keep going so we get a chance to unlock the tags file
if possible.
* Add some `ERRORLEVEL` handling code.
* Log more stuff to the log file.
| author | Ludovic Chabant <ludovic@chabant.com> |
|---|---|
| date | Mon, 15 Dec 2014 13:00:04 -0800 |
| parents | 4e1b0253f71a |
| children | 5c1baa6007d8 |
| rev | line source |
|---|---|
| 6 | 1 |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
2 # Gutentags |
| 6 | 3 |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
4 Gutentags is a plugin that takes care of the much needed management of tags |
| 6 | 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 | |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
11 Install Gutentags like any other Vim plugin. I recommend something like |
| 6 | 12 [Pathogen][], so you can go: |
| 13 | |
| 14 cd ~/.vim/bundle | |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
15 hg clone https://bitbucket.org/ludovicchabant/vim-gutentags |
| 6 | 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 | |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
19 with `help gutentags`. |
| 6 | 20 |
| 21 | |
| 22 ## What? | |
| 23 | |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
24 In order to generate tag files, Gutentags will have to figure out what's in |
| 6 | 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 | |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
27 `gutentags_project_root`), and even things you may have defined already with |
| 6 | 28 other plugins, like [CtrlP][]. |
| 29 | |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
30 If the current file you're editing is found to be in such a project, Gutentags |
| 6 | 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 | |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
36 Usually, ctags can only append tags to an existing tag file, so Gutentags |
| 6 | 37 removes the tags for the current file first, to make sure the tag file is |
| 38 always consistent with the source code. | |
| 39 | |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
40 Also, Gutentags is clever enough to not stumble upon itself by triggering |
| 6 | 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 | |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
49 I set for myself with Gutentags: |
| 6 | 50 |
| 51 * No other dependency than running Vim: no Python, Ruby, or whatever. | |
| 52 * Cross-platform: should work on at least Mac and Windows. | |
|
18
b13e1141aa5c
Fix wording in `README`.
Ludovic Chabant <ludovic@chabant.com>
parents:
6
diff
changeset
|
53 * Incremental tags generation: don't re-generate the whole project all the time. |
|
b13e1141aa5c
Fix wording in `README`.
Ludovic Chabant <ludovic@chabant.com>
parents:
6
diff
changeset
|
54 This may be fine for small projects, but it doesn't scale. |
|
b13e1141aa5c
Fix wording in `README`.
Ludovic Chabant <ludovic@chabant.com>
parents:
6
diff
changeset
|
55 * External process management: if the ctags process is taking a long time, don't |
|
b13e1141aa5c
Fix wording in `README`.
Ludovic Chabant <ludovic@chabant.com>
parents:
6
diff
changeset
|
56 run another one because I saved the file again. |
|
b13e1141aa5c
Fix wording in `README`.
Ludovic Chabant <ludovic@chabant.com>
parents:
6
diff
changeset
|
57 * Keep the tag file consistent: don't just append the current file's tags to the |
|
b13e1141aa5c
Fix wording in `README`.
Ludovic Chabant <ludovic@chabant.com>
parents:
6
diff
changeset
|
58 tag file, otherwise you will still "see" tags for deleted or renamed classes |
|
b13e1141aa5c
Fix wording in `README`.
Ludovic Chabant <ludovic@chabant.com>
parents:
6
diff
changeset
|
59 and functions. |
| 6 | 60 * Automatically create the tag file: you open something from a freshly forked |
|
18
b13e1141aa5c
Fix wording in `README`.
Ludovic Chabant <ludovic@chabant.com>
parents:
6
diff
changeset
|
61 project, it should start indexing it automatically, just like in Sublime Text |
|
b13e1141aa5c
Fix wording in `README`.
Ludovic Chabant <ludovic@chabant.com>
parents:
6
diff
changeset
|
62 or Visual Studio or any other IDE. |
| 6 | 63 |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
64 I hope Gutentags will bring you as much closure as me regarding tag files. I know |
|
18
b13e1141aa5c
Fix wording in `README`.
Ludovic Chabant <ludovic@chabant.com>
parents:
6
diff
changeset
|
65 I don't want to have to think about it, and probably neither do you. |
| 6 | 66 |
| 67 | |
| 68 [ctrlp]: https://github.com/kien/ctrlp.vim | |
| 69 |