sponsor Vim development Vim logo Vim Book Ad

vimprj : Plugin for managing options for different projects

 script karma  Rating 43/17, Downloaded by 6755  Comments, bugs, improvements  Vim wiki

created by
Dmitry Frank
script type
Please note: there's dependency DfrankUtil (vimscript #3884)

                                  * * *

I've published a thorough article on Vimprj + Indexer usage; consider reading it: http://dmitryfrank.com/articles/vim_project_code_navigation

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

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

I need to work on this project too, and i need to keep existing formatting

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

And then i decided to write this plugin to make my life easier.

Using this plugin is quite easy. You need to create in the root directory of
your project new directory ".vimprj" and put any number of files "*.vim" in it.
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 .

Usually for my own projects i create just one 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'd prefer to use directory instead of just one file.)

and for other projects i create file with appropriate options.

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

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 my projects i use mapping <F9> to open project window
(from plugin project.tar.gz), 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 stated in .vimprj dir.

There is an issue: as i already said, i would like to use shiftwidth=3. Say,
i open some file from my project with shiftwidth=3. All ok here. Then i open
file from another project with shiftwidth=4. All is 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 (e.g. shiftwidth=3), but now 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. For instance, plugin
Indexer (since version 4.0) uses these hooks to provide correct behavior
when user works on different project simultaneusly.

Right now i have not documented yet all these hooks, because of lack of
free time, but i just tell you about one hook, to let you specify your
default options.

This is a hook "SetDefaultOptions". Now i show you an example. Please insert
in your .vimrc the following, just specify your own default options instead of
mine ones: >

   function! <SID>SetMainDefaults()

      " your default options goes here!
      set tabstop=3
      set shiftwidth=3
      set expandtab


   call <SID>SetMainDefaults()

   " initialize vimprj plugin
   call vimprj#init()

   " define a hook
   function! g:vimprj#dHooks['SetDefaultOptions']['main_options'](dParams)
      call <SID>SetMainDefaults()

Now vimprj plugin will call your function SetMainDefaults just before sourcing
all *.vim files from .vimprj directory, and when you open file not from any

If you are interesting about another hooks, you can just look how is they used
in Indexer plugin (since version 4.0). I hope one day i will write all this here. =)

Please NOTE: by default this plugin will change your current dir
to project's dir if ".vimprj" is found.
More detailed read in help: type  :help vimprj-options , look for an option

Development repository (Mercurial) : http://hg.dfrank.ru/vim/bundle/vimprj
Stable git repository: https://github.com/vim-scripts/vimprj (Note that this repository is auto-generated by http://vim-scripts.org as a mirror of http://www.vim.org)
install details
There's dependency: script-library DfrankUtil (vimscript #3884)

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
vimprj-1.11.zip 1.11 2015-10-11 7.0 Dmitry Frank I've published a thorough article on Vimprj + Indexer usage, you might want to check it out: http://dmitryfrank.com/articles/vim_project_code_navigation

New in this version:

- Added $VIMPRJ_PROJECT_ROOT variable, which is set to the root of the currently active project;
- Default behavior changed: now, by default, Vimprj doesn't touch your current working directory. Set g:vimprj_changeCurDirIfVimprjFound if you want it to do so.
vimprj-1.10.zip 1.10 2014-02-22 7.0 Dmitry Frank Fixed issue: there was an error if path contains spaces (thanks to Alexey Shevchenko)
vimprj-1.09.zip 1.09 2013-01-20 7.0 Dmitry Frank Fixed issue: if quickfix window is opened, and user compiles current file (types :make ), then vimprj swithed to the 'default' settings.
vimprj-1.08.zip 1.08 2012-09-01 7.0 Dmitry Frank * Please note: if you use plugin Indexer, then you need to update it to the latest version (4.15) because some hooks logic changed.
* Nested projects are supported, and added new hook "OnAfterSourcingVimprj". I would recommend you to read nice article by Francisco Lopes da Silva: http://goo.gl/vkCBc , there you can see well-explained example how to use these hooks effectively. Sorry for the lack of time to add all the hooks to docs. Great thanks to Francisco.
vimprj-1.06.tar.gz 1.06 2012-01-15 7.0 Dmitry Frank *) Refactor. Added new dependency: script-library DfrankUtil (vimscript #3884)
vimprj-1.05.tar.gz 1.05 2012-01-14 7.0 Dmitry Frank *) Added :VimprjInfo command that echoes current project root (project root is a directory which contains .vimprj directory or file)
*) Fix: new file creation is parsed correctly now.
vimprj-1.03.tar.gz 1.03 2012-01-09 7.0 Dmitry Frank Added possibility to use just one file ".vimprj" (of course, name can be changed) instead of a whole directory, because in most cases people might want to create just one file with options, and ".vimprj/rc.vim" looks too obtrusive. Thanks to Aleksey Zapparov for nice remark.
vimprj-1.02.tar.gz 1.02 2012-01-07 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.