Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/airblade/vim-rooter

Changes Vim working directory to project root.
https://github.com/airblade/vim-rooter

vim

Last synced: 3 days ago
JSON representation

Changes Vim working directory to project root.

Awesome Lists containing this project

README 

        
# 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:



```viml

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



```viml

" Everything (default), except files under /tmp

let g:rooter_targets = ['!/tmp/*', '/', '*']

```



Comma-separated lists are also accepted:



```viml

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



```viml

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 `=`.



```viml

let g:rooter_patterns = ['=src']

```



To specify the root has a certain directory or file (which may be a glob), just give the name:



```viml

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 `^`:



```viml

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 `>`:



```viml

let g:rooter_patterns = ['>Latex']

```



To exclude a pattern, prefix it with `!`.



```viml

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).



    ```viml

    let g:rooter_change_directory_for_non_project_files = ''

    ```



- Change to file's directory (similar to `autochdir`).



    ```viml

    let g:rooter_change_directory_for_non_project_files = 'current'

    ```



- Change to home directory.



    ```viml

    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:



```viml

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:



```viml

let g:rooter_manual_only = 1

```



### Miscellaneous



By default vim-rooter uses `:cd` to change directory.  To use `:lcd` or `:tcd` instead:



```viml

let g:rooter_cd_cmd = 'lcd'

```



To stop Rooter echoing the project directory:



```viml

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:



```viml

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.