= Jetpack.vim

Jetpack.vim is a plugin manager for https://vim.org[Vim], https://neovim.io[Neovim], and https://github.com/terrychou/iVim[iVim].

The lightning-fast minimalist plugin manager for Vim/ Neovim. vim-jetpack is a jetpack for the most of vimmers. Unbelievably, it is faster than vimrc uses the built-in plugin manager only.

image::https://user-images.githubusercontent.com/5019902/154419764-d246c45c-8940-4e60-9658-9ed3424cbeaa.gif[]

== Features

• Single file installation
  ** You need to just download a single file and put it.
• First-class Lua support
  ** This plugin is not written in Lua but we provide a Lua API.
• Fancy User Interface
  ** You can see a progress of installation with a graphical progress bar.
• pack/*/start -free installation
  ** You can install plugins without pack/*/start directory.
• Git-free installation
  ** You can optionally install plugins without git.

== Installation

The installation is very simple. You just need to download a single file and put it on the runtimepath.

[source]

https://raw.githubusercontent.com/tani/vim-jetpack/master/plugin/jetpack.vim

The following is an example of installation with cURL command.

.Vim for Linux and macOS
[%collapsible]

[source]

curl -fLo ~/.vim/pack/jetpack/opt/vim-jetpack/plugin/jetpack.vim --create-dirs https://raw.githubusercontent.com/tani/vim-jetpack/master/plugin/jetpack.vim

====

.Neovim for Linux and macOS
[%collapsible]

[source]

curl -fLo ~/.local/share/nvim/site/pack/jetpack/opt/vim-jetpack/plugin/jetpack.vim --create-dirs https://raw.githubusercontent.com/tani/vim-jetpack/master/plugin/jetpack.vim

====

.Vim for Windows
[%collapsible]

[source]

curl -fLo %USERPROFILE%\vimfiles\pack\jetpack\opt\vim-jetpack\plugin\jetpack.vim --create-dirs https://raw.githubusercontent.com/tani/vim-jetpack/master/plugin/jetpack.vim

====

.Neovim for Windows
[%collapsible]

[source]

curl -fLo %USERPROFILE%\AppData\Local\nvim-data\site\pack\jetpack\opt\vim-jetpack\plugin\jetpack.vim --create-dirs https://raw.githubusercontent.com/tani/vim-jetpack/master/plugin/jetpack.vim

====

TIP: There exists an option for automatic installation on startup. Fore more details, see Configuration Snippets.

== Usage

Jetpack was initially implemented as a successor of vim-plug. Nowadays, we also provide compatibility layers for other plugin managers, dein.vim, packer.nvim.nvim, and paq.nvim.nvim. You can use Jetpack as a drop-in replacement of them. In personal opinion, vim-plug style is the most stable and easy to use.

=== Vim-plug style

[source, vim]

