unix9000 / vim-rooter

Changes Vim working directory to project root (identified by presence of known directory or file).

Rooter

Rooter changes the working directory to the project root when you open a file or directory.

The project root is identified by:

• being a known directory;
• or the presence of a known directory, such as a VCS directory;
• or the presence of a known file, such as a Rakefile.

Out of the box it knows about git, darcs, mercurial, bazaar, and subversion, but you can configure it to look for anything.

Use

By default you don't need to do anything: vim-rooter will change the working directory automatically and echo the new working directory.

You can turn this off (see below) and use the :Rooter command to invoke vim-rooter manually.

When Rooter changes the working directory it emits the autocmd user event RooterChDir.

Non-project files

There are three options for non-project files/directories:

• Don't change directory (default).

  let g:rooter_change_directory_for_non_project_files = ''

• Change to file's directory (similar to autochdir).

  let g:rooter_change_directory_for_non_project_files = 'current'

• Change to home directory.

  let g:rooter_change_directory_for_non_project_files = 'home'

Configuration

vim-rooter will unset &autochdir if it's set.

By default all files and directories trigger vim-rooter. Configure a comma separated list of file patterns to specify which files trigger vim-rooter. Include / to trigger vim-rooter on directories.

" directories and all files (default)
let g:rooter_targets = '/,*'

" ignore directories; all files
let g:rooter_targets = '*'

" ignore directories; yaml files
let g:rooter_targets = '*.yml,*.yaml'

" directories and yaml files
let g:rooter_targets = '/,*.yml,*.yaml'

To stop vim-rooter changing directory automatically:

let g:rooter_manual_only = 1

To specify how to identify a project's root directory:

let g:rooter_patterns = ['Rakefile', '.git/']

Vim-rooter checks the patterns depth (height?) first. Directories must have a trailing slash. To work correctly with git submodules place .git before .git/.

If a rooter pattern directory is one of the current file's ancestors, it is taken to be the project root. Otherwise, vim-rooter looks for an ancestor containing the given pattern directory/file.

To change directory for the current window only (:lcd):

let g:rooter_use_lcd = 1

To stop vim-rooter echoing the project directory:

let g:rooter_silent_chdir = 1

By default vim-rooter doesn't resolve symbolic links. To resolve links:

let g:rooter_resolve_links = 1

Using root-finding functionality in other scripts

The public function FindRootDirectory() returns the absolute path to the root directory as a string, if a root directory is found, or an empty string otherwise.

If that's all you need you can turn off the directory-changing behaviour with:

let g:rooter_manual_only = 1

Installation

Install into ~/.vim/plugin/rooter.vim or, if you're using Pathogen, into ~/.vim/bundle/rooter.vim.