Vimprj

Vimprj is a Vim plugin that helps you manage options for multiple projects.

Consider reading the article Vim: convenient code navigation for your projects, which explains the topic on Indexer + Vimprj usage very thoroughly.

Many times I faced a problem. That's the story:

I'd like to use 3-space indent in my projects. No tabs, exactly three spaces. One day I need to work on another project written by someone else, and there's 4-space indent. Or maybe tabs.

I need to work on this project too, and of course I need to stick to existing formatting options.

I strongly dislike that i have to switch these options by hand: &shiftwidth, &tabstop, &expandtab.

So I decided to write this plugin to make my life easier.

The project is hosted at bitbucket. Stable versions are at vim.org. Download source code from there and install it as any other Vim plugin.

There is a dependency: a simple library Vim-DFUtil.

Usage of this plugin is quite easy. In the root directory of your project, you need to create new directory .vimprj and put any number of files *.vim inside. Every time you open new file in Vim, plugin looks for .vimprj directory up by tree, and if it is found, then all *.vim files from it will be sourced.

Or, you can just put file .vimprj, then this file will be sourced. Name .vimprj can be changed by editing option g:vimprj_dirNameForSearch.

For my own projects, I usually create the file .vimprj/my.vim with the following contents:

let &tabstop = 3
let &shiftwidth = 3
set expandtab

My .vimprj directory also contain tags and other project-specific files, so, I prefer to use directory instead of just one file.

Now, when I open file from my project, file my.vim is sourced. When I open file from some another project, its own file with options is sourced too. Of course, when I switch buffer, this files are sourced too if project is changed.

So, I always have correct options, and simultaneus work on several projects with different formatting options is not painful anymore for me.

And, of course, you can use it not only to manage formatting options. For instance, in some projects I use mapping <F9> to open project window (from plugin Project), but for some java projects i use Eclim, and <F9> should be mapped to another command (to open Eclim's project). All these options can also be specified in .vimprj dir.

Attentive reader might notice an issue: as I already said, I would like to use shiftwidth=3. Say, I open some file from my project with shiftwidth=3. Everything's fine here. Then I open file from another project with shiftwidth=4. Things are still OK. Then I open some file not from any project (there's no .vimprj directory). Of course, I would like to use my favorite options (that is, shiftwidth=3), but current shiftwidth is 4, because it was changed when I opened last project. It leads us to the fact that we should define default options. But here, let me make a digression.

Plugin provides some hooks for any other plugin. Namely, plugin Vim-Indexer (since version 4.0) uses these hooks to provide correct behavior when user works on multiple project simultaneusly.

Right now I have not yet documented all of them, because of lack of free time, but I just tell you about one hook that allows you to specify your default options.

It's SetDefaultOptions hook. Now I'm going to show you an example. You might want to paste this example to your .vimrc, and just specify your own default options instead of mine ones:

function! <SID>SetMainDefaults()
 
   " your default options go here!
   set tabstop=3
   set shiftwidth=3
   set expandtab
 
endfunction
 
call <SID>SetMainDefaults()
 
" initialize vimprj plugin
call vimprj#init()
 
" define a hook. note that 'main_options' is an arbitrary string,
" each entity that uses these hooks should pick an unique name.
function! g:vimprj#dHooks['SetDefaultOptions']['main_options'](dParams)
   call <SID>SetMainDefaults()
endfunction

Now, Vimprj plugin will call your function SetMainDefaults just before sourcing your .vimprj directory, and when you open file not from any project.

If you are interested about other hooks, you can just look how they are used in Vim-Indexer plugin.

For further information, such as options and so on, refer to :help vimprj.