411 lines
14 KiB
Text
411 lines
14 KiB
Text
*vundle.txt* Vundle, a plug-in manager for Vim. *vundle*
|
|
|
|
VUNDLE MANUAL
|
|
|
|
1. About Vundle |vundle-about|
|
|
2. Quick Start |vundle-quickstart|
|
|
3. Plugins |vundle-plugins|
|
|
3.1. Configuring Plugins |vundle-plugins-configure|
|
|
3.2. Supported URIs |vundle-plugins-uris|
|
|
3.3. Installing Plugins |vundle-plugins-install|
|
|
3.4. Updating Plugins |vundle-plugins-update|
|
|
3.5. Searching Plugins |vundle-plugins-search|
|
|
3.6. Listing Plugins |vundle-plugins-list|
|
|
3.7. Cleaning Up |vundle-plugins-cleanup|
|
|
4. Interactive Mode |vundle-interactive|
|
|
5. Key Mappings |vundle-keymappings|
|
|
6. Options |vundle-options|
|
|
7. Plugin Interface Change |vundle-interface-change|
|
|
|
|
=============================================================================
|
|
1. ABOUT VUNDLE ~
|
|
*vundle-about*
|
|
|
|
Vundle is short for Vim bundle and is a Vim plugin manager.
|
|
|
|
Vundle allows you to...
|
|
|
|
- keep track of and configure your scripts right in the `.vimrc`
|
|
- install configured scripts (a.k.a. bundle)
|
|
- update configured scripts
|
|
- search by name all available Vim scripts
|
|
- clean unused scripts up
|
|
- run the above actions in a single keypress with interactive mode
|
|
|
|
Vundle automatically...
|
|
|
|
- manages the runtime path of your installed scripts
|
|
- regenerates help tags after installing and updating
|
|
|
|
Vundle's search uses http://vim-scripts.org to provide a list of all
|
|
available Vim scripts.
|
|
|
|
Vundle is undergoing an interface change, see |vundle-interface-change| for
|
|
more information.
|
|
|
|
=============================================================================
|
|
2. QUICK START ~
|
|
*vundle-quickstart*
|
|
|
|
1. Introduction:
|
|
|
|
Installation requires `Git` and triggers git clone for each configured
|
|
repository to `~/.vim/bundle/` by default. Curl is required for search.
|
|
|
|
*vundle-windows*
|
|
If you are using Windows, see instructions on the Wiki
|
|
https://github.com/VundleVim/Vundle.vim/wiki/Vundle-for-Windows.
|
|
|
|
*vundle-faq*
|
|
If you run into any issues, please consult the FAQ at
|
|
https://github.com/VundleVim/Vundle.vim/wiki
|
|
|
|
2. Setup Vundle:
|
|
>
|
|
git clone https://github.com/VundleVim/Vundle.vim.git ~/.vim/bundle/Vundle.vim
|
|
<
|
|
3. Configure bundles:
|
|
|
|
Put this at the top of your `.vimrc` to use Vundle. Remove bundles you
|
|
don't need, they are for illustration purposes.
|
|
>
|
|
set nocompatible " be iMproved, required
|
|
filetype off " required
|
|
|
|
" set the runtime path to include Vundle and initialize
|
|
set rtp+=~/.vim/bundle/Vundle.vim
|
|
call vundle#begin()
|
|
" alternatively, pass a path where Vundle should install plugins
|
|
"call vundle#begin('~/some/path/here')
|
|
|
|
" let Vundle manage Vundle, required
|
|
Plugin 'VundleVim/Vundle.vim'
|
|
|
|
" The following are examples of different formats supported.
|
|
" Keep Plugin commands between vundle#begin/end.
|
|
" plugin on GitHub repo
|
|
Plugin 'tpope/vim-fugitive'
|
|
" plugin from http://vim-scripts.org/vim/scripts.html
|
|
Plugin 'L9'
|
|
" Git plugin not hosted on GitHub
|
|
Plugin 'git://git.wincent.com/command-t.git'
|
|
" git repos on your local machine (i.e. when working on your own plugin)
|
|
Plugin 'file:///home/gmarik/path/to/plugin'
|
|
" The sparkup vim script is in a subdirectory of this repo called vim.
|
|
" Pass the path to set the runtimepath properly.
|
|
Plugin 'rstacruz/sparkup', {'rtp': 'vim/'}
|
|
" Avoid a name conflict with L9
|
|
Plugin 'user/L9', {'name': 'newL9'}
|
|
|
|
" All of your Plugins must be added before the following line
|
|
call vundle#end() " required
|
|
filetype plugin indent on " required
|
|
" To ignore plugin indent changes, instead use:
|
|
"filetype plugin on
|
|
"
|
|
" Brief help
|
|
" :PluginList - list configured plugins
|
|
" :PluginInstall(!) - install (update) plugins
|
|
" :PluginSearch(!) foo - search (or refresh cache first) for foo
|
|
" :PluginClean(!) - confirm (or auto-approve) removal of unused plugins
|
|
"
|
|
" see :h vundle for more details or wiki for FAQ
|
|
" Put your non-Plugin stuff after this line
|
|
|
|
4. Install configured bundles:
|
|
|
|
Launch vim and run
|
|
>
|
|
:PluginInstall
|
|
<
|
|
To install from command line:
|
|
>
|
|
vim +PluginInstall +qall
|
|
|
|
=============================================================================
|
|
3. PLUGINS ~
|
|
*vundle-plugins*
|
|
|
|
3.1 CONFIGURING PLUGINS ~
|
|
*vundle-plugins-configure* *:Plugin*
|
|
|
|
Vundle tracks what plugins you want configured by the `Plugin` commands in your
|
|
`.vimrc`. Each `Plugin` command tells Vundle to activate the script on startup
|
|
adding it to your |runtimepath|. Commenting out or removing the line will
|
|
disable the `Plugin`.
|
|
|
|
Each `Plugin` command takes a URI pointing to the script. No comments should
|
|
follow on the same line as the command. Example:
|
|
>
|
|
Plugin 'git_URI'
|
|
|
|
The `Plugin` command can optionally take a second argument after the URI. It
|
|
has to be a dictionary, separated from the URI by a comma. Each key-value pair
|
|
in the dictionary is a configuration option.
|
|
|
|
The following per-script configuration options are available.
|
|
|
|
The 'rtp' option
|
|
----------------
|
|
|
|
Specifies a directory inside the repository (relative path from the root of
|
|
the repository) where the vim plugin resides. It determines the path that will
|
|
be added to the |runtimepath|.
|
|
|
|
For example:
|
|
>
|
|
Plugin 'git_URI', {'rtp': 'some/subdir/'}
|
|
|
|
This can be used with git repositories that put the vim plugin inside a
|
|
subdirectory.
|
|
|
|
The 'name' option
|
|
-----------------
|
|
|
|
The name of the directory that will hold the local clone of the configured
|
|
script.
|
|
|
|
For example:
|
|
>
|
|
Plugin 'git_URI', {'name': 'newPluginName'}
|
|
|
|
This can be used to prevent name collisions between plugins that Vundle would
|
|
otherwise try to clone into the same directory. It also provides an additional
|
|
level of customisation.
|
|
|
|
The 'pinned' option
|
|
-------------------
|
|
|
|
A flag that, when set to a value of 1, tells Vundle not to perform any git
|
|
operations on the plugin, while still adding the existing plugin under the
|
|
`bundles` directories to the |runtimepath|.
|
|
|
|
For example:
|
|
>
|
|
Plugin 'mylocalplugin', {'pinned': 1}
|
|
|
|
This allows the users to include, with Vundle, plugins tracked with version
|
|
control systems other than git, but the user is responsible for cloning and
|
|
keeping up to date. It also allows the users to stay in the current version of
|
|
a plugin that might have previously been updated by Vundle.
|
|
|
|
Please note that the URI will be treated the same as for any other plugins, so
|
|
only the last part of it will be added to the |runtimepath|. The user is
|
|
advised to use this flag only with single word URIs to avoid confusion.
|
|
|
|
3.2 SUPPORTED URIS ~
|
|
*vundle-plugins-uris*
|
|
|
|
`Vundle` integrates very well with both GitHub and vim-scripts.org
|
|
(http://vim-scripts.org/vim/scripts.html) allowing short URIs. It also allows
|
|
the use of any URI `git` recognizes. In all of the following cases (except
|
|
local) the 'https' protocol is used, see Vundle's options to override this.
|
|
|
|
More information on `git`'s protocols can be found at:
|
|
http://git-scm.com/book/ch4-1.html
|
|
|
|
GitHub
|
|
------
|
|
GitHub is used when a user/repo is passed to `Plugin`.
|
|
>
|
|
Plugin 'VundleVim/Vundle.vim' => https://github.com/VundleVim/Vundle.vim
|
|
|
|
Vim Scripts
|
|
-----------
|
|
Any single word without a slash '/' is assumed to be from Vim Scripts.
|
|
>
|
|
Plugin 'ctrlp.vim' => https://github.com/vim-scripts/ctrlp.vim
|
|
|
|
Other Git URIs
|
|
--------------
|
|
No modification is performed on valid URIs that point outside the above
|
|
URLs.
|
|
>
|
|
Plugin 'git://git.wincent.com/command-t.git'
|
|
|
|
Local Plugins
|
|
-------------
|
|
The git protocol supports local installation using the 'file://' protocol.
|
|
This is handy when developing plugins locally. Follow the protocol with an
|
|
absolute path to the script directory.
|
|
>
|
|
Plugin 'file:///path/from/root/to/plugin'
|
|
|
|
3.3 INSTALLING PLUGINS ~
|
|
*vundle-plugins-install* *:PluginInstall*
|
|
>
|
|
:PluginInstall
|
|
|
|
Will install all plugins configured in your `.vimrc`. Newly installed
|
|
plugins will be automatically enabled. Some plugins may require extra steps
|
|
such as compilation or external programs, refer to their documentation.
|
|
|
|
PluginInstall allows installation of plugins by name:
|
|
>
|
|
:PluginInstall unite.vim
|
|
|
|
Installs and activates unite.vim.
|
|
|
|
PluginInstall also allows installation of several plugins separated by space.
|
|
>
|
|
:PluginInstall tpope/vim-surround tpope/vim-fugitive
|
|
|
|
Installs both tpope/vim-surround and tpope/vim-fugitive from GitHub.
|
|
|
|
You can use Tab to auto-complete known script names.
|
|
Note that the installation just described isn't permanent. To
|
|
finish, you must put `Plugin 'unite.vim'` at the appropriate place in your
|
|
`.vimrc` to tell Vundle to load the plugin at startup.
|
|
|
|
After installing plugins press 'l' (lowercase 'L') to see the log of commands
|
|
if any errors occurred.
|
|
|
|
3.4 UPDATING PLUGINS ~
|
|
*vundle-plugins-update* *:PluginUpdate* *:PluginInstall!*
|
|
>
|
|
:PluginInstall! " NOTE: bang(!)
|
|
or >
|
|
:PluginUpdate
|
|
|
|
Installs or updates the configured plugins. Press 'u' after updates complete
|
|
to see the change log of all updated bundles. Press 'l' (lowercase 'L') to
|
|
see the log of commands if any errors occurred.
|
|
|
|
To update specific plugins, write their names separated by space:
|
|
>
|
|
:PluginInstall! vim-surround vim-fugitive
|
|
or >
|
|
:PluginUpdate vim-surround vim-fugitive
|
|
|
|
3.5 SEARCHING PLUGINS ~
|
|
*vundle-plugins-search* *:PluginSearch*
|
|
>
|
|
:PluginSearch
|
|
|
|
Search requires that `curl` be available on the system. The command searches
|
|
Vim Scripts (http://vim-scripts.org/vim/scripts.html) for matching
|
|
plugins. Results display in a new split window. For example:
|
|
>
|
|
PluginSearch foo
|
|
|
|
displays:
|
|
>
|
|
"Search results for: foo
|
|
Plugin 'MarkdownFootnotes'
|
|
Plugin 'VimFootnotes'
|
|
Plugin 'foo.vim'
|
|
<
|
|
*:PluginSearch!*
|
|
Alternatively, you can refresh the script list before searching by adding a
|
|
bang to the command.
|
|
>
|
|
:PluginSearch! foo
|
|
|
|
If the command is run without argument:
|
|
>
|
|
:PluginSearch!
|
|
|
|
it will display all known plugins in the new split.
|
|
|
|
3.6 LISTING BUNDLES ~
|
|
*vundle-plugins-list* *:PluginList*
|
|
>
|
|
:PluginList
|
|
|
|
Displays a list of installed bundles.
|
|
|
|
3.7 CLEANING UP ~
|
|
*vundle-plugins-cleanup* *:PluginClean*
|
|
>
|
|
:PluginClean
|
|
|
|
Requests confirmation for the removal of all plugins no longered configured
|
|
in your `.vimrc` but present in your bundle installation directory
|
|
(default: `.vim/bundle/`).
|
|
|
|
*:PluginClean!*
|
|
>
|
|
:PluginClean!
|
|
|
|
Automatically confirm removal of unused bundles.
|
|
|
|
=============================================================================
|
|
4. INTERACTIVE MODE ~
|
|
*vundle-interactive*
|
|
|
|
Vundle provides a simple interactive mode to help you explore new plugins
|
|
easily. Interactive mode is available after any command that lists `Plugins`
|
|
such as PluginSearch, PluginList or Plugins. For instance:
|
|
>
|
|
:PluginSearch! unite
|
|
|
|
Searches for plugins matching 'unite' and yields a split window with:
|
|
>
|
|
"Keymap: i - Install bundle; c - Cleanup; s - Search; R - Reload list
|
|
"Search results for: unite
|
|
Plugin 'unite-scriptenames'
|
|
Plugin 'unite.vim'
|
|
Plugin 'unite-yarm'
|
|
Plugin 'unite-gem'
|
|
Plugin 'unite-locate'
|
|
Plugin 'unite-font'
|
|
Plugin 'unite-colorscheme'
|
|
|
|
To install a bundle, move your cursor to the Plugin of interest and then
|
|
select a command. To install 'unite.vim' put your cursor on the line and
|
|
then push `i`. For a more complete list see |vundle-keymappings|. After
|
|
unite.vim is installed the `:Unite file` command should be available.
|
|
|
|
Note: Interactive installation doesn't update your `.vimrc`.
|
|
|
|
=============================================================================
|
|
5. KEY MAPPINGS ~
|
|
*vundle-keymappings*
|
|
|
|
KEY | DESCRIPTION
|
|
----|-------------------------- >
|
|
i | run :PluginInstall with name taken from line cursor is positioned on
|
|
I | same as i, but runs :PluginInstall! to update bundle
|
|
D | delete selected bundle (be careful not to remove local modifications)
|
|
c | run :PluginClean
|
|
s | run :PluginSearch
|
|
R | fetch fresh script list from server
|
|
|
|
=============================================================================
|
|
6. OPTIONS ~
|
|
*vundle-options*
|
|
>
|
|
let g:vundle_default_git_proto = 'git'
|
|
<
|
|
This option makes Vundle use `git` instead of `https` when building
|
|
absolute URIs. For example:
|
|
>
|
|
Plugin 'sjl/gundo.vim' -> git@github.com:sjl/gundo.git
|
|
|
|
=============================================================================
|
|
7. VUNDLE INTERFACE CHANGE ~
|
|
*vundle-interface-change* *:Bundle* *:BundleInstall!*
|
|
*:BundleUpdate* *:BundleSearch* *:BundleList* *:BundleClean!*
|
|
*:VundleInstall!* *:VundleUpdate* *:VundleSearch*
|
|
*:VundleList* *:VundleClean!*
|
|
|
|
In order to bring in new changes, Vundle is adopting a new interface.
|
|
Going forward we will support primarily the Plugin namespace, additionally
|
|
for convenience we will also alias some commands to the Vundle namespace.
|
|
The following table summarizes the interface changes.
|
|
|
|
Deprecated Names | New Names
|
|
-----------------------------
|
|
Bundle | Plugin
|
|
BundleInstall(!) | PluginInstall(!), VundleInstall(!)
|
|
BundleUpdate | PluginUpdate, VundleUpdate
|
|
BundleSearch(!) | PluginSearch(!), VundleSearch(!)
|
|
BundleClean | PluginClean(!), VundleClean(!)
|
|
BundleList | PluginList
|
|
|
|
Note: The Bundle commands will be deprecated. You may continue using them,
|
|
but they may not get all future updates. For instance, we have enabled
|
|
comments on Plugin lines but not Bundle, since it requires a change in
|
|
command declaration.
|
|
|
|
" vim: set expandtab sts=2 ts=2 sw=2 tw=78 ft=help norl:
|