/
tplugin.txt
executable file
·557 lines (433 loc) · 22.1 KB
/
tplugin.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
*tplugin.txt* A simple plugin loader/runtimepath manager
Author: Tom Link, micathom at gmail com
tplugin is a plugin management tool similar to pathogen. Other than
pathogen tplugin expands the 'runtimepath' as needed (e.g. when
calling a command or function that is defined in a bundle) in order to
have minimal impact on startup time.
This plugin helps users to deal with plugins that are distributed via
source code repositories. Usually, you would make those plugins
available to vim by adding the local copies of those repositories to
|runtimepath|. The disadvantage of this approach is that the value of
|runtimepath| becomes unnecessarily complex. If this is done at startup (e.g.
when using the pathogen plugin), all plugins are loaded on each startup, which
takes time.
tplugin scans the local copies of those repositories for commands and
functions. It then amends the |runtimepath| only if a respective
command/function/map is called (similar to the AsNeeded plugin). This
helps to keep your |runtimepath| simple and improve startup time.
In order to achieve this goal, plugins are installed in an alternative
directory structure where each plugin (consequently referred to as
"repo" or "bundle") is installed in a subdirectory. tplugin takes care of
"modifying 'runtimepath' and of loading the vim script files as necessary. For
"compatibility with pathogen, all "bundle" subdirectories in the 'runtimepath'
"are considered as roots -- unless tplugin seems to be installed as repo itself.
alternative directory layout:
ROOT/
repo1/
after/
autoload/
doc/
plugin/
repo2/
after/
autoload/
doc/
plugin/
...
Repos can be enabled (i.e. added to 'runtimepath') either explicitly
with the |:TPlugin| command or automatically by calling a command,
function, or by requesting a filetype plugin/syntax/indent file defined
in a repo -- i.e. tplugin also provides an autoload facility similar to
the AsNeeded plugin (vimscript #915). See below for details.
The main purpose of this plugin was to facilitate the use of plugins
that are downloaded from a VCS like git, svn etc. But it can also be
used to handle plugins distributed as zip or tgz archives. For vimballs,
you'll might have to use a non-standard vimball unpacker---like the one
that can be found in the vimtlib repository.
You can have more than one root directory although it currently (as of
version 0.2) could cause problems and is deprecated.
Usage~
By default, tplugin has autoload enabled. With autoload, you can use
tplugin by
(1) loading the macro in your |vimrc| file >
" Put this close to the top of your vimrc file
runtime macros/tplugin.vim
(2) (optional step) setting non-standard root directories. The standard
root-directory is where tplugin was installed in (see |:TPluginRoot|). >
" Only necessary if you use a non-standard root directory
TPluginRoot /home/x/src/bundle
It might still be necessary to load certain plugins right on startup for them
to work properly.
(3) Start vim and collect the autoload information by running the
|:TPluginScan| command.
(4) Restart vim.
The plugins will be loaded as soon as one of its functions or
commands is called for the first time.
Full example as it could be found in a |vimrc| file: >
runtime macros/tplugin.vim
TPluginRoot F:\vim-addons
TPlugin vim-surround
let g:snippets_dir = 'X:\vimfiles\snippets,F:\vim-addons\snipmate.vim\snippets'
TPlugin snipmate.vim
TPlugin! tlib_vim 02tlib
*tplugin-dependencies*
*tplugin-metadata*
When enabling a repository (ROOT/REPO), e.g., by calling |:TPlugin|,
the files ROOT/_tplugin_REPO.vim and ROOT/REPO/_tplugin.vim are
loaded. These files allows users (or plugin developers) to, e.g.,
define dependencies (see |:TPluginBefore| and |:TPluginAfter|).
CAVEAT: If you have a file after/plugin/foo.vim in you user vimfiles
directory, this file will be loaded before any "managed" plugin "foo".
You thus have to check in your after/plugin/foo.vim file if the plugin
was already loaded.
Contrary to the default plugin behaviour, those managed plugins are
loaded when the |VimEnter| event is triggered, i.e. after all plugins
(incl. the after directory) and |gvimrc| was loaded. This approach
provides for a better control of which plugins should be loaded. You can
load a managed plugin immediately by adding a bang '!' to the |:TPlugin|
command.
*tplugin-asneeded*
AsNeeded Users~
tplugin can serve as a drop-in replacement for the AsNeeded plugin. Add
the following command to you |vimrc| file: >
TPluginRoot ~/vimfiles/AsNeeded/*
Alternatively, move the files the AsNeeded subdirectory to
REPOS/AsNeeded/plugin/.
Run |:TPluginScan| in order to create autoload definitions for commands
and functions.
Contrary to the AsNeeded plugin, tplugin only supports autoload for
|<Plug>| type of maps. Other autoload maps have to be defined by the
user using the |TPluginMap()| function.
Related work~
- Marc Weber's vim-addon-manager (my main source of inspiration for
this script), which also provides downloading plugins and
automatic dependency management:
http://github.com/MarcWeber/vim-addon-manager (vimscript #2905)
- Tim Pope's pathogen (vimscript #2332).
- Charles E. Campbell's AsNeeded (vimscript #915)
- A comprehensive list of plugin managers (download and update local copies
of vim plugins): http://vim-scripts.org/tools.html
- The ruby script I personally use to update local copies of source
code repositories: http://github.com/tomtom/vcsdo
If your VIM has compiled-in ruby support, you can use the :TPluginUpdate
command to run vcsdo from within VIM.
-----------------------------------------------------------------------
Install~
Edit the vba file and type: >
:so %
See :help vimball for details. If you have difficulties or use vim 7.0,
please make sure, you have the current version of vimball
(vimscript #1502) installed or update your runtime.
Optional: If tlib (vimscript #1863) is available, its progressbar will
be used to visualize the scan progress.
Also available via git: http://github.com/tomtom/tplugin_vim/
========================================================================
Contents~
g:tplugin_autoload .......................... |g:tplugin_autoload|
g:tplugin_menu_prefix ....................... |g:tplugin_menu_prefix|
g:tplugin_file .............................. |g:tplugin_file|
g:tplugin_load_plugin ....................... |g:tplugin_load_plugin|
:TPlugin .................................... |:TPlugin|
:TPluginRoot ................................ |:TPluginRoot|
:TPluginScan ................................ |:TPluginScan|
:TPluginBefore .............................. |:TPluginBefore|
:TPluginAfter ............................... |:TPluginAfter|
:TPluginUpdate .............................. |:TPluginUpdate|
TPluginMap .................................. |TPluginMap()|
TPluginFunction ............................. |TPluginFunction()|
TPluginCommand .............................. |TPluginCommand()|
TPluginAddRoots ............................. |TPluginAddRoots()|
TPluginDependencies ......................... |TPluginDependencies()|
TPluginVimEnter ............................. |TPluginVimEnter()|
g:tplugin#autoload_exclude .................. |g:tplugin#autoload_exclude|
g:tplugin#scan .............................. |g:tplugin#scan|
g:tplugin#shallow_scan ...................... |g:tplugin#shallow_scan|
g:tplugin#show_helptags_errors .............. |g:tplugin#show_helptags_errors|
tplugin#ScanRoots ........................... |tplugin#ScanRoots()|
g:tplugin#vcsdo#script ...................... |g:tplugin#vcsdo#script|
g:tplugin#vcsdo#log_buffer .................. |g:tplugin#vcsdo#log_buffer|
g:tplugin#vcsdo#exclude_roots_rx ............ |g:tplugin#vcsdo#exclude_roots_rx|
g:tplugin#autoload_exclude .................. |g:tplugin#autoload_exclude|
g:tplugin#scan .............................. |g:tplugin#scan|
g:tplugin#shallow_scan ...................... |g:tplugin#shallow_scan|
g:tplugin#show_helptags_errors .............. |g:tplugin#show_helptags_errors|
tplugin#ScanRoots ........................... |tplugin#ScanRoots()|
========================================================================
macros/tplugin.vim~
*g:tplugin_autoload*
g:tplugin_autoload (default: 1)
Enable autoloading. See |:TPluginScan|, |:TPluginCommand|, and
|:TPluginFunction|.
Values:
1 ... Enable autoload (default)
2 ... Enable autoload and automatically run |:TPluginScan|
after updating tplugin.
*g:tplugin_menu_prefix*
g:tplugin_menu_prefix (default: '')
If autoload is enabled and this variable is non-empty, build a
menu with available plugins.
Menus are disabled by default because they are less useful
than one might think with autoload enabled.
A good choice for this variable would be, e.g.,
'Plugin.T&Plugin.'.
NOTE: You have to re-run |:TPluginScan| after setting this
value.
*g:tplugin_file*
g:tplugin_file (default: '_tplugin')
The prefix for tplugin control files.
*g:tplugin_load_plugin*
g:tplugin_load_plugin (default: [])
A list of pairs [REGEXP, VALUE] that determine how tplugin handles
autoload function calls and filetype plugins.
When an autoload function or filetype plugin is loaded, the
respective plugin is added to 'runtimepath'. This variable decides
whether the corresponding plugin should be loaded too. Possible
values are:
. :: Don't load any plugins
* :: Load all plugins (default if no REGEXP pattern matches the
full repo directory name)
*:TPlugin*
:TPlugin[!] REPOSITORY [PLUGINS ...]
IF REPOSITORY contains a slash or a backslash, it is considered the
path relative from the current root directory to the plugin directory.
This allows you to deal with repositories with a non-standard
directory layout. Otherwise it is assumed that the source files are
located in the "plugin" subdirectory.
IF PLUGIN is "-", the REPOSITORY will be enabled but no plugin will be
loaded.
*:TPluginRoot*
:TPluginRoot[!] DIRECTORY
Define the root directory for the following |:TPlugin| commands.
Read autoload information if available (see |g:tplugin_autoload| and
|:TPluginScan|).
With the optional <bang>, don't register commands, functions etc. when
scanning the root with |:TPluginScan|.
If DIRECTORY ends with "*", it doesn't refer to a directory hierarchy
à la vimfiles but to a single "flat" directory.
If tplugin was installed a directory called .vim or vimfiles, the
default root directory is the "bundle" subdirectory of the first
element in 'runtimepath'. Otherwise, the default root directory is the
directory where tplugin_vim was installed in, i.e. this assumes that
tplugin was loaded from ROOT/tplugin_vim/macros/tplugin.vim
Example: >
" A collection of git repositories
TPluginRoot ~/src/git_repos
" A directory with experimental plugins
TPluginRoot ~/vimfiles/experimental_plugins/*
<
*:TPluginScan*
:TPluginScan[!] [WHAT] [ROOT]
Scan the current root directory for commands and functions. Save
autoload information in "ROOT/_tplugin.vim".
Where WHAT is a set of letters determining the information being
collected. See |g:tplugin#scan| for details.
With the optional '!', the autocommands are immediatly usable.
Other than the AsNeeded plugin, tplugin doesn't support the creation
of autoload information for maps.
If you collect repositories in one than more directory, I'd suggest to
create a special script.
The source file may contain special markers that make :TPluginScan
include text in the _tplugin.vim file:
*@TPluginInclude*
Blocks of non-empty lines are introduced with an @TPluginInclude tag: >
" @TPluginInclude
augroup Foo
autocmd!
autocmd Filetype foo call foo#Init()
augroup END
< Special lines are prefixed with @TPluginInclude: >
" @TPluginInclude if !exists('g:foo') | let g:foo = 1 | endif
< Example: >
TPluginRoot dir1
TPluginScan
TPluginRoot dir2
TPluginScan
<
*:TPluginBefore*
:TPluginBefore FILE_RX COMMAND
|:execute| COMMAND after loading a file matching the |regexp| pattern
FILE_RX. The COMMAND is executed after the repo's path is added to the
'runtimepath'.
This command should be best put into ROOT/tplugin_REPO.vim files,
which are loaded when enabling a source repository.
Example: >
" Load master.vim before loading any plugin in a repo
TPluginBefore plugin/.\{-}\.vim runtime! macros/master.vim
< It can also be included in the comments of source files (you have
to prepend it with a "@"): >
"@TPluginBefore my_repo/autoload DoThis
let loaded_yup = 1
<
*:TPluginAfter*
:TPluginAfter FILE_RX COMMAND
|:execute| COMMAND after loading a file matching the |regexp| pattern
FILE_RX.
See also |:TPluginBefore|.
*:TPluginUpdate*
TPluginUpdate[!]
Update all repos (VCS types only).
Requires compiled-in ruby support and http://github.com/tomtom/vcsdo
to be installed. You also have to set |g:tplugin#vcsdo#script|.
With the optional !, show which commands would be issued but don't do
anything.
*TPluginMap()*
TPluginMap(map, repo, plugin, ?remap="")
MAP is a map command and the map. REPO and PLUGIN are the same as for
the |:TPlugin| command.
Examples: >
" Map for <plug>Foo:
call TPluginMap('map <plug>Foo', 'mylib', 'myplugin')
" Load the plugin when pressing <f3> and remap the key to an appropriate
" command from the autoloaded plugin:
call TPluginMap('map <f3>', 'mylib', 'myplugin', ':Foo<cr>')
<
*TPluginFunction()*
TPluginFunction(FUNCTION, REPOSITORY, [PLUGIN])
Load a certain plugin on demand (aka autoload) when FUNCTION is called
for the first time.
*TPluginCommand()*
TPluginCommand(COMMAND, REPOSITORY, [PLUGIN])
Load a certain plugin on demand (aka autoload) when COMMAND is called
for the first time. Then call the original command.
For most plugins, |:TPluginScan| will generate the appropriate
TPluginCommand commands for you. For some plugins, you'll have to
define autocommands yourself in the |vimrc| file.
Example: >
TPluginCommand TSelectBuffer vimtlib tselectbuffer
<
*TPluginAddRoots()*
TPluginAddRoots(?subdir="bundle")
Add all directories named SUBDIR as roots.
*TPluginDependencies()*
TPluginDependencies(repo, deps)
*TPluginVimEnter()*
TPluginVimEnter(group)
========================================================================
autoload/tplugin.vim~
*g:tplugin#autoload_exclude*
g:tplugin#autoload_exclude (default: ['tplugin'])
A list of repositories for which autoload is disabled when running
|:TPluginScan|.
*g:tplugin#scan*
g:tplugin#scan (default: 'cfptham_')
The default value for |:TPluginScan|. A set of identifiers
determining the information being collected:
c ... commands
f ... functions
p ... <plug> maps
t ... filetypes
h ... helptags if not available
a ... autoload
m ... parse vim-addon-manager metadata
_ ... include _tplugin.vim files
all ... all of the above
*g:tplugin#shallow_scan*
g:tplugin#shallow_scan (default: 'hm')
*g:tplugin#show_helptags_errors*
g:tplugin#show_helptags_errors (default: 1)
If true, show errors when running :helptags.
*tplugin#ScanRoots()*
tplugin#ScanRoots(immediate, roots, shallow_roots, args)
Write autoload information for each root directory to
"ROOT/_tplugin.vim".
Search in autoload/tplugin/autoload/*.vim for prefabricated autoload
definitions. The file's basenames are repo names.
*g:tplugin#autoload_exclude*
g:tplugin#autoload_exclude (default: ['tplugin'])
A list of repositories for which autoload is disabled when running
|:TPluginScan|.
*g:tplugin#scan*
g:tplugin#scan (default: 'cfptham_')
The default value for |:TPluginScan|. A set of identifiers
determining the information being collected:
c ... commands
f ... functions
p ... <plug> maps
t ... filetypes
h ... helptags if not available
a ... autoload
m ... parse vim-addon-manager metadata
_ ... include _tplugin.vim files
all ... all of the above
*g:tplugin#shallow_scan*
g:tplugin#shallow_scan (default: 'hm')
*g:tplugin#show_helptags_errors*
g:tplugin#show_helptags_errors (default: 1)
If true, show errors when running :helptags.
*tplugin#ScanRoots()*
tplugin#ScanRoots(immediate, roots, shallow_roots, args)
Write autoload information for each root directory to
"ROOT/_tplugin.vim".
Search in autoload/tplugin/autoload/*.vim for prefabricated autoload
definitions. The file's basenames are repo names.
========================================================================
autoload/tplugin/vcsdo.vim~
*g:tplugin#vcsdo#script*
g:tplugin#vcsdo#script (default: '')
The filename of the vcsdo executable.
*g:tplugin#vcsdo#log_buffer*
g:tplugin#vcsdo#log_buffer (default: '__TPluginUpdateLog__')
Name of the log buffer.
If empty, print log lines as messages.
*g:tplugin#vcsdo#exclude_roots_rx*
g:tplugin#vcsdo#exclude_roots_rx (default: '')
Don't update root directories matching this |regexp|.
========================================================================
autoload/tplugin.vim~
*g:tplugin#autoload_exclude*
g:tplugin#autoload_exclude (default: ['tplugin'])
A list of repositories for which autoload is disabled when running
|:TPluginScan|.
*g:tplugin#scan*
g:tplugin#scan (default: 'cfptham_')
The default value for |:TPluginScan|. A set of identifiers
determining the information being collected:
c ... commands
f ... functions
p ... <plug> maps
t ... filetypes
h ... helptags if not available
a ... autoload
m ... parse vim-addon-manager metadata
_ ... include _tplugin.vim files
all ... all of the above
*g:tplugin#shallow_scan*
g:tplugin#shallow_scan (default: 'hm')
*g:tplugin#show_helptags_errors*
g:tplugin#show_helptags_errors (default: 1)
If true, show errors when running :helptags.
*tplugin#ScanRoots()*
tplugin#ScanRoots(immediate, roots, shallow_roots, args)
Write autoload information for each root directory to
"ROOT/_tplugin.vim".
Search in autoload/tplugin/autoload/*.vim for prefabricated autoload
definitions. The file's basenames are repo names.
*g:tplugin#autoload_exclude*
g:tplugin#autoload_exclude (default: ['tplugin'])
A list of repositories for which autoload is disabled when running
|:TPluginScan|.
*g:tplugin#scan*
g:tplugin#scan (default: 'cfptham_')
The default value for |:TPluginScan|. A set of identifiers
determining the information being collected:
c ... commands
f ... functions
p ... <plug> maps
t ... filetypes
h ... helptags if not available
a ... autoload
m ... parse vim-addon-manager metadata
_ ... include _tplugin.vim files
all ... all of the above
*g:tplugin#shallow_scan*
g:tplugin#shallow_scan (default: 'hm')
*g:tplugin#show_helptags_errors*
g:tplugin#show_helptags_errors (default: 1)
If true, show errors when running :helptags.
*tplugin#ScanRoots()*
tplugin#ScanRoots(immediate, roots, shallow_roots, args)
Write autoload information for each root directory to
"ROOT/_tplugin.vim".
Search in autoload/tplugin/autoload/*.vim for prefabricated autoload
definitions. The file's basenames are repo names.
vim:tw=78:fo=tcq2:isk=!-~,^*,^|,^":ts=8:ft=help:norl: