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.

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.

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'

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.

Note that using a symlink as a rooter pattern will probably not do what you want. Vim resolves symlinks when evaluating file paths so you will end up with the symlink source regarded as the root, not its target.

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

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

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