diff --git a/README.md b/README.md index 38ea63f..d0fbbd7 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ 1. Introduction: Installation requires [Git] and triggers [`git clone`] for each configured repository to `~/.vim/bundle/` by default. + Curl is required for search. If you are using Windows, go directly to [Windows setup]. If you run into any issues, please consult the [FAQ]. @@ -69,6 +70,8 @@ " ... filetype plugin indent on " required + " To ignore plugin indent changes, instead use: + "filetype plugin on " " Brief help " :BundleList - list configured bundles @@ -78,6 +81,7 @@ " " see :h vundle for more details or wiki for FAQ " NOTE: comments after Bundle commands are not allowed. + " Put your stuff after this line ``` 4. Install Bundles: @@ -137,8 +141,8 @@ see [Vundle contributors](https://github.com/gmarik/vundle/graphs/contributors) [help tags]:http://vimdoc.sourceforge.net/htmldoc/helphelp.html#:helptags [runtime path]:http://vimdoc.sourceforge.net/htmldoc/options.html#%27runtimepath%27 -[install]:https://github.com/gmarik/vundle/blob/master/doc/vundle.txt#L115-129 -[update]:https://github.com/gmarik/vundle/blob/master/doc/vundle.txt#L131-137 -[search]:https://github.com/gmarik/vundle/blob/master/doc/vundle.txt#L139-161 -[clean]:https://github.com/gmarik/vundle/blob/master/doc/vundle.txt#L171-L183 -[interactive mode]:https://github.com/gmarik/vundle/blob/master/doc/vundle.txt#L186-213 +[install]:https://github.com/gmarik/vundle/blob/master/doc/vundle.txt#L179-198 +[update]:https://github.com/gmarik/vundle/blob/master/doc/vundle.txt#L200-209 +[search]:https://github.com/gmarik/vundle/blob/master/doc/vundle.txt#L211-238 +[clean]:https://github.com/gmarik/vundle/blob/master/doc/vundle.txt#L247-260 +[interactive mode]:https://github.com/gmarik/vundle/blob/master/doc/vundle.txt#L263-303 diff --git a/doc/vundle.txt b/doc/vundle.txt index d17c94e..4bc3a5f 100644 --- a/doc/vundle.txt +++ b/doc/vundle.txt @@ -1,248 +1,317 @@ -*vundle.txt* Vundle, a plug-in manager for Vim. *vundle* +*vundle.txt* Vundle, a plug-in manager for Vim. *vundle* - VUNDLE MANUAL + VUNDLE MANUAL -Vundle is short for Vim bundle and is a Vim plug-in manager. - -1. Why Vundle |vundle-why-vundle| -2. Quick start |vundle-quickstart| +1. About Vundle |vundle-about| +2. Quick Start |vundle-quickstart| 3. Scripts |vundle-scripts| - 3.1. Configure scripts |vundle-scripts-configure| - 3.2. Installing scripts |vundle-scripts-install| - 3.3. Updating scripts |vundle-scripts-update| - 3.4. Searching scripts |vundle-scripts-search| - 3.5. Listing scripts |vundle-scripts-list| - 3.6. Cleanup |vundle-scripts-cleanup| -4. Interactive mode |vundle-interactive| -5. Key mappings |vundle-keymappings| + 3.1. Configuring Scripts |vundle-scripts-configure| + 3.2. Supported URIs |vundle-uris| + 3.3. Installing Scripts |vundle-scripts-install| + 3.4. Updating Scripts |vundle-scripts-update| + 3.5. Searching Scripts |vundle-scripts-search| + 3.6. Listing Bundles |vundle-scripts-list| + 3.7. Cleaning Up |vundle-scripts-cleanup| +4. Interactive Mode |vundle-interactive| +5. Key Mappings |vundle-keymappings| 6. Options |vundle-options| ============================================================================= -1. WHY VUNDLE ~ - *vundle-why-vundle* -Vundle allows you to: +1. ABOUT VUNDLE ~ + *vundle-about* -- keep track and configure your scripts right in `.vimrc` -- install configured scripts (aka bundle) -- update configured scripts -- search [all available vim scripts] by name -- clean up from unused scripts +Vundle is short for Vim bundle and is a Vim plugin manager. -Also Vundle: +Vundle allows you to... -- manages runtime path of your installed scripts -- regenerates helptags automatically + - 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 takes advantage of [vim-scripts.org](http://vim-scripts.org) -in order to install/search [all available vim scripts] +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. ============================================================================= 2. QUICK START ~ - *vundle-quickstart* -1) Setup Vundle: > + *vundle-quickstart* - git clone https://github.com/gmarik/vundle.git ~/.vim/bundle/vundle +1. Introduction: -2) Configure bundles: + Installation requires `Git` and triggers git clone for each configured + repository to `~/.vim/bundle/` by default. Curl is required for search. - Sample `.vimrc`: > + *vundle-windows* + If you are using Windows, see instructions on the Wiki + https://github.com/gmarik/Vundle.vim/wiki/Vundle-for-Windows. - set nocompatible " be iMproved - filetype off " required! + *vundle-faq* + If you run into any issues, please consult the FAQ at + https://github.com/gmarik/Vundle.vim/wiki - set rtp+=~/.vim/bundle/vundle/ - call vundle#rc() +2. Setup Vundle: +> + git clone https://github.com/gmarik/vundle.git ~/.vim/bundle/vundle +< +3. Configure bundles: - " let Vundle manage Vundle - Bundle 'gmarik/vundle' + 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 - " My Bundles here: - " - " original repos on github - Bundle 'tpope/vim-fugitive' - Bundle 'Lokaltog/vim-easymotion' - Bundle 'rstacruz/sparkup', {'rtp': 'vim/'} - " vim-scripts repos - Bundle 'L9' - Bundle 'FuzzyFinder' - Bundle 'rails.vim' - " non github repos - Bundle 'git://git.wincent.com/command-t.git' - " git repos on your local machine (ie. when working on your own plugin) - Bundle 'file:///Users/gmarik/path/to/plugin' - " ... + " set the runtime path to include Vundle and initialize + set rtp+=~/.vim/bundle/vundle/ + call vundle#rc() + " alternatively, pass a path where Vundle should install bundles + "let path = '~/some/path/here' + "call vundle#rc(path) - filetype plugin indent on " required! - " or - " filetype plugin on " to not use the indentation settings set - " by plugins + " let Vundle manage Vundle, required + Bundle 'gmarik/vundle' -3) Install configured bundles: + " The following are examples of different formats supported. + " Keep bundle commands between here and filetype plugin indent on. + " scripts on GitHub repos + Bundle 'tpope/vim-fugitive' + Bundle 'Lokaltog/vim-easymotion' + Bundle 'tpope/vim-rails.git' + " The sparkup vim script is in a subdirectory of this repo called vim. + " Pass the path to set the runtimepath properly. + Bundle 'rstacruz/sparkup', {'rtp': 'vim/'} + " scripts from http://vim-scripts.org/vim/scripts.html + Bundle 'L9' + Bundle 'FuzzyFinder' + " scripts not on GitHub + Bundle 'git://git.wincent.com/command-t.git' + " git repos on your local machine (i.e. when working on your own plugin) + Bundle 'file:///home/gmarik/path/to/plugin' + " ... - Launch `vim`, run > + filetype plugin indent on " required + " To ignore plugin indent changes, instead use: + "filetype plugin on + " Put your stuff after this line +4. Install configured bundles: + + Launch vim and run +> :BundleInstall - -Installing requires [Git] and triggers -[Git clone](http://gitref.org/creating/#clone) for each configured repo to -`~/.vim/bundle/`. +< + To install from command line: +> + vim +BundleInstall +qall ============================================================================= 3. SCRIPTS ~ - *vundle-scripts* -3.1 CONFIGURE SCRIPTS ~ - *vundle-scripts-configure* *Bundle* -Before installing scripts they need to be configured. It's done using `Bundle` -command in `.vimrc`: > + *vundle-scripts* - Bundle 'git_repo_uri' " 'git_repo_uri' should be a valid uri to git - " repository -or > +3.1 CONFIGURING SCRIPTS ~ + *vundle-scripts-configure* *:Bundle* - Bundle 'script_name' " 'script-name' should be an official script - " name (see |vundle-scripts-search|) +Vundle tracks what scripts you want configured by the `Bundle` commands in your +`.vimrc`. Each `Bundle` command tells Vundle to activate the script on startup +adding it to your runtimepath. Commenting out or removing the line will +disable the `Bundle`. -Vundle loves Github, that's why short URIs can be used with commands: > - - Bundle 'tpope/vim-fugitive' - -equals full uri > - - Bundle 'http://github.com/tpope/vim-fugitive.git' - -Note that Vundle defaults to http:// protocol for the short URIs. +Each `Bundle` command takes a URI pointing to the script. No comments should +follow on the same line as the command. Example: +> + Bundle 'git_URI' There can also be a second argument after URI. It has to be a dictionary with a key called 'rtp'. The value for that key is a directory inside the repository (relative path from the root of the repository) where the vim -plugin resides. For example: > - - Bundle 'any_valid_uri', {'rtp': 'some/subdir/'} +plugin resides. For example: +> + Bundle 'git_URI', {'rtp': 'some/subdir/'} This can be used with git repositories that put the vim plugin inside a subdirectory. -3.2 INSTALL SCRIPTS ~ - *vundle-scripts-install* *BundleInstall* -run > - :BundleInstall -installs configured scripts. Newly installed scripts will be automatically -enabled. Except special cases requiring compilation or pre-configuration. +3.2 SUPPORTED URIS ~ + *vundle-uris* -BundleInstall allows to install scripts by name:> +`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. - :BundleInstall unite.vim +More information on `git`'s protocols can be found at: +http://git-scm.com/book/ch4-1.html -installs and activates unite.vim. You can use Tab to auto-complete known +GitHub +------ +GitHub is used when a user/repo is passed to `Bundle`. +> + Bundle 'gmarik/Vundle.vim' => https://github.com/gmarik/Vundle.vim + +Vim Scripts +----------- +Any single word without a '/' is assumed to be from Vim Scripts. +> + Bundle '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. +> + Bundle '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. +> + Bundle 'file///path/from/root/to/plugin' + +3.3 INSTALLING SCRIPTS ~ + *vundle-scripts-install* *:BundleInstall* +> + :BundleInstall + +Will install all plugins configured in your `.vimrc`. Newly installed +scripts will be automatically enabled. Some scripts may require extra steps +such as compilation or external programs, refer to their documentation. + +BundleInstall allows installation of scripts by name: +> + :BundleInstall unite.vim + +Installs and activates unite.vim. You can use Tab to auto-complete known script names. Note that the installation just described isn't permanent. To -finish, you must put `Bundle 'unite.vim` at the appropriate line in your +finish, you must put `Bundle 'unite.vim'` at the appropriate place in your `.vimrc` to tell Vundle to load the plugin at startup. -3.3 UPDATE SCRIPTS ~ - *vundle-scripts-update* *BundleInstall!* -run > - :BundleInstall! " NOTE: bang(!) +After installing scripts press 'l' (lowercase 'L') to see the log of commands +if any errors occurred. -installs or updates configured scripts. -press u after updates complete to see the changelog of all updated bundles. - -3.4 SEARCHING ~ - *vundle-scripts-search* *BundleSearch* -run > - :BundleSearch foo - -lists bundles matching 'foo' in new a new split window, ie: +3.4 UPDATING SCRIPTS ~ + *vundle-scripts-update* *:BundleUpdate* *:BundleInstall!* > - Bundle 'VimFootnotes' - Bundle 'foo.vim' + :BundleInstall! " NOTE: bang(!) +or > + :BundleUpdate + +Installs or updates the configured scripts. 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. + +3.5 SEARCHING SCRIPTS ~ + *vundle-scripts-search* *:BundleSearch* > -and > + :BundleSearch - :BundleSearch! foo - -refreshes script list before performing actual search. - -If command is run without argument: > - - :BundleSearch! - -it will display all known scripts - -Searching requires [`curl`](http://curl.haxx.se/) - -3.5 LISTING BUNDLES ~ - *vundle-scripts-list* *BundleList* - -To quickly pull list of installed bundles use > - - :BundleList - - -3.6 CLEANING UP ~ - *vundle-scripts-cleanup* *BundleClean* -run > - - :BundleClean - -confirms removal of unused script-dirs from `.vim/bundle/`. - - *BundleClean!* +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: > - :BundleClean! + BundleSearch foo -removes unused dirs with no questions. +displays: +> + "Search results for: foo + Bundle 'MarkdownFootnotes' + Bundle 'VimFootnotes' + Bundle 'foo.vim' +< + *:BundleSearch!* +Alternatively, you can refresh the script list before searching by adding a +bang to the command. +> + :BundleSearch! foo +If the command is run without argument: +> + :BundleSearch! + +it will display all known scripts in the new split. + +3.6 LISTING BUNDLES ~ + *vundle-scripts-list* *:BundleList* +> + :BundleList + +Displays a list of installed bundles. + +3.7 CLEANING UP ~ + *vundle-scripts-cleanup* *:BundleClean* +> + :BundleClean + +Requests confirmation for the removal of all scripts no longered configured +in your `.vimrc` but present in your bundle installation directory +(default: `.vim/bundle/`). + + *:BundleClean!* +> + :BundleClean! + +Automatically confirm removal of unused bundles. ============================================================================= 4. INTERACTIVE MODE ~ - *vundle-interactive* + *vundle-interactive* + Vundle provides a simple interactive mode to help you explore new scripts -easily. Interactive mode is available as result of any commands that displays -a list of bundles. For instance, running: > +easily. Interactive mode is available after any command that lists `Bundles` +such as BundleSearch, BundleList or Bundles. For instance: +> + :BundleSearch! unite - :BundleSearch! unite +Searches for scripts matching 'unite' and yields a split window with: +> + "Keymap: i - Install bundle; c - Cleanup; s - Search; R - Reload list + "Search results for: unite + Bundle 'unite-scriptenames' + Bundle 'unite.vim' + Bundle 'unite-yarm' + Bundle 'unite-gem' + Bundle 'unite-locate' + Bundle 'unite-font' + Bundle 'unite-colorscheme' -triggers search for scripts matching 'unite' and yields a split window with -content: > +To install a bundle, move your cursor to the Bundle 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. - "Keymap: i - Install bundle; c - Cleanup; r - Refine list; R - Reload list - "Search results for: unite - Bundle 'unite.vim' - Bundle 'unite-yarm' - Bundle 'unite-gem' - Bundle 'unite-locate' - Bundle 'unite-font' - Bundle 'unite-colorscheme' - -As the first line (starting with `"Keymap:`) shows, certain actions may be -applied to selected bundles. Move the cursor over the line `Bundle -'unite.vim'` and press i key (install, see |vundle-keymappings| for more -details). After unite.vim is installed - `:Unite file` command should be -available to prove 'unite.vim' availability. - -Note that the interactive installation doesn't update your .vimrc -configuration. +Note: Interactive installation doesn't update your `.vimrc`. ============================================================================= 5. KEY MAPPINGS ~ - *vundle-keymappings* + *vundle-keymappings* + KEY | DESCRIPTION ----|-------------------------- > i | run :BundleInstall with name taken from line cursor is positioned on I | same as i, but runs :BundleInstall! to update bundle - D | delete selected bundle( be careful not to remove local modifications) + D | delete selected bundle (be careful not to remove local modifications) c | run :BundleClean s | run :BundleSearch R | fetch fresh script list from server -. ============================================================================= 6. OPTIONS ~ - *vundle-options* + *vundle-options* +> let g:vundle_default_git_proto = 'git' - -makes Vundle use `git` instead default `https` when building absolute repo URIs - +< + This option makes Vundle use `git` instead of `https` when building + absolute URIs. For example: +> + Bundle 'sjl/gundo.vim' -> git@github.com:sjl/gundo.git vim:tw=78:ts=8:ft=help:norl: