Rooter

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

The project root can be identified by:

• being a known directory;
• having a known directory or file;
• being a subdirectory of a known directory.
• being a direct subdirectory of a known directory

You can also exclude directories.

For a file or directory which doesn't have a root, Rooter can: do nothing; change to the file's directory (similar to autochdir); or change to your home directory.

Usage

By default you don't need to do anything: 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 Rooter manually.

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

Rooter will unset &autochdir if it's set.

Configuration

Which buffers trigger Rooter

By default all files and directories trigger Rooter. Alternatively, set g:rooter_targets to a list of file path patterns which should trigger Rooter. Use a literal / to match directory buffers. For example:

" Everything (default)
let g:rooter_targets = ['/', '*']

" Directories and everything under /home
let g:rooter_targets = ['/', '/home/*']

Patterns are tried in order until one of them matches. To specify a negative pattern, prefix it with a !. If no patterns match, Rooter is not triggered:

" Everything (default), except files under /tmp
let g:rooter_targets = ['!/tmp/*', '/', '*']

Comma-separated lists are also accepted:

" All files
let g:rooter_targets = '*'

" YAML files
let g:rooter_targets = '*.yml,*.yaml'

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

Which buffer types trigger Rooter

Rooter only runs in buffer types where it makes sense to look for a root directory.

A normal file has an empty 'buftype'. Directory browsing plugins often set the 'buftype' to "nofile", "nowrite", or "acwrite". To stick to normal files:

let g:rooter_buftypes = ['']

How to identify a root directory

Set g:rooter_patterns to a list of identifiers. They are checked breadth-first as Rooter walks up the directory tree and the first match is used.

To specify the root is a certain directory, prefix it with =.

let g:rooter_patterns = ['=src']

To specify the root has a certain directory or file (which may be a glob), just give the name:

let g:rooter_patterns = ['.git', 'Makefile', '*.sln', 'build/env.sh']

To specify the root has a certain directory as an ancestor (useful for excluding directories), prefix it with ^:

let g:rooter_patterns = ['^fixtures']

To specify the root has a certain directory as its direct ancestor / parent (useful when you put working projects in a common directory), prefix it with >:

let g:rooter_patterns = ['>Latex']

To exclude a pattern, prefix it with !.

let g:rooter_patterns = ['!.git/worktrees', '!=extras', '!^fixtures', '!build/env.sh']

List your exclusions before the patterns you do want.

Non-project files

• 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'
  

Ignored files

By default Rooter does not take into account .gitignore.

To make Rooter aware of ignored files:

let g:rooter_ignore = 1

When this is set, and the file in question is ignored by git, Rooter acts as if .git is not in g:rooter_patterns.

Support for other VCSs' ignores could be added.

Running automatically or manually

To toggle between automatic and manual behaviour, use :RooterToggle.

To make Rooter start in manual mode:

let g:rooter_manual_only = 1

Miscellaneous

By default vim-rooter uses :cd to change directory. To use :lcd or :tcd instead:

let g:rooter_cd_cmd = 'lcd'

To stop Rooter echoing the project directory:

let g:rooter_silent_chdir = 1

By default Rooter doesn't resolve symbolic links in the file or directory which triggers it. To do so:

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.