sponsor Vim development Vim logo Vim Book Ad

indexer.tar.gz : Auto-generate tags for all files of project(s) and keep tags up-to-date

 script karma  Rating 176/55, Downloaded by 11576  Comments, bugs, improvements  Vim wiki

created by
Dmitry Frank
script type
I've published a detailed article about Indexer + Vimprj usage, you might want to read it: https://dmitryfrank.com/articles/vim_project_code_navigation


This plugin can work in two ways:
1) independently
2) as add-on for project.tar.gz (vimscript #69)

In both ways, it provides painless automatic tags generation for whole project(s) and keeps tags up-to-date.

IMPORTANT: you need patched version of ctags (5.8.1) to make this plugin work correctly with C/C++ files, because of bug in ctags 5.8. You can read detailed info about this bug and download patched version here: http://dfrank.ru/ctags581/en.html

This plugin can be very useful when it's used together with plugins omnicppcomplete (for c, c++ development), code_complete.vim and other plugins that use tags.  You also will be able to jump from function call to its definition just by pressing Ctrl-] or g]

As i said, Indexer can work as add-on for project.tar.gz plugin ( vimscript #69 ). Indexer reads project file, parses it and builds tags for all files in project. But it also works fine without project.tar.gz.

Actually, if you use project.tar.gz plugin and your projects file is default (~/.vimprojects), then setting Indexer up is very easily: you can just install this plugin, start Vim and open any file from your project. Indexer will detect that opened file is a file from project and automatically start ctags for each file in this project.  It also set &path and &tags options for Vim.

If you use project.tar.gz, but you have another projects file, you should set option g:indexer_projectsSettingsFilename in your vimrc.

If you don't use project.tar.gz then you can use ".indexer_files" to define projects and files to index.  Default location of this file is "~/.indexer_files". You can change it by modifying variable g:indexer_indexerListFilename

Syntax of this file is simple, probably the best way to explain it is to show an example:

NOTE! Since Indexer 4.10 syntax of .indexer_files is changed a bit, to make ctags work much more effectively.  However, old syntax will work too, for backward compatibility.  If you used Indexer before with .indexer_files, please read this:
:help indexer-syn-change-4.10

--------------------- example ~/.indexer_files -----------------------


   option:ctags_params = "--languages=c++"

I hope all is obvious:
There's two projects: CoolProject and AnotherProject.
CoolProject just contains ALL files from "/home/user/myproject".
AnotherProject is configured more complicated.
It specifies additional parameter for ctags: "--languages=c++".
It is needed to make ctags ignore all files except c++ sources.
I would recommend you to read and understand ctags help, to be able to write perfect configuration for your projects.
You can read it here: http://ctags.sourceforge.net/ctags.html
The options you need to know first is the following two:

If you have many projects and you are lazy to put every project in
this file, you can put in your ~/.indexer_files something like this:

--------------------- example ~/.indexer_files -----------------------


The keyword is PROJECTS_PARENT.
In this way, each directory in ~/workspace will be interpreted as separate
project, and you can open any file from any project in ~/workspace, and the
whole proper project will be indexed.

Please note: suggested ctags options is tested with ctags 5.8. As far as i
know, option --languages is marked as deprecated in ctags 5.9, but i still did
not test it, because the latest version on http://ctags.sourceforge.net is
still 5.8. I hope i will have time for this soon.

Indexer 3.0 and later supports open several files from several projects. For example, a little story.

You have two projects: "project1" and "project2", and you use "~/.indexer_files".

1) you open file1 from project1.
   Indexer generates tags for all files from project1 and set &tags:
2) you open file2 from the same project1.
   Indexer just notes that file2 is file from project1.
   &tags does not change.
3) you open file3 from project2.
   Indexer generates tags for all files from project2 and set &tags:
4) you switch to buffer with file1.
   Indexer does not generate any tags, it just changes &tags to
5) you switch to buffer with file3.
   Indexer changes &tags back to ~/.indexer_files_tags/project2 .

So, you should not care about your projects. It just works. If you have some projects with subprojects, i would recommend you to use .vimprj directory with specific settings for your project, in which you can set any options such as &tags, &tabstop, etc. More detailed: read :help vimprj

Actually, Indexer sets &path for needed project when you swith to new buffer, not only &tags.


It is successfully tested on Vim 7.3, on the following systems:
*) Archlinux
*) Ubuntu 10.4
*) Windows XP
*) Mac OS X Lion

Please, if you have another system configuration and all works fine for you,
please send to me your configuration, i'll update text on this page.

If you have any troubles using this plugin, feel free to email me.
You also can contact me in irc:
server: irc.freenode.net
channel: #vim
nick: dfrank


