Skip to content

airblade/vim-rooter

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

Instead of specifying which 'buftype's to ignore, specify which ones to
heed.

See #132.
4f52ca5

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
doc
January 13, 2023 14:57
January 13, 2023 14:57
May 4, 2016 12:36
October 27, 2016 15:13

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.

About

Changes Vim working directory to project root.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published