Skip to content

Commit 96375cb

Browse files
junegunnjunegunn
committed
Update README and add vim help file
Close #705
1 parent 2f4dc4d commit 96375cb

File tree

2 files changed

+382
-3
lines changed

2 files changed

+382
-3
lines changed

‎README.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -78,10 +78,13 @@ $uri = 'https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim'
7878

7979
### Getting Help
8080

81-
- See the [requirements] page for debugging information & tested configurations.
82-
- See the [FAQ] for common problems and questions.
83-
- Create an [issue](https://github.com/junegunn/vim-plug/issues/new).
81+
- See [tutorial] page to learn the basics of vim-plug
82+
- See [tips] and [FAQ] pages for common problems and questions
83+
- See [requirements] page for debugging information & tested configurations
84+
- Create an [issue](https://github.com/junegunn/vim-plug/issues/new)
8485

86+
[tutorial]: https://github.com/junegunn/vim-plug/wiki/tutorial
87+
[tips]: https://github.com/junegunn/vim-plug/wiki/tips
8588
[FAQ]: https://github.com/junegunn/vim-plug/wiki/faq
8689
[requirements]: https://github.com/junegunn/vim-plug/wiki/requirements
8790

‎doc/plug.txt‎

Lines changed: 376 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,376 @@
1+
plug.txt plug Last change: November 27 2017
2+
PLUG - TABLE OF CONTENTS *plug* *plug-toc*
3+
==============================================================================
4+
5+
vim-plug
6+
Pros.
7+
Installation
8+
Vim
9+
Unix
10+
Windows (PowerShell)
11+
Neovim
12+
Unix
13+
Windows (PowerShell)
14+
Getting Help
15+
Usage
16+
Example
17+
Commands
18+
Plug options
19+
Global options
20+
Keybindings
21+
Example: A small sensible Vim configuration
22+
On-demand loading of plugins
23+
Post-update hooks
24+
PlugInstall! and PlugUpdate!
25+
Articles
26+
License
27+
28+
VIM-PLUG *vim-plug*
29+
==============================================================================
30+
31+
A minimalist Vim plugin manager.
32+
33+
https://raw.githubusercontent.com/junegunn/i/master/vim-plug/installer.gif
34+
35+
36+
< Pros. >_____________________________________________________________________~
37+
*plug-pros*
38+
39+
- Easier to setup: Single file. No boilerplate code required.
40+
- Easier to use: Concise, intuitive syntax
41+
- {Super-fast}{1} parallel installation/update (with any of `+job`, `+python`,
42+
`+python3`, `+ruby`, or {Neovim}{2})
43+
- Creates shallow clones to minimize disk space usage and download time
44+
- On-demand loading for {faster startup time}{3}
45+
- Can review and rollback updates
46+
- Branch/tag/commit support
47+
- Post-update hooks
48+
- Support for externally managed plugins
49+
50+
{1} https://raw.githubusercontent.com/junegunn/i/master/vim-plug/40-in-4.gif
51+
{2} http://neovim.org/
52+
{3} https://github.com/junegunn/vim-startuptime-benchmark#result
53+
54+
55+
< Installation >______________________________________________________________~
56+
*plug-installation*
57+
58+
{Download plug.vim}{4} and put it in the "autoload" directory.
59+
60+
{4} https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
61+
62+
63+
Vim~
64+
*plug-vim*
65+
66+
67+
>> Unix~
68+
>
69+
curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
70+
https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
71+
<
72+
You can automate the process by putting the command in your Vim configuration
73+
file as suggested {here}{5}.
74+
75+
{5} https://github.com/junegunn/vim-plug/wiki/tips#automatic-installation
76+
77+
78+
>> Windows (PowerShell)~
79+
>
80+
md ~\vimfiles\autoload
81+
$uri = 'https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim'
82+
(New-Object Net.WebClient).DownloadFile(
83+
$uri,
84+
$ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath(
85+
"~\vimfiles\autoload\plug.vim"
86+
)
87+
)
88+
<
89+
90+
Neovim~
91+
*plug-neovim*
92+
93+
94+
>> Unix~
95+
>
96+
curl -fLo ~/.local/share/nvim/site/autoload/plug.vim --create-dirs \
97+
https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
98+
<
99+
100+
>> Windows (PowerShell)~
101+
>
102+
md ~\AppData\Local\nvim\autoload
103+
$uri = 'https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim'
104+
(New-Object Net.WebClient).DownloadFile(
105+
$uri,
106+
$ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath(
107+
"~\AppData\Local\nvim\autoload\plug.vim"
108+
)
109+
)
110+
<
111+
112+
< Getting Help >______________________________________________________________~
113+
*plug-getting-help*
114+
115+
- See {tutorial}{6} page to learn the basics of vim-plug
116+
- See {tips}{7} and {FAQ}{8} pages for common problems and questions
117+
- See {requirements}{9} page for debugging information & tested configurations
118+
- Create an {issue}{10}
119+
120+
{6} https://github.com/junegunn/vim-plug/wiki/tutorial
121+
{7} https://github.com/junegunn/vim-plug/wiki/tips
122+
{8} https://github.com/junegunn/vim-plug/wiki/faq
123+
{9} https://github.com/junegunn/vim-plug/wiki/requirements
124+
{10} https://github.com/junegunn/vim-plug/issues/new
125+
126+
127+
< Usage >_____________________________________________________________________~
128+
*plug-usage*
129+
130+
Add a vim-plug section to your `~/.vimrc` (or `~/.config/nvim/init.vim` for
131+
Neovim):
132+
133+
*plug#begin* *plug#end*
134+
135+
1. Begin the section with `call plug#begin()`
136+
2. List the plugins with `Plug` commands
137+
3. `call plug#end()` to update 'runtimepath' and initialize plugin system
138+
- Automatically executes `filetype plugin indent on` and `syntax enable`.
139+
You can revert the settings after the call. e.g. `filetype indent off`,
140+
`syntax off`, etc.
141+
142+
143+
Example~
144+
*plug-example*
145+
>
146+
" Specify a directory for plugins
147+
" - For Neovim: ~/.local/share/nvim/plugged
148+
" - Avoid using standard Vim directory names like 'plugin'
149+
call plug#begin('~/.vim/plugged')
150+
151+
" Make sure you use single quotes
152+
153+
" Shorthand notation; fetches https://github.com/junegunn/vim-easy-align
154+
Plug 'junegunn/vim-easy-align'
155+
156+
" Any valid git URL is allowed
157+
Plug 'https://github.com/junegunn/vim-github-dashboard.git'
158+
159+
" Multiple Plug commands can be written in a single line using | separators
160+
Plug 'SirVer/ultisnips' | Plug 'honza/vim-snippets'
161+
162+
" On-demand loading
163+
Plug 'scrooloose/nerdtree', { 'on': 'NERDTreeToggle' }
164+
Plug 'tpope/vim-fireplace', { 'for': 'clojure' }
165+
166+
" Using a non-master branch
167+
Plug 'rdnetto/YCM-Generator', { 'branch': 'stable' }
168+
169+
" Using a tagged release; wildcard allowed (requires git 1.9.2 or above)
170+
Plug 'fatih/vim-go', { 'tag': '*' }
171+
172+
" Plugin options
173+
Plug 'nsf/gocode', { 'tag': 'v.20150303', 'rtp': 'vim' }
174+
175+
" Plugin outside ~/.vim/plugged with post-update hook
176+
Plug 'junegunn/fzf', { 'dir': '~/.fzf', 'do': './install --all' }
177+
178+
" Unmanaged plugin (manually installed and updated)
179+
Plug '~/my-prototype-plugin'
180+
181+
" Initialize plugin system
182+
call plug#end()
183+
<
184+
*:PlugInstall*
185+
186+
Reload .vimrc and `:PlugInstall` to install plugins.
187+
188+
189+
< Commands >__________________________________________________________________~
190+
*plug-commands*
191+
192+
------------------------------------+-------------------------------------------------------------------
193+
Command | Description ~
194+
------------------------------------+-------------------------------------------------------------------
195+
`PlugInstall [name ...] [#threads]` | Install plugins
196+
`PlugUpdate [name ...] [#threads]` | Install or update plugins
197+
`PlugClean[!]` | Remove unused directories (bang version will clean without prompt)
198+
`PlugUpgrade` | Upgrade vim-plug itself
199+
`PlugStatus` | Check the status of plugins
200+
`PlugDiff` | Examine changes from the previous update and the pending changes
201+
`PlugSnapshot[!] [output path]` | Generate script for restoring the current snapshot of the plugins
202+
------------------------------------+-------------------------------------------------------------------
203+
204+
205+
< Plug options >______________________________________________________________~
206+
*plug-options*
207+
208+
------------------------+-----------------------------------------------
209+
Option | Description ~
210+
------------------------+-----------------------------------------------
211+
`branch` / `tag` / `commit` | Branch/tag/commit of the repository to use
212+
`rtp` | Subdirectory that contains Vim plugin
213+
`dir` | Custom directory for the plugin
214+
`as` | Use different name for the plugin
215+
`do` | Post-update hook (string or funcref)
216+
`on` | On-demand loading: Commands or <Plug>-mappings
217+
`for` | On-demand loading: File types
218+
`frozen` | Do not update unless explicitly specified
219+
------------------------+-----------------------------------------------
220+
221+
222+
< Global options >____________________________________________________________~
223+
*plug-global-options*
224+
225+
*g:plug_threads* *g:plug_timeout* *g:plug_retries* *g:plug_shallow* *g:plug_window*
226+
*g:plug_pwindow* *g:plug_url_format*
227+
228+
--------------------+-----------------------------------+-----------------------------------------------------------------------------------
229+
Flag | Default | Description ~
230+
--------------------+-----------------------------------+-----------------------------------------------------------------------------------
231+
`g:plug_threads` | 16 | Default number of threads to use
232+
`g:plug_timeout` | 60 | Time limit of each task in seconds (Ruby & Python)
233+
`g:plug_retries` | 2 | Number of retries in case of timeout (Ruby & Python)
234+
`g:plug_shallow` | 1 | Use shallow clone
235+
`g:plug_window` | `vertical topleft new` | Command to open plug window
236+
`g:plug_pwindow` | `above 12new` | Command to open preview window in `PlugDiff`
237+
`g:plug_url_format` | `https://git::@github.com/%s.git` | `printf` format to build repo URL (Only applies to the subsequent `Plug` commands)
238+
--------------------+-----------------------------------+-----------------------------------------------------------------------------------
239+
240+
241+
< Keybindings >_______________________________________________________________~
242+
*plug-keybindings*
243+
244+
*:PlugStatus* *:PlugDiff*
245+
246+
- `D` - `PlugDiff`
247+
- `S` - `PlugStatus`
248+
- `R` - Retry failed update or installation tasks
249+
- `U` - Update plugins in the selected range
250+
- `q` - Close the window
251+
- `:PlugStatus`
252+
- `L` - Load plugin
253+
- `:PlugDiff`
254+
- `X` - Revert the update
255+
256+
257+
< Example: A small sensible Vim configuration >_______________________________~
258+
*plug-example-a-small-sensible-vim-configuration*
259+
>
260+
call plug#begin()
261+
Plug 'tpope/vim-sensible'
262+
call plug#end()
263+
<
264+
265+
< On-demand loading of plugins >______________________________________________~
266+
*plug-on-demand-loading-of-plugins*
267+
>
268+
" NERD tree will be loaded on the first invocation of NERDTreeToggle command
269+
Plug 'scrooloose/nerdtree', { 'on': 'NERDTreeToggle' }
270+
271+
" Multiple commands
272+
Plug 'junegunn/vim-github-dashboard', { 'on': ['GHDashboard', 'GHActivity'] }
273+
274+
" Loaded when clojure file is opened
275+
Plug 'tpope/vim-fireplace', { 'for': 'clojure' }
276+
277+
" Multiple file types
278+
Plug 'kovisoft/paredit', { 'for': ['clojure', 'scheme'] }
279+
280+
" On-demand loading on both conditions
281+
Plug 'junegunn/vader.vim', { 'on': 'Vader', 'for': 'vader' }
282+
283+
" Code to execute when the plugin is lazily loaded on demand
284+
Plug 'junegunn/goyo.vim', { 'for': 'markdown' }
285+
autocmd! User goyo.vim echom 'Goyo is now loaded!'
286+
<
287+
`for` option is generally not needed as most plugins for specific file types
288+
usually don't have too much code in `plugin` directory. You might want to
289+
examine the output of `vim --startuptime` before applying the option.
290+
291+
292+
< Post-update hooks >_________________________________________________________~
293+
*plug-post-update-hooks*
294+
295+
There are some plugins that require extra steps after installation or update.
296+
In that case, use `do` option to describe the task to be performed.
297+
>
298+
Plug 'Shougo/vimproc.vim', { 'do': 'make' }
299+
Plug 'Valloric/YouCompleteMe', { 'do': './install.py' }
300+
<
301+
If the value starts with `:`, it will be recognized as a Vim command.
302+
303+
*:GoInstallBinaries*
304+
>
305+
Plug 'fatih/vim-go', { 'do': ':GoInstallBinaries' }
306+
<
307+
If you need more control, you can pass a reference to a Vim function that
308+
takes a single argument.
309+
>
310+
function! BuildYCM(info)
311+
" info is a dictionary with 3 fields
312+
" - name: name of the plugin
313+
" - status: 'installed', 'updated', or 'unchanged'
314+
" - force: set on PlugInstall! or PlugUpdate!
315+
if a:info.status == 'installed' || a:info.force
316+
!./install.py
317+
endif
318+
endfunction
319+
320+
Plug 'Valloric/YouCompleteMe', { 'do': function('BuildYCM') }
321+
<
322+
Both forms of post-update hook are executed inside the directory of the plugin
323+
and only run when the repository has changed, but you can force it to run
324+
unconditionally with the bang-versions of the commands: `PlugInstall!` and
325+
`PlugUpdate!`.
326+
327+
Make sure to escape BARs and double-quotes when you write `do` option inline
328+
as they are mistakenly recognized as command separator or the start of the
329+
trailing comment.
330+
>
331+
Plug 'junegunn/fzf', { 'do': 'yes \| ./install' }
332+
<
333+
But you can avoid the escaping if you extract the inline specification using a
334+
variable (or any Vimscript expression) as follows:
335+
336+
*g:fzf_install*
337+
>
338+
let g:fzf_install = 'yes | ./install'
339+
Plug 'junegunn/fzf', { 'do': g:fzf_install }
340+
<
341+
342+
< PlugInstall! and PlugUpdate! >______________________________________________~
343+
*pluginstall-and-plugupdate*
344+
345+
The installer takes the following steps when installing/updating a plugin:
346+
347+
1. `git clone` or `git fetch` from its origin
348+
2. Check out branch, tag, or commit and optionally `git merge` remote branch
349+
3. If the plugin was updated (or installed for the first time)
350+
1. Update submodules
351+
2. Execute post-update hooks
352+
353+
The commands with `!` suffix ensure that all steps are run unconditionally.
354+
355+
356+
< Articles >__________________________________________________________________~
357+
*plug-articles*
358+
359+
- {Writing my own Vim plugin manager}{11}
360+
- {Vim plugins and startup time}{12}
361+
- ~~{Thoughts on Vim plugin dependency}{13}~~
362+
- Support for Plugfile has been removed since 0.5.0
363+
364+
{11} http://junegunn.kr/2013/09/writing-my-own-vim-plugin-manager
365+
{12} http://junegunn.kr/2014/07/vim-plugins-and-startup-time
366+
{13} http://junegunn.kr/2013/09/thoughts-on-vim-plugin-dependency
367+
368+
369+
< License >___________________________________________________________________~
370+
*plug-license*
371+
372+
MIT
373+
374+
375+
==============================================================================
376+
vim:tw=78:sw=2:ts=2:ft=help:norl:nowrap:

0 commit comments

Comments
 (0)