Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

executable file 450 lines (342 sloc) 18.024 kb
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
*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#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/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.



vim:tw=78:fo=tcq2:isk=!-~,^*,^|,^":ts=8:ft=help:norl:
Something went wrong with that request. Please try again.