plug.kak

plug.kak is a plugin manager for Kakoune, that was inspired by vim-plug and use-package. It can install and update plugins, run post-update actions, and helps to encapsulate the configuration within itself.

Installation

plug.kak can be installed anywhere in your system, but in order to update itself, it is required to install plug.kak in the plugin installation directory. By default, plug.kak installs plugins to the %val{config}/plugins, which is usually at $HOME/.config/kak/plugins:

mkdir -p $HOME/.config/kak/plugins
git clone https://github.com/andreyorst/plug.kak.git $HOME/.config/kak/plugins/plug.kak

Now, when plug.kak is installed, we need to tell Kakoune about it. Add this to the kakrc file:

source "%val{config}/plugins/plug.kak/rc/plug.kak"
plug "andreyorst/plug.kak" noload

Alternatively, this process can be automated, by adding the following snippet to the kakrc:

evaluate-commands %sh{
    plugins="$kak_config/plugins"
    mkdir -p "$plugins"
    [ ! -e "$plugins/plug.kak" ] && \
        git clone -q https://github.com/andreyorst/plug.kak.git "$plugins/plug.kak"
    printf "%s\n" "source '$plugins/plug.kak/rc/plug.kak'"
}
plug "andreyorst/plug.kak" noload

This will create all needed directories on Kakoune launch, and download plug.kak if it is not installed already.

Note: plug "andreyorst/plug.kak" noload is needed to register plug.kak as manually loaded plugin, so plug-clean will not delete plug.kak.

Usage

All plugins are installed and loaded with the plug command. This command accepts one-or-more arguments, which are keywords and attributes, that change how plug.kak behaves.

The first strict rule of the plug command is that the first argument is always the plugin name formatted as in GitHub URL: "author/repository".

plug "author/repository"

By default plug.kak will look for the plugin at github.com, and download it. When the plugin is hosted on a different service, a URL can be used as the first argument. So in most cases it is enough to add this to the kakrc to use a plugin:

plug "delapouite/kakoune-text-objects"

Or with URL:

plug "https://gitlab.com/Screwtapello/kakoune-inc-dec"

After adding this, kakrc needs to be re-sourced to let plug.kak know that configuration was changed. Alternatively, Kakoune can be restarted. After that newly added plugins can be installed with the plug-install command. More information about other commands available in Commands section.

Keywords and attributes

The plug command accepts optional attributes, that change how plug.kak works, or add additional steps for plug to perform.

These keywords are supported:

• branch, tag, commit
• load-path
• noload
• do
• theme
• config
• defer
• demand
• ensure

Branch, Tag or Commit

plug can checkout a plugin to desired branch, commit or tag before loading it. It can be done by adding the following keywords with parameters: branch "branch_name", tag "tag_name" or commit "commit_hash".

Loading plugin from different path

Plugins can be loaded from arbitrary path by specifying the load-path keyword and providing the path as an argument:

plug "plugin_name" load-path "~/Development/plugin_dir"

However all plug related commands, like plug-update or plug-clean will not work for plugins that aren't installed to plug_install_dir.

Skipping loading of a plugin

If plugin needs to be loaded manually, the noload keyword can be used. This can also be used to avoid loading the plugin second time, like in the example with plug.kak from the installation section:

source "%val{config}/plugins/plug.kak/rc/plug.kak"
plug "andreyorst/plug.kak" noload

Note, that plugins with the noload keyword are still configured and managed. See handling-user-configuration for more details.

Automatically do certain tasks on install or update

When the plugin requires some additional steps to preform after installation or update, the do keyword can be used. This keyword expects the body which will be executed in the shell, thus it can only contain shell commands, not Kakoune commands.