by Marco Hinz
Twitter: https://twitter.com/_mhinz_
IRC: mhi^ (Freenode)
If you use any of my plugins, please star them on github. It's a great way of getting feedback and gives me the kick to put more time into their development. If you encounter any bugs or have feature requests, just open an issue report on Github.
vim-toplevel helps changing to the root directory of a version control system or any specified custom directory.
There are really just two commands that try to accomplish the same: changing to a certain root directory. Both use different approaches, though.
You'll almost always want to use :Cd
, because it should be faster since it
doesn't have to run external programs.
:Root
can be used in case your hg repository contains a directory (or
symlink) named .git
or even .hg
although it isn't the one from the root
directory. :Cd
would use the wrong directory in such cases.
NOTE: Found root directories will be cached, so frequent switching between
buffers doesn't effect performance, even when you set up an autocmd to trigger
on BufEnter. For an example see :h toplevel-section-example
.
:Cd change directory for the current window
:Cd! change directory for all windows
This command uses the builtin function finddir() to get a certain root repository and change to it. It starts searching upwards from the directory of the current buffer.
:Root change directory for the current window
:Root! change directory for all windows
This command uses the builtin function system() to start external programs (e.g. git or hg) to get the VCS root directory and change to it.
All configuration is done through one variable: g:toplevel
.
let toplevel = {
\ 'cdlist': [
\ ['.git', 'finddir' ],
\ ['_darcs', 'finddir' ],
\ ['.svn', 'finddir' ],
\ ['.fossil', 'findfile'],
\ ]
\ ]
This option tells :Cd
what to do. It's a list of lists that contain two
elements:
1) name The name of the file or directory to look for.
2) type This specifies whether to look for a file or directory.
It should be either 'finddir' or 'findfile'.
:Cd
will test for these files/directories in the given order.
let toplevel = { 'rootlist': ['bzr', 'hg'] }
This option tells :Root
what to do. It's a list of external programs to use.
:Root
will use these programs in the given order.
NOTE: Explicitely setting this variable will lead to less runtime checks and a tad more performance.
Currently supported:
'git'
'hg'
'bzr'
let toplevel = { 'vimshell': 1 }
If you're on Windows and have vim-misc/vim-shell installed, enabling this will
avoid the annoying flickering of the cmd.exe popping up for the fraction of a
second. Only makes a difference for :Root
, not for :Cd
.
If you have no preferred installation method, I suggest using tpope's pathogen. Afterwards installing vim-toplevel is as easy as pie:
$ git clone https://github.com/mhinz/vim-toplevel ~/.vim/bundle/vim-toplevel
It works without any configuration, but you might want to look into the documentation for further customization:
:Helptags " rebuilding tags files
:h toplevel
let toplevel = {
\ 'cdlist': [
\ ['.git', 'finddir' ],
\ ['_darcs', 'finddir' ],
\ ['.svn', 'finddir' ],
\ ['.fossil', 'findfile'],
\ ],
\ 'rootlist': [
\ 'hg',
\ 'bzr',
\ ],
\ 'vimshell': 0,
\ }
augroup toplevel
autocmd BufEnter * silent Cd
augroup END
This example does exactly the same as the one given above, but uses a slightly different syntax:
let toplevel = {}
let toplevel.vimshell = 0
let toplevel.rootlist = ['hg', 'bzr']
let toplevel.cdlist = [
\ ['.git', 'finddir' ],
\ ['_darcs', 'finddir' ],
\ ['.svn', 'finddir' ],
\ ['.fossil', 'findfile'],
\ ]
augroup toplevel
autocmd BufEnter * silent Cd
augroup END
MIT license. Copyright (c) 2013 Marco Hinz.