Development mercurial repository: http://hg.dfrank.ru/vim/bundle/indexer_development
Stable git repository: https://github.com/vim-scripts/indexer.tar.gz (Note that this repository is auto-generated by http://vim-scripts.org as a mirror of http://www.vim.org)

install details
There's some dependencies:
1) script-library DfrankUtil (vimscript #3884)
2) script Vimprj (vimscript #3872)

Functionality of the Vimprj plugin has been implemented in Indexer earlier, but now Indexer functionality is divided in two plugins: Indexer and Vimprj.
If you don't need Vimprj's functionality, just install Vimprj and do not use it. It will not disturb you.

And i suggest you to use pathogen (vimscript #2332) to manage your plugins.

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
indexer-4.16.zip 4.16 2015-10-12 7.0 Dmitry Frank I've published a thorough article on advanced Indexer + Vimprj usage, you might want to check it out: http://dmitryfrank.com/articles/vim_project_code_navigation

New in this version:

- Added an option dontUpdateTagsIfFileExists that prevents Indexer from re-generating tags if tags file already exists. Useful on large projects;
- Added several example projects that illustrate Indexer + Vimprj usage. See the aforementioned article for details
indexer-4.15.zip 4.15 2012-09-01 7.0 Dmitry Frank *) Fixed issue with background tags generation in terminal vim, thanks to John Jarvis.
*) Fixed some little appearance bugs
*) Compatibility with latest vimprj plugin (1.08)
indexer-4.14.tar.gz 4.14 2012-01-31 7.0 Dmitry Frank *) Nested projects is now supported. If one project is a subdir(s) of another one, then only nested project will be used for inner files.  This will also work for PROJECTS_PARENT. I mean, you can set up your .indexer_files just like that:


and then each dir in ~/dev will be a separate project, and each dir in ~/dev/SomeProject will also be sepate project.

*) Some bugfix
indexer-4.13.tar.gz 4.13 2012-01-29 7.0 Dmitry Frank *) MacVim is now supported. Thanks to Asis Hallab for bugreport and for help to implement it.
*) Added new option g:indexer_vimExecutable, it is needed if you want your
custom vim to be executed instead of standard "vim" (or "mvim" on MacVim). Thanks to Asis Hallab again for nice idea.
indexer-4.12.tar.gz 4.12 2012-01-18 7.0 Dmitry Frank *) Bugfix: file .indexer_files wasn't parsed if you have custom filename for it with "~" in the path. Thanks to Dmitry Yudin for reporting this.
*) Bugfix: syntax file for .indexer_files had fileformat "dos". Changed to "unix".
indexer-4.11.tar.gz 4.11 2012-01-15 7.0 Dmitry Frank *) Optimization: when there's many projects available, opening new file was too slow. Now this is solved.
*) Please download latest version 1.06 of Vimprj script (vimscript #3872).
*) Yet another dependency added: script-library DfrankUtil (vimscript #3884). Sorry if you are bored by all these dependencies, but now i really need to put my common code in one place.
indexer-4.10.tar.gz 4.10 2012-01-14 7.0 Dmitry Frank *) Optimized work with .vimprojects file (with project.tar.gz plugin) on rather large projects: now, Indexer generates filelist, stores it into the file and passes it to ctags with "-L" key, instead of passing each file directly in command line. This makes ctags work much faster, because in earlier versions it was called several times with "-a" key if command is too long.
*) Optimized work with .indexer_files file: syntax of this file changed a bit, to make ctags settings much more effective. However, old syntax works too, for backward compatibility reasons. If you used Indexer before with .indexer_files, then I would strongly recommend you to read :help indexer-syn-change-4.10 .
*) Added syntax file for .indexer_files .
If you found a bug, please report it to me.
indexer-4.04.tar.gz 4.04 2012-01-07 7.0 Dmitry Frank *) IMPORTANT NOTE: since version 4.00 there is a dependency: plugin vimprj ( vimscript #3872 )
*) Some performance improvements
*) Many, many refactor. Previous versions was laggy in some cases when used on remote machines, now it is solved. Thanks to Thiago Bellini for bugreports and for being a beta-tester.
indexer-3.18.tar.gz 3.18 2011-09-14 7.0 Dmitry Frank * Added option g:indexer_changeCurDirIfVimprjFound.
If anyone wants to make Indexer not to change current dir automatically if .vimprj directory is found, then you can specify in your vimrc:

