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 RooterChDir
.
For triggered buffers, rooter will unset &autochdir
if it's set. For other buffers, rooter respect user's setting of &autochdir
.
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'
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 = ['!=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
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'
To toggle between automatic and manual behaviour, use :RooterToggle
.
To make Rooter start in manual mode:
let g:rooter_manual_only = 1
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
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.