Documentation
Basic Concepts
Actions

Actions

HermitGrab provides three types of actions:

  • link
  • patch
  • install

Link

The link action is a core feature, used for linking files from your dotfiles repository to their target locations, typically within your home directory. There are three supported linking types:

  • soft - create a symbolic link (default)
  • hard - create a hard link
  • copy - copy the file/folder

See link for more details.

XDG Support

The target for a link will substitute certain folder segments with their corresponding XDG environment variables if they are set:

  • ~/.config -> $XDG_CONFIG_HOME
  • ~/.local/share -> $XDG_DATA_HOME
  • ~/.local/state -> XDG_STATE_HOME

If you don’t want this substitution, you can use {{ dir.home }} instead of ~.

Install

The install action can execute code to change the configuration of the target machine, i.e., install programs or run commands that alter the configuration.

The install action has a name field for identification, which can also be referenced from within the command itself. It also has three main configuration fields:

  • check (optional) - Execute a command to see if the install is actually required
  • install - The actual installation/configuration command.
  • variables - key value pairs that can be referenced via handlebars.

See install for more details.

Handlebars Support

The check, install, and variables fields all support Handlebars syntax. With Handlebars, you can access contextual information:

The helper function snippet allows you to reference the contents of a defined snippet.

Here is a simple “hello world” example:

[snippet]
greet="world!"

[[install]]
name="HelloWorld"
install="echo Hello {{snippet greet}}"

See handlebars for more details.

UBI Support

The universal binary installer (ubi) is integrated directly into HermitGrab. This allows for seamless installation of tools without relying on external utilities like curl, wget, or decompression tools. You can invoke it from any script or command by calling ubi.

Patch

This action applies a patch from a source file to a target file. There are two supported methods:

HermitGrab can parse TOML, YAML, and JSON (with comments) and apply the patch (which can also be in any of those formats). Note that comments and formatting in the original target document will be lost during this process.

See patch for more details.

Tags