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

The link action can be configured to handle cases where the target file already exists:

  • Abort - Abort the apply command (default).
  • Backup - Move the existing file to a .bak file. If .bak already exists, create .bak.1, etc.
  • BackupOverwrite - Move the existing file to a .bak file, overwriting .bak if it already exists.
  • Delete - Delete any existing file, but not directories.
  • DeleteDir - Delete any existing file or directory. Use with caution.
  • Ignore - Do nothing if the file already exists.

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.

Handlebars Support

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

  • dir
    • this - The directory of the current hermit.toml file
    • hermit - The location of the .hermitgrab directory
    • home - The home of the user
    • xdg_config - The directory of XDG_CONFIG_HOME or its default
    • xdg_data - The directory of XDG_DATA_HOME or its default
    • xdg_state - The directory of XDG_STATE_HOME or its default
  • var - In an install action the variables as specified in the hermit.toml
    • name - The name of the install action
  • tag - The values of the detected tags as specified in tags
    • arch for example might be aarch64

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}}"

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.

Tags