Plugins

Importing plugins and authoring your own: commands, decorators, shorthands, and command extensions.

Import a plugin

Add a plugin to an experiment with knit_import, pinned to a ref.

APIs: knit_import

knit_import fetches a plugin from a git host, pins the exact commit, verifies its checksum, and sources it, so the plugin’s commands and decorators become available. Call it at the top of the experiment, after source knit.sh and before using what the plugin provides:

# Short form: expands to github.com/knit-sh/knit-<name>.
knit_import spack

# Pin a ref (tag, branch, or commit). A mutable ref is resolved to a commit on
# the first bootstrap and frozen in knit-plugins.lock.
knit_import spack@v1.2.0

# Full form names the host, owner, and repository.
knit_import github.com/your-org/knit-example@v1.0.0

# Optionally hard-pin the tarball checksum.
knit_import spack@v1.2.0 \
    --sha256 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

The short form expands to github.com/knit-sh/knit-<name>. A mutable ref such as a branch resolves to a commit on the first bootstrap and is frozen in knit-plugins.lock, so a later run and a fresh checkout use the same code. Bootstrap also records each plugin in the plugins table and materializes its pinned tree under .knit/plugins/ for a self-contained experiment directory.

The worked example throughout this guide is the Spack environment manager, imported with knit_import spack: it adds the knit_with_spack_* setup directives, the spack command, and the --spack bootstrap options. See the Spack category for what it provides.

Author a decorator

Build a decorator from the public registration surface.

APIs: knit_run_before, knit_add_command_note, knit_command_set_marker, knit_command_has_marker, knit_current_command

A decorator is a function that changes the command currently being registered, the way the built-in knit_with_* decorators do. It is built from the public registration surface: knit_run_before installs a callback that runs before the command body, knit_add_command_note adds a line to the command’s --help requirements, and the per-command markers (knit_command_set_marker / knit_command_has_marker) let the decorator reject a second use of itself:

# A decorator is a function that changes the command currently being registered,
# using the same public surface the built-in knit_with_* decorators use:
# knit_run_before installs a callback, knit_add_command_note adds a help note,
# and the per-command markers reject a second use of the decorator.
demo_print_banner() {
    printf '=== %s ===\n' "$1"
}

demo_with_banner() {
    if knit_command_has_marker banner; then
        knit_fatal "@with_banner is used more than once on \"$(knit_current_command)\"."
    fi
    knit_command_set_marker banner
    knit_add_command_note "Prints a \"$1\" banner before it runs."
    knit_run_before demo_print_banner "$1"
}

Apply it in the registration block between knit_register and knit_done, like any knit_with_* call.

Register a shorthand

Expose a decorator as an @-shorthand for the user’s experiment.

APIs: knit_register_shorthand

knit_register_shorthand defines an @-shorthand that forwards to a function, so a plugin can offer its decorator in the same @ form as the built-in decorators. The shorthand generator runs before a plugin loads, so a plugin registers its own shorthand on demand:

# Expose the decorator as "@with_banner" for the user's own experiment. The
# shorthand generator runs before a plugin loads, so a plugin registers its
# shorthand on demand. Reserve the shorthand for the user: call the decorator by
# its canonical name inside plugin.sh (a user may disable shorthands).
knit_register_shorthand with_banner demo_with_banner

The shorthand is a convenience for the user’s experiment. Inside your own plugin.sh, call the decorator by its canonical name (demo_with_banner), not @with_banner: a user can disable shorthands with KNIT_WITHOUT_SHORTHAND, which would leave the shorthand undefined and break your plugin as it loads. knit_register_shorthand honors that opt-out and rejects a token that a built-in or another plugin already defines.

Extend a command

Reopen a registered command to add options or hooks with knit_extend.

APIs: knit_extend, knit_ensure_subcommand_exists

knit_extend reopens the registration of a command that is already closed, so the ordinary decorators apply to it again. It works on any registered entity — a command, setup, job, app, or enum — including a core Knit command. A plugin uses it to add an option to, or hook the body of, a command it did not define:

# knit_extend reopens a command that is already registered so the decorators
# apply again. It works on any command, including a core Knit command.
# knit_ensure_subcommand_exists runs the lazy discovery so the target exists.
knit_ensure_subcommand_exists metadata store
knit_extend "metadata:store"
knit_with_optional "note:string" "" "A note added by the plugin."
knit_done

knit_ensure_subcommand_exists first runs the lazy discovery so the target is registered before knit_extend reopens it. Between knit_extend and knit_done the decorators append to the command’s existing options, callbacks, and table columns; the re-run of its done callbacks is idempotent.