let g:indexer_changeCurDirIfVimprjFound = 0
indexer-3.17.tar.gz 3.17 2011-08-21 7.0 Dmitry Frank * Optimization change: with .indexer_files default value of g:indexer_ctagsDontSpecifyFilesIfPossible is 1, but with .vimprojects default value is 0.
indexer-3.16.tar.gz 3.16 2011-08-18 7.0 Dmitry Frank * Bugfix: on FreeBSD we should check executable 'exctags' before 'ctags', because of 'ctags' is also present, but it is not actually Exuberant ctags. Thanks to Olivier Szika for bugreport.
indexer-3.14.tar.gz 3.14 2011-04-26 7.0 Dmitry Frank * Bugfix: $INDEXER_PROJECT_ROOT wasn't work in .vimprojects file. Thanks to Alexander Pazdnikov for bugreport.
indexer-3.12.tar.gz 3.12 2011-03-26 7.0 Dmitry Frank Some improvements in error reporting:
* error if no ctags is available in the PATH,
* warning when ctags returns error.
indexer-3.11.tar.gz 3.11 2011-03-24 7.0 Dmitry Frank * Bugfix: if "noswapfile" option is set, then tags wasn't generated. Thanks to Thiago Bellini for help and persistence =)
* Bugfix: :IndexerFiles command didn't work.
indexer-3.1.tar.gz 3.1 2011-03-21 7.0 Dmitry Frank * Bugfixes
* When no servername is present, tags generate in Vim thread, not in background. (because i don't know how to execute remote command in Vim without servername. If anyone know, please contact me)
indexer-3.0.tar.gz 3.0 2011-03-17 7.0 Dmitry Frank * Multiple projects supported. For example, you open file1 from one project, and then you open file2 from second project. Then, when you switch to file1, &tags will be set to tags file for first project, and when you switch to file2, then &tags will be set back for second project. You should not care about it.
* Background tags generation (thanks to Thiago Bellini for pointing me at needed script). You have not to wait every time while ctags is working.
* By default, on Windows tags generates always for whole project, because of bugs in all Windows versions of Sed i have. Actually, now this isn't problem, because of tags generates in background.
* Tags file is sorted now. In Indexer 2.x it was unsorted because of bugs in Sed, and to make tags unsorted was workaround. As i already said, in Linux Sed works fine, and on Windows Sed doesn't uses by default, so, tags file can be sorted.
indexer-2.01.tar.gz 2.01 2010-11-15 7.0 Dmitry Frank The only thing changed is that maximum command length on Windows systems decreased from 8186 to 8000, because of on some systems 8186 is too large, i don't know, why. I hope 8000 will work at all Windows systems (XP or later).
Thanks to Dan Price again.
indexer-2.0.tar.gz 2.0 2010-11-11 7.0 Dmitry Frank IMPORTANT! You need patched version of ctags (5.8.1) to make this version of plugin work correctly, because of bug in ctags 5.8. You can read detailed info about this bug and download pathed version here: http://dfrank.ru/ctags581/en.html

* Solved trouble with large projects: if there's very many files in your project and command to ctags is too long, then ctags calling several times with "-a" key. (Again: to make this work you need patched version of ctags);
* option "DontSpecifyFilesIfPossible" working with .vimprojects file too now
* when using append at filesave, old tags removing from tags file by SED. (this is needed to exclude garbage in tags file)
Thanks to Dan Price for ideas and inspiration :)
indexer-1.8.tar.gz 1.8 2010-09-26 7.0 Dmitry Frank * Fixed some bugs (thanks to Julian Kooij)
indexer-1.7.tar.gz 1.7 2010-09-10 7.0 Dmitry Frank * Fixed bug that caused not all comments in .vimprojects was parsed correctly (thanks to Alexander Q).
* Fixed some little bugs.
indexer-1.6.tar.gz 1.6 2010-09-01 7.0 Dmitry Frank * For every projects creating unique tags file to avoid conflicts (thanks to Torkve)
indexer-1.5.tar.gz 1.5 2010-08-31 7.0 Dmitry Frank * Fixed bug that caused paths with spaces wasn't parsed correctly.
* Added PROJECTS_PARENT .indexer_files feature (possibility to define directory with many projects inside).
indexer-1.4.tar.gz 1.4 2010-08-30 7.0 Dmitry Frank Fixed bug that caused paths with "~" wasn't parsed correctly (thanks Makoto Nokata)
indexer-1.3.tar.gz 1.3 2010-08-30 7.0 Dmitry Frank * Fixed some bugs
* Default name of project settings directory has been changed from ".vim" to ".vimprj" to avoid conflicts with standard ~/.vim directory. If you are using this feature and your project settings dir is ".vim", please rename it.
indexer-1.2.tar.gz 1.2 2010-08-26 7.0 Dmitry Frank Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
Vim at Github