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. Configure a comma separated list of patterns to specify which files trigger. Include / to trigger on directories. For example:

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

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

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.

hwgao/vim-rooter