From 9b4ecd1bb56e25cc46c6643be260637822c8c7bb Mon Sep 17 00:00:00 2001 From: Junegunn Choi Date: Tue, 14 May 2024 19:06:23 +0900 Subject: [PATCH] Update documentation (#1280) --- README.md | 204 ++++++++++++++++++++++-------------------- doc/plug.txt | 244 ++++++++++++++++++++++++++++++++++----------------- 2 files changed, 274 insertions(+), 174 deletions(-) diff --git a/README.md b/README.md index 3d78b7f0..6e09eac2 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 +
+ +### 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 the basics of vim-plug +- 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,74 +305,6 @@ More examples can be found in: - `:PlugDiff` - `X` - Revert the update -### Example: A small [sensible](https://github.com/tpope/vim-sensible) Vim configuration - -```vim -call plug#begin() -Plug 'tpope/vim-sensible' -call plug#end() -``` - -### On-demand loading of plugins - -```vim -" 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`. -> -> ```sh -> 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. - -> [!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 - - ### Post-update hooks There are some plugins that require extra steps after installation or update. @@ -400,14 +358,14 @@ with the bang-versions of the commands: `PlugInstall!` and `PlugUpdate!`. > ``` > > But you can avoid the escaping if you extract the inline specification using a -> variable (or any Vimscript expression) as follows: +> 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!` +#### `PlugInstall!` and `PlugUpdate!` The installer takes the following steps when installing/updating a plugin: @@ -419,6 +377,66 @@ The installer takes the following steps when installing/updating a plugin: The commands with the `!` suffix ensure that all steps are run unconditionally. +### On-demand loading of plugins + +```vim +" 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`. +> +> ```sh +> 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. + +> [!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 - [Jan Edmund Lazo](https://github.com/janlazo) - Windows support diff --git a/doc/plug.txt b/doc/plug.txt index 23c96f47..507124a5 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* + + - 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://raw.githubusercontent.com/junegunn/i/master/vim-plug/40-in-4.gif + {2} https://github.com/junegunn/vim-startuptime-benchmark#result - - 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} - {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 +< 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. + + +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* -Example~ - *plug-example* +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*