local_vimrc : A project management plugin for Vim

The aim of

local_vimrc

A project is defined by a root directory: everything under the root directory belongs to the project. No need to register every single file in the project, they all belong.

Purpose

This plugin presents a solution to Yakov Lerner's question on Vim ML. It searches for

_vimrc_local.vim

The Initial Question was:

Is it possible, after sourcing ~/.exrc, to traverse from

$HOME

down to cwd, and source

.exrc

from every directory if present ? (And if cwd is not under

$HOME,

just source

~/.exrc)

. What do I put into .vimrc to do this ?

Example: current dir is

~/a/b/c

. Files are sourced in this order: ~/.exrc, then ~/a/.exrc,

~/a/b/.exrc

,

~/a/b/c/.exrc

. No messages if some of

.exrc

does not exist.

Requirements / Installation

The latest version of this script requires vim 7.0 and lh-vim-lib v5.2.1+. UT v0.1.0 will be required to execute the unit tests.

The easiest way to install this plugin is with vim-addon-manager, or other plugin managers based on vim-pi, that support vim-addon-files -- as this script specifies its dependencies in vim-addon-file format.

ActivateAddons local_vimrc

Or with vim-flavor which also supports dependencies:

flavor 'LucHermitte/local_vimrc'

With Vundle

Plugin 'LucHermitte/lh-vim-lib'
Plugin 'LucHermitte/local_vimrc'

Or, with a NeoBundle version that doesn't support vim-pi yet: ```vim set rtp+=~/.vim/bundle/NeoBundle.vim/ call neobundle#begin(expand('~/.vim/bundle')) NeoBundleFetch 'Shougo/NeoBundle.vim' " Line required to force the right plugin name -> lh-vim-lib, and not trunk NeoBundle 'LucHermitte/lh-vim-lib', {'name': 'lh-vim-lib'} " Note: I haven't found the syntax to merge the two NeoBundle lines into one... NeoBundle 'LucHermitte/local_vimrc', {'depends': 'lh-vim-lib'} call neobundle#end()

NeoBundleCheck ```

Usage

Drop a

_vimrc_local.vim

_vimrc_local.vim

content

In other words. The project file is expected to be loaded (/sourced) every time you enter a buffer that corresponds to a file under the project root directory.

As a consequence, you may want to prevent multiple executions of parts the sourced file: almost everything shall remain identical and shall not need to be reset. However some plugins, like alternate (a.vim), rely on global variables to tune their behaviour. The settings (global variables) related to those plugins will require you to update their value every time -- if you expect to have settings that differ from a project to another. In order to support such project-aware setting,

local_vimrc

For your project settings prefer buffer-local mappings (

:h :map-

:h :abbreviate-

:h :command-buffer

:h :setlocal

:h local-variable

N.B.: if you are a plugin writer that want to support configuration variables that'll dynamically adapt to the current project settings, have a look at my

lh#option#get()

lh#ft#option#get()

You'll find examples of use in my dedicated repository.

Options

The behaviour of this plugin can be tuned with the following options:

• g:local_vimrc

  variable specifies the filenames and filepaths to be searched. The default is

  "_vimrc_local.vim"

  . It can contain a list (

  :h List

  ) of pathnames, or a simple string. It's meant to contain something that'll be relative to your current project root.
  This can contain a directory or a list of directories. In that case, in order to find any file named

  _vimrc_local.vim

  in directories named

  .config/

  at the root of current project directory, set the variable to

  vim
  let g:local_vimrc = ['.config', '_vimrc_local.vim']
  

• g:local_vimrc_options

  dictionary will hold four lists (

  whitelist

  ,

  blacklist

  ,

  asklist

  , and

  sandboxlist

  ) that define how security issues are handled. See Security concerns.

Other Features

Per-project settings and Template Expander Plugins

Sometimes we want to set variables (like a project source directory, or specific template files that override the default project file headers) before other plugins are triggered.
The typical use case will be from the shell: ```

There is a vimrclocal.vim file in /path/to/myproject/