packadd vim-jetpack
call jetpack#begin()
Jetpack 'tani/vim-jetpack', {'opt': 1} "bootstrap
Jetpack 'https://github.com/dense-analysis/ale'
Jetpack 'junegunn/fzf.vim'
Jetpack 'junegunn/fzf', { 'do': {-> fzf#install()} }
Jetpack 'neoclide/coc.nvim', { 'branch': 'release' }
Jetpack 'neoclide/coc.nvim', { 'branch': 'master', 'do': 'yarn install --frozen-lockfile' }
Jetpack 'vlime/vlime', { 'rtp': 'vim' }
Jetpack 'dracula/vim', { 'as': 'dracula' }
Jetpack 'tpope/vim-fireplace', { 'for': 'clojure' }
call jetpack#end()

=== Dein.vim style

[source, vim]

packadd vim-jetpack
call jetpack#begin()
call jetpack#load_toml('path/to/dein.toml')
call jetpack#add('tani/vim-jetpack', {'opt': 1}) "bootstrap
call jetpack#add('https://github.com/dense-analysis/ale')
call jetpack#add('junegunn/fzf.vim')
call jetpack#add('junegunn/fzf', { 'build': './install' })
call jetpack#add('neoclide/coc.nvim', { 'branch': 'release' })
call jetpack#add('neoclide/coc.nvim', { 'branch': 'master', 'build': 'yarn install --frozen-lockfile' })
call jetpack#add('vlime/vlime', { 'rtp': 'vim' })
call jetpack#add('dracula/vim', { 'name': 'dracula' })
call jetpack#add('tpope/vim-fireplace', { 'on_ft': 'clojure' })
call jetpack#end()

[source, toml]

[[plugins]] repo = 'tani/vim-jetpack'

[[plugins]]
repo = 'tpope/vim-fugitive'
on_cmd = 'Git'
hook_source = '''
let g:fugitive_no_mappings = 1
'''
hook_post_source = '''
echom 'fugitive is loaded'
'''

=== Legacy packer.nvim style

[source, lua]

-- Packer.nvim v1
vim.cmd('packadd vim-jetpack')
require('jetpack.packer').startup(function(use)
use { 'tani/vim-jetpack' } -- bootstrap
use 'https://github.com/dense-analysis/ale'
use 'junegunn/fzf.vim'
use {'junegunn/fzf', run = 'call fzf#install()' }
use {'neoclide/coc.nvim', branch = 'release'}
use {'neoclide/coc.nvim', branch = 'master', run = 'yarn install --frozen-lockfile'}
use {'vlime/vlime', rtp = 'vim' }
use {'dracula/vim', as = 'dracula' }
use {'tpope/vim-fireplace', ft = 'clojure' },
use {'nvim-treesitter/nvim-treesitter',
run = ':TSUpdate',
config = function()
require'nvim-treesitter.configs'.setup {
ensure_installed = 'maintained',
highlight = { enable = true }
}
end
}
end)

=== Modern packer.nvim/ paq.nvim style

[source, lua]

-- Packer.nvim v2
vim.cmd('packadd vim-jetpack')
require('jetpack.packer').add {
{'tani/vim-jetpack'}, -- bootstrap
'https://github.com/dense-analysis/ale',
'junegunn/fzf.vim',
{'junegunn/fzf', run = 'call fzf#install()' },
{'neoclide/coc.nvim', branch = 'release'},
{'neoclide/coc.nvim', branch = 'master', run = 'yarn install --frozen-lockfile'},
{'vlime/vlime', rtp = 'vim' },
{'dracula/vim', as = 'dracula' },
{'tpope/vim-fireplace', ft = 'clojure' },
{'nvim-treesitter/nvim-treesitter',
run = ':TSUpdate',
config = function()
require'nvim-treesitter.configs'.setup {
ensure_installed = 'maintained',
highlight = { enable = true }
}
end
}
}

[source, lua]

-- Paq.nvim
vim.cmd('packadd vim-jetpack')
require('jetpack.paq') {
{'tani/vim-jetpack'}, -- bootstrap
'https://github.com/dense-analysis/ale',
'junegunn/fzf.vim',
{'junegunn/fzf', run = './install' },
{'neoclide/coc.nvim', branch = 'release'},
{'neoclide/coc.nvim', branch = 'master', run = 'yarn install --frozen-lockfile'},
{'dracula/vim', as = 'dracula' },
}

== Configuration

=== Configuration Variables

We provide configuration variables to change the internal behaviors: copying files, downloading plugins.

g:jetpack_download_method:: Jetpack downloads plugins with git by default. Further, Jetpack can download plugins with git, cURL, and wget This is useful for environments without git. Non-git options are not recommended because they are slower than git as jeptack downloads the whole repository as a tar archive.

[TIP]
.iVim does not have git command.

We recommend the following configuration to avoid
the external commands except cURL.
[source, vim]

let g:jetpack_download_method = 'curl'

====

=== Configuration Parameters

CAUTION: You might be able to use another configuration parameters, you can use on_cmd in vim-plug style for example, but it might be going to be removed in the future. Thus, we recommend you not to use unlisted configuration parameters.

==== Vim-plug style

You can pass the configuration parameters to Jetpack command as follows.

[source, vim]

Jetpack 'tani/vim-jetpack', { 'as': 'jetpack' }

The following is a list of configuration parameters for vim-plug style.

[%autowidth] |=== |Parameter|Type|Description

|on |string or array | On-demand loading plugins by commands, keymaps.

|for |string or array | On-demand loading plugins by filetypes.

|branch |string | Install plugins from the specified branch.

|commit |string | Install plugins from the specified commit.

|tag |string | Install plugins from the specified tag.

|rtp |string | Add the specified directory to the runtimepath.

|do |string or function | Execute the specified command after installation.

|as |string | Install plugins as the specified name.

|dir |string | Install plugins to the specified directory.

|frozen |boolean | Freeze plugins to the current version. |===

NOTE: Jetpack mechanically distinguishes :SomeCommand and <Plug>(some-command), and the external command, for on parameters and do parameters.

==== Dein.vim style

You can pass the configuration parameters to jetpack#add function as follows.

[source, vim]

call jetpack#add('tani/vim-jetpack', { 'name': 'jetpack' })

The following is a list of configuration parameters for dein.vim style. Note that we do not support full features of dein.vim. We are welcome to your pull requests to improve the compatibility.

[%autowidth] |=== |Parameter|Type|Description

|on_cmd |string or array | On-demand loading plugins by commands.

|on_ft |string or array | On-demand loading plugins by filetypes.

|on_map |string or array | On-demand loading plugins by keymaps.

|on_event |string or array | On-demand loading plugins by events.

|branch |string | Install plugins from the specified branch.

|commit |string | Install plugins from the specified commit.

|tag |string | Install plugins from the specified tag.

|path |string | Install plugins to the specified directory.

|rtp |string | Add the specified directory to the runtimepath.

|build |string | Execute the specified external command after installation.

|name |string | Install plugins as the specified name.

|merged |boolean | Merge plugins to the current runtimepath.

|frozen |boolean | Freeze plugins to the current version.

|depends |string or array | Load the specified plugins before the plugin.

|on_source |string or array | Load the plugin before the specified plugins.

|on_post_source |string or array | Load the plugin after the specified plugins.

|hook_add |string | Execute the specified Vim script at the end of jetpack#add function.

|hook_source |string | Execute the specified Vim script before loading the plugin.

|hook_post_source |string | Execute the specified Vim script after loading the plugin. |===

==== Legacy packer.nvim style

You can pass the configuration parameters to use function as follows.

[source, lua]

use { 'tani/vim-jetpack', as = 'jetpack' }

Note that we do not support full features of packer.nvim. We are welcome to your pull requests to improve the compatibility.

[%autowidth] |=== |Parameter|Type|Description

|opt |boolean | On-demand loading plugins by packadd

|cmd |string or array | On-demand loading plugins by commands.

|keys |string or array | On-demand loading plugins by keymaps.

|event |string or array | On-demand loading plugins by event.

|ft |string or array | On-demand loading plugins by filetypes.

|branch |string | Install plugins from the specified branch.

|commit |string | Install plugins from the specified commit.

|tag |string | Install plugins from the specified tag.

|rtp |string | Add the specified directory to the runtimepath.

|run |string or function | Execute the specified command after installation.

|as |string | Install plugins as the specified name.

|requires |string or array | Enable the plugin after the specified plugins.

|after |string or array | Enable the plugin after the specified plugins.

|before |string or array | Enable the plugin before the specified plugins.

|lock |boolean | Freeze plugins to the current version.

|config |function or string | Execute the specified function after startup.

|setup |function or string | Execute the specified function before startup. |===

CAUTION: Note that we do not install the specified plugins automatically. You have to declare the specified plugins by use function.

==== Modern packer.nvim/ paq.nvim style

WARNING: Modern packer.nvim style is still experimental. The configuration parameters might be changed in the future.

You can pass the configuration parameters to a table as follows.

[source, lua]

{ 'tani/vim-jetpack', as = 'jetpack' }

Note that we do not support full features of packer.nvim. We are welcome to your pull requests to improve the compatibility.

[%autowidth] |=== |Parameter|Type|Description

|opt |boolean | On-demand loading plugins by packadd

|cmd |string or array | On-demand loading plugins by commands.

|keys |string or array | On-demand loading plugins by keymaps.

|event |string or array | On-demand loading plugins by event.

|ft |string or array | On-demand loading plugins by filetypes.

|branch |string | Install plugins from the specified branch.

|commit |string | Install plugins from the specified commit.

|tag |string | Install plugins from the specified tag.

|rtp |string | Add the specified directory to the runtimepath.

|run |string or function | Execute the specified command after installation.

|as |string | Install plugins as the specified name.

|requires |string | Install plugins after the specified plugins.

|lock |boolean | Freeze plugins to the current version.

|config |function or string | Execute the specified function after startup.

|setup |function or string | Execute the specified function before startup. |===

=== Configuration Snippets

==== Automatic installation on startup

.Vim
[source, vim]

let s:jetpackfile = expand(':p:h') .. '/pack/jetpack/opt/vim-jetpack/plugin/jetpack.vim'
let s:jetpackurl = "https://raw.githubusercontent.com/tani/vim-jetpack/master/plugin/jetpack.vim"
if !filereadable(s:jetpackfile)
call system(printf('curl -fsSLo %s --create-dirs %s', s:jetpackfile, s:jetpackurl))
endif

.Neovim
[source, vim]

"neovim + vim
let s:jetpackfile = stdpath('data') .. '/site/pack/jetpack/opt/vim-jetpack/plugin/jetpack.vim'
let s:jetpackurl = "https://raw.githubusercontent.com/tani/vim-jetpack/master/plugin/jetpack.vim"
if !filereadable(s:jetpackfile)
call system(printf('curl -fsSLo %s --create-dirs %s', s:jetpackfile, s:jetpackurl))
endif

.Neovim with Lua
[source, lua]

local jetpackfile = vim.fn.stdpath('data') .. '/site/pack/jetpack/opt/vim-jetpack/plugin/jetpack.vim'
local jetpackurl = "https://raw.githubusercontent.com/tani/vim-jetpack/master/plugin/jetpack.vim"
if vim.fn.filereadable(jetpackfile) == 0 then
vim.fn.system(string.format('curl -fsSLo %s --create-dirs %s', jetpackfile, jetpackurl))
end

==== Automatic plugin installation on startup

.Vim and Neovim
[source, vim]

for name in jetpack#names()
if !jetpack#tap(name)
call jetpack#sync()
break
endif
endfor

.Neovim with Lua
[source, lua]

local jetpack = require('jetpack')
for _, name in ipairs(jetpack.names()) do
if not jetpack.tap(name) then
jetpack.sync()
break
end
end

==== Build cache of treesitter parsrs

[source, lua]

local parser_install_dir = vim.fn.stdpath "data" .. "/treesitter" vim.opt.runtimepath:append(parser_install_dir)

require("nvim-treesitter.configs").setup {
parser_install_dir = parser_install_dir,
...
}

== API

CAUTION: You might be able to use other functions, commands, and events. but it might be going to be removed in the future. Thus, we recommend you not to use unlisted ones.

=== VimL Function

• jetpack#begin([path])
  ** The function setups jetpack plugins. All plugin declarations should be
  placed after this function. You can give path if you want to use another
  directory to manage plugins.
• jetpack#add(repo [, options])
  ** repo is a pair of string concatenated with / such as tani/vim-jetpack.
  options is a dictionary. See below.
• jetpack#sync()
  ** The function performs to install, update, and bundle all plugins.
  The function is everything all you need to know.
  You must run this function after a change of your configuration.
• jetpack#end()
  ** The function loads declared plugins. All plugin declarations should be
  placed before this function.
• jetpack#tap(name)
  ** It returns a truthy value if the plugin is available,
  otherwise it returns a falsy value.
• jetpack#names()
  ** It returns the list of plugin names registered including unavailable
  plugins.
• jetpack#get(name)
  ** It returns metadata of the plugin if possible, otherwise it returns {}.
  This is the same as dein#get of dein.vim.
• jetpack#load(name)
  ** This is a wrapper function for packadd; since it fires config options,
  etc., it is recommended to use this instead of packadd.
• jetpack#load_toml(path)
  ** This function load dein-style toml settings.

=== Lua Function

All jetpack# functions are exported as jetpack module. You can call them using require('jetpack') as you want. Additionally, functions compatible with packer.nvim and paq.nvim are available.

• require('jetpack.paq')(config)
  ** This function loads plugins described in config like paq.nvim.
• require('jetpack.packer').startup(config)
  ** This function loads plugins described by use function like packer.nvim.
• require('jetpack.packer').add(config)
  ** This function loads plugins described by use function like packer.nvim.
• require('jetpack.packer').init(option)
  ** Now supported option is only package_root.

=== Commands

• :JetpackSync ** The function performs to install, update, and bundle all plugins. The function is everything all you need to know. You must run this function after a change of your configuration.

• :Jetpack repo [, options] ** A command version of jetpack#add(). It is useful for the vim-plug style declaration of plugins in vimrc.

=== Events

• User JetpackPre:{plugin-name}/ User JetpackPost:{plugin-name} ** Let {plugin-name} be the name of the plugin. The specified event is fired before/after the plugin is loaded.

• User Jetpack{PluginName}Pre/ User Jetpack{PluginName}Post ** Let {PluginName} be a CamelCase of plugin name. The specified event is fired before/after the plugin is loaded.

[%autowidth] |=== | plugin-name | EventName

| vim-jetpack | VimJetpack

| goyo.vim | GoyoVim

| vim_foo | VimFoo |===

=== Autocmd Groups

• Jetpack
  ** vim-jetpack's lazy loading system uses autocommands
  defined under Jetpack autocmd-group.

== Contributing

== License

Copyright (c) 2022 -- 2023 Masaya Taniguchi

The software is released under the MIT License, see the header of the source code.