vis-plug 🍜

A minimal plugin-manager for vis

vis-plug plugins are defined by a Lua file in a git repository and can be both a plugin or a theme.

Configure plugins in your visrc and use Commands to install and more.

Plugins are installed using git (in the background) to a cache folder and required on init.

Browse available plugins and themes at vis-plugins.

Install

Manual

Clone vis-plug to your vis plugins folder:

git clone https://github.com/erf/vis-plug "${XDG_CONFIG_HOME:-$HOME/.config}/vis/plugins/vis-plug"

Then require it in your visrc:

local plug = require('plugins/vis-plug')

Bootstrap

Or add the following to your visrc to automatically clone vis-plug on first run and require it:

local plug_path = (os.getenv('XDG_CONFIG_HOME') or os.getenv('HOME') .. '/.config') .. '/vis/plugins/vis-plug'
if not pcall(require, 'plugins/vis-plug') then
	os.execute('git clone --quiet https://github.com/erf/vis-plug "' .. plug_path .. '"')
end
local plug = require('plugins/vis-plug')

Configure

Configure plugins in your visrc as a list of tables given to the plug.init method.

Example:

local plug = require('plugins/vis-plug') -- or use the bootstrap above

-- configure plugins in an array of tables with git urls and options
local plugins = {

	-- load a plugin from a git repo (https://github.com/ is optional, loads 'init.lua' by default)
	{ 'erf/vis-cursors' },

	-- first parameter is a shorthand for 'url'
	{ url = 'erf/vis-cursors' },

	-- specify an alias to later use to access plugin variables (see example below)
	{ 'erf/vis-cursors', alias = 'cursors' },

	-- specify which lua file to load and a ref (commit, branch or tag) to checkout
	{ 'erf/vis-test', file = 'test', ref = 'some-branch' },

	-- set 'theme = true' for themes; the first theme is set on INIT
	{ 'samlwood/vis-gruvbox', theme = true, file = 'gruvbox' },
}

-- require and optionally install plugins on init
plug.init(plugins, true)

-- access plugins via alias
plug.plugins.cursors.maxsize = 2000

Each plugin table can have the following options:

• url - the git repo url (https://github.com/ or https:// can be omitted)
• file - relative path to the lua file, without .lua (optional, defaults to init)
• ref - checkout a specific commit, branch or tag (optional)
• alias - access plugins via plug.plugins.{alias} (optional)
• theme - set to true for themes; the theme is set on the INIT event (optional)

Install on init

Pass true as second argument to plug.init (as in the example above) to install missing plugins on init.

Install path

Plugins are installed (cloned) to the following path (in this order):

(VIS_PLUG_HOME|(XDG_CACHE_HOME|HOME/.cache)/vis-plug)/{plugins|themes}

Use plug.path to set a custom install path:

plug.path('/Users/user/my-plugins')

Themes

Install themes using the { theme = true, file = 'somepath/theme-file' } option (don't include .lua)

The first theme in the config table is set on the INIT event.

Example theme:

local plugins = {
	{ 'timoha/vis-acme', theme = true, file = 'acme' },
}

Commands

We support the following vis commands:

:plug-list - list plugins and themes

:plug-install - install plugins (git clone)

:plug-update - update outdated plugins (git pull)

:plug-outdated - check if plugins are up-to-date

:plug-upgrade - upgrade to latest vis-plug using git pull

:plug-remove {name} - delete a plugin (:plug-list for names)

:plug-clean - delete all plugins from disk

:plug-purge - list plugins and themes not in config (:plug-purge! to delete them)

:plug-checkout {name} {commit|branch|tag} - checkout a specific version of a plugin

:plug-commands - list commands (these)