.vim/pack/plugins/start/vim-rooter/doc/rooter.txt (ce8800e) - dotfiles.git

rooter.txt

*rooter.txt*  Plugin that changes to a buffer's root directory

____              __
                       / __ \____  ____  / /____  _____
                      / /_/ / __ \/ __ \/ __/ _ \/ ___/
                     / _, _/ /_/ / /_/ / /_/  __/ /
                    /_/ \_\\____/\____/\__/\___/_/

==============================================================================
Introduction                                    *rooter* *rooter-introduction*

Rooter is a Vim plugin which 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.

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                                                           *rooter-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                                           *rooter-configuration*

Which buffers trigger Rooter                                *g:rooter_targets*

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:
>
    let g:rooter_targets = '/,*.rb,*.haml,*.js'
<
Default: '/,*'

------------------------------------------------------------------------------
How to identify a root directory                           *g:rooter_patterns*

Default: ['.git', '_darcs', '.hg', '.bzr', '.svn', 'Makefile', 'package.json']

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 for when you put working projects in a common direcotry), prefix it
with `>`:
>
    let g:rooter_patterns = ['>Latex']
<
To exclude a pattern, prefix it with `!`.
>
    let g:rooter_patterns = ['!.git/worktrees', '!=src', '!build/env.sh', '!^fixtures']
<
List your exclusions before the patterns you do want.

------------------------------------------------------------------------------
Non-project files            *g:rooter_change_directory_for_non_project_files*

There are three options for non-project files/directories:

- 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'
<
Default: ''

------------------------------------------------------------------------------
Running automatically or manually                       *g:rooter_manual_only*
                                                               *:RooterToggle*
                                                                     *:Rooter*

To toggle between automatic and manual behaviour, use |:RooterToggle|. When
running manually you can invoke Rooter with |:Rooter|.

To make Rooter start in manual mode:
>
    let g:rooter_manual_only = 1
<
Default: 0

------------------------------------------------------------------------------
To change the change-directory command:                      *g:rooter_cd_cmd*
>
    let g:rooter_cd_cmd = 'lcd'
<
Default: "cd"

------------------------------------------------------------------------------
To stop Rooter echoing the project directory:          *g:rooter_silent_chdir*
>
    let g:rooter_silent_chdir = 1
<
Default: 0

------------------------------------------------------------------------------
Symlinks                                              *g:rooter_resolve_links*

By default Rooter doesn't resolve symbolic links in the file or directory
which triggers it.  To resolve links:
>
    let g:rooter_resolve_links = 1
<
Default: 0

==============================================================================
Using in other scripts                           *rooter-use-by-other-plugins*

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.

==============================================================================
vim:tw=78:sw=4:ts=8:ft=help:norl:

dotfiles.git

Added vim-rooter.