Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/tomtom/tplugin_vim

An on-demand runtimepath manager and plugin loader for vim (for handling plugins distributes, e.g., as git repositories)
https://github.com/tomtom/tplugin_vim

Last synced: 7 months ago
JSON representation

An on-demand runtimepath manager and plugin loader for vim (for handling plugins distributes, e.g., as git repositories)

Awesome Lists containing this project

README 

          
NOTE: This plugin is obsoleted by https://github.com/tomtom/enabler_vim



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 

|| 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.



-----------------------------------------------------------------------



Status:  Works for me (there may be some minor quirks)

Install: See http://github.com/tomtom/vimtlib/blob/master/INSTALL.TXT

See http://github.com/tomtom for related plugins.