diff --git a/README.md b/README.md
index 3d78b7f..6e09eac 100644
--- a/README.md
+++ b/README.md
@@ -32,11 +32,12 @@ A minimalist Vim plugin manager.
### Pros.
-- Easy to set up: Single file. No boilerplate code required.
-- Easy to use: Concise, intuitive syntax
-- Minimalist: No feature bloat
+- Minimalist design
+ - Just one file with no dependencies. Super easy to set up.
+ - Concise, intuitive syntax that you can learn within minutes. No boilerplate code required.
+ - No feature bloat
- Extremely stable with flawless backward compatibility
- - Works perfectly with Vim 7.0+ since 2006 and with all versions of Neovim since 2014
+ - Works perfectly with all versions of Vim since 2006 and all versions of Neovim ever released
- [Super-fast][40/4] parallel installation/update
- Creates shallow clones to minimize disk space usage and download time
- On-demand loading for [faster startup time][startup-time]
@@ -53,6 +54,9 @@ A minimalist Vim plugin manager.
[Download plug.vim](https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim)
and put it in the "autoload" directory.
+
+Click to see the instructions
+
#### Vim
###### Unix
@@ -97,30 +101,52 @@ iwr -useb https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim |`
ni "$(@($env:XDG_DATA_HOME, $env:LOCALAPPDATA)[$null -eq $env:XDG_DATA_HOME])/nvim-data/site/autoload/plug.vim" -Force
```
-### Getting Help
+
-- See [tutorial] page to learn the basics of vim-plug
+### Usage
+
+Add a vim-plug section to your `~/.vimrc` (or `init.vim` for Neovim)
+
+1. Begin the section with `call plug#begin()`
+1. List the plugins with `Plug` commands
+1. End the section with `call plug#end()`
+
+For example,
+
+```vim
+call plug#begin()
+
+" List your plugins here
+Plug 'tpope/vim-sensible'
+
+call plug#end()
+```
+
+Reload the file or restart Vim, then you can,
+
+* `:PlugInstall` to install the plugins
+* `:PlugUpdate` to install or update the plugins
+* `:PlugDiff` to review the changes from the last update
+
+> [!NOTE]
+> That's basically all you need to know to get started. The rest of the
+> document is for advanced users who want to know more about the features and
+> options.
+
+#### Getting Help
+
+- See [tutorial] page to learn more about the basics of vim-plug
- See [tips] and [FAQ] pages for common problems and questions
-- See [requirements] page for debugging information & tested configurations
-- Create an [issue](https://github.com/junegunn/vim-plug/issues/new)
[tutorial]: https://github.com/junegunn/vim-plug/wiki/tutorial
[tips]: https://github.com/junegunn/vim-plug/wiki/tips
[FAQ]: https://github.com/junegunn/vim-plug/wiki/faq
-[requirements]: https://github.com/junegunn/vim-plug/wiki/requirements
-### Usage
+### More examples
-Add a vim-plug section to your `~/.vimrc` (or `stdpath('config') . '/init.vim'` for Neovim)
+The following examples demonstrate the additional features of vim-plug.
-1. Begin the section with `call plug#begin([PLUGIN_DIR])`
-1. List the plugins with `Plug` commands
-1. `call plug#end()` to update `&runtimepath` and initialize plugin system
- - Automatically executes `filetype plugin indent on` and `syntax enable`.
- You can revert the settings after the call. e.g. `filetype indent off`, `syntax off`, etc.
-1. Reload the file or restart Vim and run `:PlugInstall` to install plugins.
-
-#### Example
+#### Vim script example
```vim
call plug#begin()
@@ -167,18 +193,18 @@ Plug 'tpope/vim-fireplace', { 'for': 'clojure' }
" Unmanaged plugin (manually installed and updated)
Plug '~/my-prototype-plugin'
-" Initialize plugin system
-" - Automatically executes `filetype plugin indent on` and `syntax enable`.
+" Call plug#end to update &runtimepath and initialize the plugin system.
+" - It automatically executes `filetype plugin indent on` and `syntax enable`
call plug#end()
" You can revert the settings after the call like so:
" filetype indent off " Disable file-type-specific indentation
" syntax off " Disable syntax highlighting
```
-#### Example (Lua configuration for Neovim)
+#### Lua configuration example for Neovim
In Neovim, you can write your configuration in a Lua script file named
-`init.lua`. The following code is the Lua script equivalent to the VimScript
+`init.lua`. The following code is the Lua script equivalent to the Vim script
example above.
```lua
@@ -279,14 +305,78 @@ More examples can be found in:
- `:PlugDiff`
- `X` - Revert the update
-### Example: A small [sensible](https://github.com/tpope/vim-sensible) Vim configuration
+### Post-update hooks
+
+There are some plugins that require extra steps after installation or update.
+In that case, use the `do` option to describe the task to be performed.
```vim
-call plug#begin()
-Plug 'tpope/vim-sensible'
-call plug#end()
+Plug 'Shougo/vimproc.vim', { 'do': 'make' }
+Plug 'ycm-core/YouCompleteMe', { 'do': './install.py' }
```
+If the value starts with `:`, it will be recognized as a Vim command.
+
+```vim
+Plug 'fatih/vim-go', { 'do': ':GoInstallBinaries' }
+```
+
+To call a Vim function, you can pass a lambda expression like so:
+
+```vim
+Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }
+```
+
+If you need more control, you can pass a reference to a Vim function that
+takes a dictionary argument.
+
+```vim
+function! BuildYCM(info)
+ " info is a dictionary with 3 fields
+ " - name: name of the plugin
+ " - status: 'installed', 'updated', or 'unchanged'
+ " - force: set on PlugInstall! or PlugUpdate!
+ if a:info.status == 'installed' || a:info.force
+ !./install.py
+ endif
+endfunction
+
+Plug 'ycm-core/YouCompleteMe', { 'do': function('BuildYCM') }
+```
+
+A post-update hook is executed inside the directory of the plugin and only run
+when the repository has changed, but you can force it to run unconditionally
+with the bang-versions of the commands: `PlugInstall!` and `PlugUpdate!`.
+
+> [!TIP]
+> Make sure to escape BARs and double-quotes when you write the `do` option
+> inline as they are mistakenly recognized as command separator or the start of
+> the trailing comment.
+>
+> ```vim
+> Plug 'junegunn/fzf', { 'do': 'yes \| ./install' }
+> ```
+>
+> But you can avoid the escaping if you extract the inline specification using a
+> variable (or any Vim script expression) as follows:
+>
+> ```vim
+> let g:fzf_install = 'yes | ./install'
+> Plug 'junegunn/fzf', { 'do': g:fzf_install }
+> ```
+
+#### `PlugInstall!` and `PlugUpdate!`
+
+The installer takes the following steps when installing/updating a plugin:
+
+1. `git clone` or `git fetch` from its origin
+2. Check out branch, tag, or commit and optionally `git merge` remote branch
+3. If the plugin was updated (or installed for the first time)
+ 1. Update submodules
+ 2. Execute post-update hooks
+
+The commands with the `!` suffix ensure that all steps are run unconditionally.
+
### On-demand loading of plugins
```vim
@@ -347,78 +437,6 @@ autocmd! User goyo.vim echom 'Goyo is now loaded!'
> See https://github.com/junegunn/vim-plug/wiki/tips#loading-plugins-manually
-### Post-update hooks
-
-There are some plugins that require extra steps after installation or update.
-In that case, use the `do` option to describe the task to be performed.
-
-```vim
-Plug 'Shougo/vimproc.vim', { 'do': 'make' }
-Plug 'ycm-core/YouCompleteMe', { 'do': './install.py' }
-```
-
-If the value starts with `:`, it will be recognized as a Vim command.
-
-```vim
-Plug 'fatih/vim-go', { 'do': ':GoInstallBinaries' }
-```
-
-To call a Vim function, you can pass a lambda expression like so:
-
-```vim
-Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }
-```
-
-If you need more control, you can pass a reference to a Vim function that
-takes a dictionary argument.
-
-```vim
-function! BuildYCM(info)
- " info is a dictionary with 3 fields
- " - name: name of the plugin
- " - status: 'installed', 'updated', or 'unchanged'
- " - force: set on PlugInstall! or PlugUpdate!
- if a:info.status == 'installed' || a:info.force
- !./install.py
- endif
-endfunction
-
-Plug 'ycm-core/YouCompleteMe', { 'do': function('BuildYCM') }
-```
-
-A post-update hook is executed inside the directory of the plugin and only run
-when the repository has changed, but you can force it to run unconditionally
-with the bang-versions of the commands: `PlugInstall!` and `PlugUpdate!`.
-
-> [!TIP]
-> Make sure to escape BARs and double-quotes when you write the `do` option
-> inline as they are mistakenly recognized as command separator or the start of
-> the trailing comment.
->
-> ```vim
-> Plug 'junegunn/fzf', { 'do': 'yes \| ./install' }
-> ```
->
-> But you can avoid the escaping if you extract the inline specification using a
-> variable (or any Vimscript expression) as follows:
->
-> ```vim
-> let g:fzf_install = 'yes | ./install'
-> Plug 'junegunn/fzf', { 'do': g:fzf_install }
-> ```
-
-### `PlugInstall!` and `PlugUpdate!`
-
-The installer takes the following steps when installing/updating a plugin:
-
-1. `git clone` or `git fetch` from its origin
-2. Check out branch, tag, or commit and optionally `git merge` remote branch
-3. If the plugin was updated (or installed for the first time)
- 1. Update submodules
- 2. Execute post-update hooks
-
-The commands with the `!` suffix ensure that all steps are run unconditionally.
-
### Collaborators
- [Jan Edmund Lazo](https://github.com/janlazo) - Windows support
diff --git a/doc/plug.txt b/doc/plug.txt
index 23c96f4..507124a 100644
--- a/doc/plug.txt
+++ b/doc/plug.txt
@@ -1,21 +1,24 @@
-plug.txt plug Last change: March 31 2024
+plug.txt plug Last change: May 14 2024
PLUG - TABLE OF CONTENTS *plug* *plug-toc*
==============================================================================
- vim-plug |vim-plug|
- Getting Help |plug-getting-help|
- Usage |plug-usage|
- Example |plug-example|
- Example (Lua configuration for Neovim) |plug-examplelua-configuration-for-neovim|
- Commands |plug-commands|
- Plug options |plug-options|
- Global options |plug-global-options|
- Keybindings |plug-keybindings|
- Example: A small sensible Vim configuration |plug-example-a-small-sensible-vim-configuration|
- On-demand loading of plugins |plug-on-demand-loading-of-plugins|
- Post-update hooks |plug-post-update-hooks|
- PlugInstall! and PlugUpdate! |pluginstall-and-plugupdate|
- License |plug-license|
+ vim-plug |vim-plug|
+ Pros. |plug-pros|
+ Installation |plug-installation|
+ Usage |plug-usage|
+ Getting Help |plug-getting-help|
+ More examples |plug-more-examples|
+ Vim script example |plug-vim-script-example|
+ Lua configuration example for Neovim |plug-lua-configuration-example-for-neovim|
+ Commands |plug-commands|
+ Plug options |plug-options|
+ Global options |plug-global-options|
+ Keybindings |plug-keybindings|
+ Post-update hooks |plug-post-update-hooks|
+ PlugInstall! and PlugUpdate! |pluginstall-and-plugupdate|
+ On-demand loading of plugins |plug-on-demand-loading-of-plugins|
+ Collaborators |plug-collaborators|
+ License |plug-license|
VIM-PLUG *vim-plug*
==============================================================================
@@ -23,40 +26,89 @@ VIM-PLUG *vim-plug*
A minimalist Vim plugin manager.
-< Getting Help >______________________________________________________________~
- *plug-getting-help*
+< Pros. >_____________________________________________________________________~
+ *plug-pros*
- - See {tutorial}{1} page to learn the basics of vim-plug
- - See {tips}{2} and {FAQ}{3} pages for common problems and questions
- - See {requirements}{4} page for debugging information & tested configurations
- - Create an {issue}{5}
+ - Minimalist design
+ - Just one file with no dependencies. Super easy to set up.
+ - Concise, intuitive syntax that you can learn within minutes. No
+ boilerplate code required.
+ - No feature bloat
+ - Extremely stable with flawless backward compatibility
+ - Works perfectly with Vim 7.0+ since 2006 and with all versions of Neovim
+ since 2014
+ - {Super-fast}{1} parallel installation/update
+ - Creates shallow clones to minimize disk space usage and download time
+ - On-demand loading for {faster startup time}{2}
+ - Can review and rollback updates
+ - Branch/tag/commit support
+ - Post-update hooks
+ - Support for externally managed plugins
- {1} https://github.com/junegunn/vim-plug/wiki/tutorial
- {2} https://github.com/junegunn/vim-plug/wiki/tips
- {3} https://github.com/junegunn/vim-plug/wiki/faq
- {4} https://github.com/junegunn/vim-plug/wiki/requirements
- {5} https://github.com/junegunn/vim-plug/issues/new
+ {1} https://raw.githubusercontent.com/junegunn/i/master/vim-plug/40-in-4.gif
+ {2} https://github.com/junegunn/vim-startuptime-benchmark#result
+
+
+< Installation >______________________________________________________________~
+ *plug-installation*
+
+{Download plug.vim}{3} and put it in the "autoload" directory.
+
+ {3} https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
< Usage >_____________________________________________________________________~
*plug-usage*
-Add a vim-plug section to your `~/.vimrc` (or
-`stdpath('config') . '/init.vim'` for Neovim)
+Add a vim-plug section to your `~/.vimrc` (or `init.vim` for Neovim)
*plug#begin* *plug#end*
- 1. Begin the section with `call plug#begin([PLUGIN_DIR])`
+ 1. Begin the section with `call plug#begin()`
2. List the plugins with `Plug` commands
- 3. `call plug#end()` to update 'runtimepath' and initialize plugin system
- - Automatically executes `filetype plugin indent on` and `syntax enable`.
- You can revert the settings after the call. e.g. `filetype indent off`,
- `syntax off`, etc.
- 4. Reload the file or restart Vim and run `:PlugInstall` to install plugins.
+ 3. End the section with `call plug#end()`
+
+For example,
+>
+ call plug#begin()
+
+ " List your plugins here
+ Plug 'tpope/vim-sensible'
+
+ call plug#end()
+<
+Reload the file or restart Vim, then you can,
+
+ *:PlugInstall* *:PlugUpdate* *:PlugDiff*
+
+ - `:PlugInstall` to install the plugins
+ - `:PlugUpdate` to install or update the plugins
+ - `:PlugDiff` to review the changes from the last update
+
+[!NOTE] That's basically all you need to know to get started. The rest of the
+document is for advanced users who want to know more about the features and
+options.
-Example~
- *plug-example*
+Getting Help~
+ *plug-getting-help*
+
+ - See {tutorial}{4} page to learn more about the basics of vim-plug
+ - See {tips}{5} and {FAQ}{6} pages for common problems and questions
+
+ {4} https://github.com/junegunn/vim-plug/wiki/tutorial
+ {5} https://github.com/junegunn/vim-plug/wiki/tips
+ {6} https://github.com/junegunn/vim-plug/wiki/faq
+
+
+< More examples >_____________________________________________________________~
+ *plug-more-examples*
+
+The following examples demonstrate the additional features of vim-plug.
+
+
+Vim script example~
+ *plug-vim-script-example*
>
call plug#begin()
" The default plugin directory will be as follows:
@@ -102,19 +154,19 @@ Example~
" Unmanaged plugin (manually installed and updated)
Plug '~/my-prototype-plugin'
- " Initialize plugin system
- " - Automatically executes `filetype plugin indent on` and `syntax enable`.
+ " Call plug#end to update &runtimepath and initialize the plugin system.
+ " - It automatically executes `filetype plugin indent on` and `syntax enable`
call plug#end()
" You can revert the settings after the call like so:
" filetype indent off " Disable file-type-specific indentation
" syntax off " Disable syntax highlighting
<
-Example (Lua configuration for Neovim)~
- *plug-example-lua-configuration-for-neovim*
+Lua configuration example for Neovim~
+ *plug-lua-configuration-example-for-neovim*
In Neovim, you can write your configuration in a Lua script file named
-`init.lua`. The following code is the Lua script equivalent to the VimScript
+`init.lua`. The following code is the Lua script equivalent to the Vim script
example above.
>
local vim = vim
@@ -189,7 +241,7 @@ More examples can be found in:
*-mappings*
------------------------+------------------------------------------------------------
- Option | Description ~
+ Option | Description ~
------------------------+------------------------------------------------------------
`branch` / `tag` / `commit` | Branch/tag/commit of the repository to use
`rtp` | Subdirectory that contains Vim plugin
@@ -235,41 +287,6 @@ More examples can be found in:
- `X` - Revert the update
-< Example: A small sensible Vim configuration >_______________________________~
- *plug-example-a-small-sensible-vim-configuration*
->
- call plug#begin()
- Plug 'tpope/vim-sensible'
- call plug#end()
-<
-
-< On-demand loading of plugins >______________________________________________~
- *plug-on-demand-loading-of-plugins*
->
- " NERD tree will be loaded on the first invocation of NERDTreeToggle command
- Plug 'preservim/nerdtree', { 'on': 'NERDTreeToggle' }
-
- " Multiple commands
- Plug 'junegunn/vim-github-dashboard', { 'on': ['GHDashboard', 'GHActivity'] }
-
- " Loaded when clojure file is opened
- Plug 'tpope/vim-fireplace', { 'for': 'clojure' }
-
- " Multiple file types
- Plug 'kovisoft/paredit', { 'for': ['clojure', 'scheme'] }
-
- " On-demand loading on both conditions
- Plug 'junegunn/vader.vim', { 'on': 'Vader', 'for': 'vader' }
-
- " Code to execute when the plugin is lazily loaded on demand
- Plug 'junegunn/goyo.vim', { 'for': 'markdown' }
- autocmd! User goyo.vim echom 'Goyo is now loaded!'
-<
-The `for` option is generally not needed as most plugins for specific file
-types usually don't have too much code in the `plugin` directory. You might
-want to examine the output of `vim --startuptime` before applying the option.
-
-
< Post-update hooks >_________________________________________________________~
*plug-post-update-hooks*
@@ -313,15 +330,13 @@ the trailing comment.
Plug 'junegunn/fzf', { 'do': 'yes \| ./install' }
<
But you can avoid the escaping if you extract the inline specification using a
-variable (or any Vimscript expression) as follows:
-
- *g:fzf_install*
+variable (or any Vim script expression) as follows:
>
let g:fzf_install = 'yes | ./install'
Plug 'junegunn/fzf', { 'do': g:fzf_install }
<
-< PlugInstall! and PlugUpdate! >______________________________________________~
+PlugInstall! and PlugUpdate!~
*pluginstall-and-plugupdate*
The installer takes the following steps when installing/updating a plugin:
@@ -336,6 +351,73 @@ The commands with the `!` suffix ensure that all steps are run
unconditionally.
+< On-demand loading of plugins >______________________________________________~
+ *plug-on-demand-loading-of-plugins*
+>
+ " NERD tree will be loaded on the first invocation of NERDTreeToggle command
+ Plug 'preservim/nerdtree', { 'on': 'NERDTreeToggle' }
+
+ " Multiple commands
+ Plug 'junegunn/vim-github-dashboard', { 'on': ['GHDashboard', 'GHActivity'] }
+
+ " Loaded when clojure file is opened
+ Plug 'tpope/vim-fireplace', { 'for': 'clojure' }
+
+ " Multiple file types
+ Plug 'kovisoft/paredit', { 'for': ['clojure', 'scheme'] }
+
+ " On-demand loading on both conditions
+ Plug 'junegunn/vader.vim', { 'on': 'Vader', 'for': 'vader' }
+
+ " Code to execute when the plugin is lazily loaded on demand
+ Plug 'junegunn/goyo.vim', { 'for': 'markdown' }
+ autocmd! User goyo.vim echom 'Goyo is now loaded!'
+<
+[!NOTE] #### Should I set up on-demand loading?
+
+You probably don't need to.
+
+A properly implemented Vim plugin should already load lazily without any help
+from a plugin manager (`:help autoload`). So there are few cases where these
+options actually make much sense. Making a plugin load faster is the
+responsibility of the plugin developer, not the user. If you find a plugin
+that takes too long to load, consider opening an issue on the plugin's issue
+tracker.
+
+Let me give you a perspective. The time it takes to load a plugin is usually
+less than 2 or 3ms on modern computers. So unless you use a very large number
+of plugins, you are unlikely to save more than 50ms. If you have spent an hour
+carefully setting up the options to shave off 50ms, you will have to start Vim
+72,000 times just to break even. You should ask yourself if that's a good
+investment of your time.
+
+Make sure that you're tackling the right problem by breaking down the startup
+time of Vim using `--startuptime`.
+>
+ vim --startuptime /tmp/log
+<
+On-demand loading should only be used as a last resort. It is basically a
+hacky workaround and is not always guaranteed to work.
+
+ *plug#load*
+
+[!TIP] You can pass an empty list to `on` or `for` option to disable the
+loading of the plugin. You can manually load the plugin using
+`plug#load(NAMES...)` function.
+
+See https://github.com/junegunn/vim-plug/wiki/tips#loading-plugins-manually
+
+
+< Collaborators >_____________________________________________________________~
+ *plug-collaborators*
+
+ - {Jan Edmund Lazo}{7} - Windows support
+ - {Jeremy Pallats}{8} - Python installer
+
+ {7} https://github.com/janlazo
+ {8} https://github.com/starcraftman
+
+
< License >___________________________________________________________________~
*plug-license*