Skip to content

airblade/vim-rooter

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.

About

Changes Vim working directory to project root.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published