Mercurial > vim-gutentags
annotate README.md @ 251:e61d20280c6c
Fix some more spaces-in-paths issues.
When using the tags cache directory, the project root is passed to ctags.
Escaping this path didn't work correctly when it has spaces:
- We remove the quotes around it on *nix because `job_start()` doesn't
like those, but then we need to escape the spaces with backslashes
otherwise the script doesn't understand those parameters.
- Once the escaping is gone in the script, we need to quote them but it
looks like sh doesn't like double quotes in the middle of an env var
or something, so we need to put the project root in a separate env
var.
| author | Ludovic Chabant <ludovic@chabant.com> |
|---|---|
| date | Fri, 25 Oct 2019 23:52:12 -0700 |
| parents | 39547ffc8867 |
| children |
| 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 | |
|
172
02a94ff0db57
Add CONTRIBUTING file.
Ludovic Chabant <ludovic@chabant.com>
parents:
52
diff
changeset
|
9 |
| 6 | 10 ## How? |
| 11 | |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
12 Install Gutentags like any other Vim plugin. I recommend something like |
| 6 | 13 [Pathogen][], so you can go: |
| 14 | |
| 15 cd ~/.vim/bundle | |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
16 hg clone https://bitbucket.org/ludovicchabant/vim-gutentags |
| 6 | 17 |
|
183
bd641fccdae4
Add GitHub link to README.
Ludovic Chabant <ludovic@chabant.com>
parents:
172
diff
changeset
|
18 If you're more into Git than Mercurial: |
|
bd641fccdae4
Add GitHub link to README.
Ludovic Chabant <ludovic@chabant.com>
parents:
172
diff
changeset
|
19 |
|
bd641fccdae4
Add GitHub link to README.
Ludovic Chabant <ludovic@chabant.com>
parents:
172
diff
changeset
|
20 git clone https://github.com/ludovicchabant/vim-gutentags.git |
|
bd641fccdae4
Add GitHub link to README.
Ludovic Chabant <ludovic@chabant.com>
parents:
172
diff
changeset
|
21 |
| 6 | 22 Then you only need to do a `:call pathogen#helptags()` to generate the |
|
42
5c1baa6007d8
Fix typo in `README` file.
Ludovic Chabant <ludovic@chabant.com>
parents:
22
diff
changeset
|
23 documentation tags (how ironic, eh?) and you can access Gutentags' help pages |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
24 with `help gutentags`. |
| 6 | 25 |
| 26 | |
| 27 ## What? | |
| 28 | |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
29 In order to generate tag files, Gutentags will have to figure out what's in |
| 6 | 30 your project. To do this, it will locate well-known project root markers like |
| 31 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
|
32 `gutentags_project_root`), and even things you may have defined already with |
| 6 | 33 other plugins, like [CtrlP][]. |
| 34 | |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
35 If the current file you're editing is found to be in such a project, Gutentags |
| 6 | 36 will make sure the tag file for that project is up to date. Then, as you work |
| 37 in files in that project, it will partially re-generate the tag file. Every | |
| 38 time you save, it will silently, in the background, update the tags for that | |
| 39 file. | |
| 40 | |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
41 Usually, ctags can only append tags to an existing tag file, so Gutentags |
| 6 | 42 removes the tags for the current file first, to make sure the tag file is |
| 43 always consistent with the source code. | |
| 44 | |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
45 Also, Gutentags is clever enough to not stumble upon itself by triggering |
| 186 | 46 multiple ctags processes if you save files too fast, or your project is really |
| 6 | 47 big. |
| 48 | |
| 49 | |
| 50 ## Why? | |
| 51 | |
| 52 There are some similar Vim plugins out there ("vim-tags", "vim-autotag", | |
| 53 "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
|
54 I set for myself with Gutentags: |
| 6 | 55 |
| 56 * No other dependency than running Vim: no Python, Ruby, or whatever. | |
|
172
02a94ff0db57
Add CONTRIBUTING file.
Ludovic Chabant <ludovic@chabant.com>
parents:
52
diff
changeset
|
57 * Cross-platform: should work on at least Ubuntu, Mac, and Windows. |
|
18
b13e1141aa5c
Fix wording in `README`.
Ludovic Chabant <ludovic@chabant.com>
parents:
6
diff
changeset
|
58 * 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
|
59 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
|
60 * External process management: if the ctags process is taking a long time, don't |
|
172
02a94ff0db57
Add CONTRIBUTING file.
Ludovic Chabant <ludovic@chabant.com>
parents:
52
diff
changeset
|
61 run another one because I saved a file again. |
|
18
b13e1141aa5c
Fix wording in `README`.
Ludovic Chabant <ludovic@chabant.com>
parents:
6
diff
changeset
|
62 * 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
|
63 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
|
64 and functions. |
| 6 | 65 * 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
|
66 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
|
67 or Visual Studio or any other IDE. |
| 6 | 68 |
|
22
4e1b0253f71a
Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents:
18
diff
changeset
|
69 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
|
70 I don't want to have to think about it, and probably neither do you. |
| 6 | 71 |
| 72 | |
|
210
39547ffc8867
Add mention of `gutentags_plus` for Cscope users.
Ludovic Chabant <ludovic@chabant.com>
parents:
186
diff
changeset
|
73 # Related Projects |
|
39547ffc8867
Add mention of `gutentags_plus` for Cscope users.
Ludovic Chabant <ludovic@chabant.com>
parents:
186
diff
changeset
|
74 |
|
39547ffc8867
Add mention of `gutentags_plus` for Cscope users.
Ludovic Chabant <ludovic@chabant.com>
parents:
186
diff
changeset
|
75 * [gutentags_plus](https://github.com/skywind3000/gutentags_plus): handles |
|
39547ffc8867
Add mention of `gutentags_plus` for Cscope users.
Ludovic Chabant <ludovic@chabant.com>
parents:
186
diff
changeset
|
76 switching between `cscope` databases automatically before performing a search |
|
39547ffc8867
Add mention of `gutentags_plus` for Cscope users.
Ludovic Chabant <ludovic@chabant.com>
parents:
186
diff
changeset
|
77 query. |
|
39547ffc8867
Add mention of `gutentags_plus` for Cscope users.
Ludovic Chabant <ludovic@chabant.com>
parents:
186
diff
changeset
|
78 |
|
52
586c3a86adac
Added link to pathogen in readme
Rathesan Iyadurai <rad.iyadurai@gmail.com>
parents:
42
diff
changeset
|
79 [Pathogen]: https://github.com/tpope/vim-pathogen |
| 6 | 80 [ctrlp]: https://github.com/kien/ctrlp.vim |
| 81 |