cd /path/to/myproject/submodule42 gvim foobar.h ```

In order to use

myproject

vimrc_local

This plugin provides the

:SourceLocalVimrc

Automatic increment of

vimrc_local

script version number

When saved, if the

vimrc_local

s:k_version

vimrc_local

Security concerns

Thanks to the option

g:local_vimrc_options

_vimrc_local

The lists

The four lists

g:local_vimrc_options.whitelist

g:local_vimrc_options.blacklist

g:local_vimrc_options.asklist

g:local_vimrc_options.sandboxlist

_vimrc_local

• sourced, if it belongs to the whitelist,
• ignored, if it belongs to the blacklist,
• sourced, if it belongs to the asklist and if the end user says "Yes please, source this file!",
• sourced in the sandbox (

  :h sandbox

  ) if it belongs to the sandboxlist.
• or sourced if it belongs to no list (and if it's a local file, and not a file accessed through scp://, http://, ...).

Default settings

• Any

  _vimrc_local

  file in

  $HOME/.vim/

  will be sourced.
• However, files in

  $HOME/.vim/

  subdirectories will be ignored. This way, the end-user may specify options to use when editing vim files. See the file I use for instance.

• _vimrc_local

  files under

  $HOME

  are sourced only if the end-user interactively says "yes".

• _vimrc_local

  files under

  $HOME/..

  are ignored.

Tuning the lists

In order to blindly accept

_vimrc_local

.vimrc

" Sourcing the plugin
ActivateAddons local_vimrc
...
" Let's assume you put all projects you are working on in your
" corporation under $HOME/dev/my_corporation/
call lh#local_vimrc#munge('whitelist', $HOME.'/dev/my_corporation')
" But projects from 3rd parties/projects downloaded from the internet go
" into $HOME/dev/3rdparties/
call lh#local_vimrc#munge('blacklist', $HOME.'/dev/3rdparties')

If you want to override default settings, change them in your

.vimrc

ActivateAddons local_vimrc
...
" Remove $HOME from the asklist,
call lh#local_vimrc#filter_list('asklist', 'v:val != $HOME')
" Add it in the sandbox list instead
call lh#local_vimrc#munge('sandboxlist', $HOME)

" Clean the whitelist
let lh#local_vimrc#lists().whitelist = []

Alternatives

To be fair, there exist alternatives.

Modelines

Modelines are particularly limited: * We can't set variables (that tunes other (ft)plugins, like "should the braces of the for-snippet be on a newline ?"), * nor call functions from modelines (I don't limit myself to coding standards, I also set the makefile to use depending on the current directory) * Modelines aren't DRY. With modelines, a setting needs to be repeated in every file, if there are too many things to set or tunings to change, it will quickly become difficult to maintain, moreover, it will require the use of a template-expander plugin (which you should consider if you have several vimmers in your project). * Not every one uses Vim to develop. I don't want to be bothered by other people editor settings, why should I parasite theirs with modelines ?

.exrc

Vim natively supports

.exrc

:h .exrc

'exrc'

local_vimrc

.exrc

.exrc

Autocommands

It's possible to add autocommands in our

.vimrc

:set xxxxx

:let b:style='alman'

:source path/to/project_config.vim

If the autocommand executes simple commands (instead of sourcing a file), the solution won't scale when new commands will need to be added.

Autocommands won't scale either as a project location may vary : * On several machines a project may not be stored in the same path ; * When branches are stored in different paths, the

.vimrc

.vimrc

Project plugin

There exist a quite old (which does NOT mean bad) plugin dedicated to the management of project configuration. I've never used it, I won't be able to tell you why

local_vimrc

Plugins similar to local_vimrc

There exist many plugins with the same name or even with similar purpose. Just to name a few, there is for instance:

• Project oriented plugins:

  • Aric Blumer's good old project.vim plugin #69 which addresses other project concerns.
  • Tim Pope's Projectionist #4989,
  • Vim plugin for EditorConfig -- I plan eventually to provide a way to set project variables for this plugin,
  • My lh-vim-lib library plugin provides a new way to define projects and to tune plugins on a per project basis. For more complex plugins, both approaches can be mixed.

• local-vimrc plugins:

  • Marc Weber's vim-addon-local-vimrc
  • Markus "embear" Braun's local_vimrc #441,
  • thinca's localrc.vim #3393,
  • Tye Zdrojewski's Directory specific settings #1860.

TO DO

• Document how

  local_vimrc

  can be used with BuildToolsWrapper to support CMake based projects.
• Document how to mix definitions that need to be sourced only once, and

  local_vimrc

• doc&test: Support the definition of the project configuration in files put a separate directory (in order to help versioning them).
• doc: Support List of possible names for

  vimrc_local

  scripts
• Support checksum for project configuration from external sources

History

• v2.2.11
  • BUG: Use

    is_eligible

    on the right pathname (PR#12)
  • ENH: Don't source anything on directories
  • ENH: Don't source multiple times in a row with a same buffer
  • ENH: Improve logs
  • DOC: Miscelleanous improvments
  • BUG: Define "Edit Local Vimrc" mapping in buffers with a local vimrc.
• v2.2.10
  • ENH: Add 'edit local vimrc' in menu
  • ENH: Ignore buffer when

    ! lh#project#is_eligible()

  • ENH: Abort of quickfix and fugitive paths
  • PERF: Improve vim startup time
• v2.2.9 ENH: Simplify permission list management
• v2.2.8 BUG: Fix regression to support Vim7.3
• v2.2.7 ENH: Listen for BufRead and BufNewFile
• v2.2.6 ENH: Use lhvl 4.0.0 permission lists
  This implicitly fix asklist management
• v2.2.5 BUG: Fix #7 -- support of config in directory
• v2.2.4 Use new logging framework
  Fix issue when

  g:local_vimrc

  is a string.
• v2.2.3 Merge pull requests:
  • Incorrect addon-info extension (txt -> json)
    
  • Fix :SourceLocalVimrc path
• v2.2.2 Directory lists were incorrectly sorted (bis) + shellslash isssue
• v2.2.1 Directory lists were incorrectly sorted
• v2.2.0 Plugins functions moved to autoload.
  Verbose mode is activated by calling

  lh#local_vimrc#verbose(1)

• v2.1.1 Bug fix in support of regex in white/black/... lists.
• v2.1.0 Whitelist, blacklist & co
  Requires lh-vim-lib 3.2.4
• v2.0.1 Updated to match changes in lh-vim-lib 3.2.2.
  
• v2.0 Code refactored.
  -> Search function deported to lh-vim-lib
  -> dependencies to vim7 and to lh-vim-lib introduced
  Support for directory of localvimrcfiles added.
• v1.12 Previous versions of the plugin were hosted on my google-code / lh-misc repository.
• v1.11 Less errors are printed when the file loaded contains errors.
• v1.10

  s:k_version

  in

  vimrc_local

  files is automatically incremented on saving.
• v1.9 New command

  :SourceLocalVimrc

  in order to explicitly load the local-vimrc file before creating new files from a template (We can't just rely on

  BufNewFile

  as there is no guaranty

  vimrc_local

  's

  BufNewFile

  will be called before the one from the Template Expander Plugin => it's up to the TEP to call the function).
  
• v1.8 No more infinite recursion on file in non existent paths. + patch from cristiklein to support paths with spaces
• v1.7 Don't search a local vimrc with remote paths (ftp://, http, ... )
• v1.6 Sometimes root path is Z:\, which is quite odd
• v1.5 The auto-command is moved to the au-group

  LocalVimrc

• v1.4 Stop the recursion when we get to

  //

  or

  \\

  (UNC paths)
• v1.3 More comments.
  Trace of the directories searched when

  'verbose' >= 2

• v1.2 Stops at

  $HOME

  or at root (

  /

  )
• v1.1 Uses

  _vimrc_local.vim

• v1.0 Initial solution