Mercurial > vim-gutentags

annotate README.md @ 227:c64e8847b4e1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Make it more obvious what trace is coming from the background job.
author Ludovic Chabant <ludovic@chabant.com>
date Sun, 11 Nov 2018 21:48:15 -0800
parents 39547ffc8867
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
1
22
4e1b0253f71a Renamed project to "Gutentags" (thanks Sylvain!).
Ludovic Chabant <ludovic@chabant.com>
parents: 18
diff changeset
2 # Gutentags
6
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
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
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
5 files in Vim. It will (re)generate tag files as you work while staying
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
6 completely out of your way. It will even do its best to keep those tag files
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
7 out of your way too. It has no dependencies and just works.
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
8
172
02a94ff0db57 Add CONTRIBUTING file.
Ludovic Chabant <ludovic@chabant.com>
parents: 52
diff changeset
9
6
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
10 ## How?
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
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
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
13 [Pathogen][], so you can go:
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
14
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
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
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
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
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
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
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
25
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
26
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
27 ## What?
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
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
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
30 your project. To do this, it will locate well-known project root markers like
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
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
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
33 other plugins, like [CtrlP][].
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
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
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
36 will make sure the tag file for that project is up to date. Then, as you work
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
37 in files in that project, it will partially re-generate the tag file. Every
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
38 time you save, it will silently, in the background, update the tags for that
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
39 file.
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
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
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
42 removes the tags for the current file first, to make sure the tag file is
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
43 always consistent with the source code.
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
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
becdd3c867c7 fix typo
Florian Heiderich <florian@heiderich.org>
parents: 183
diff changeset
46 multiple ctags processes if you save files too fast, or your project is really
6
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
47 big.
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
48
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
49
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
50 ## Why?
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
51
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
52 There are some similar Vim plugins out there ("vim-tags", "vim-autotag",
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
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
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
55
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
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
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
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
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
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
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
71
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
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
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
80 [ctrlp]: https://github.com/kien/ctrlp.vim
ec87439fc784 Add README file.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
81