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.
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
Rooter will unset
&autochdir if it's set.
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
"acwrite". To stick to normal files:
let g:rooter_buftypes = ['']
How to identify a root directory
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.
Don't change directory (default).
let g:rooter_change_directory_for_non_project_files = ''
Change to file's directory (similar to
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
To make Rooter start in manual mode:
let g:rooter_manual_only = 1
By default vim-rooter uses
:cd to change directory. To use
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.