Documentation
TOML Reference
Patch

Patch

The [[patch]] table defines a patch to be applied to a file. HermitGrab can parse TOML, YAML, and JSON (with comments) and apply the patch (which can also be in any of those formats). The type will be determined by the file extsion.

Comments and formatting in the original target document will be lost during this process.

Basic Usage

KeyTypeDefaultDescription
sourceString or TableRequiredPath to the patch file within the HermitGrab repository.
targetStringRequiredPath to the file to be patched on the target system. Supports Handlebars and XDG variables.
typeStringRequiredThe patch method. See below for possible values.
requiresArray of Strings[]A list of tags that must be active for this patch to be processed.
orderUnsinged int0The order in which to execute this action. Patch actions with the same order number will be potentially be executed in parallel.

The simplest way to specify a source is by providing a string, which is interpreted as a file path relative to your hermit.toml.

[[patch]]
# Patches target.json with the contents of test.json
source = "test.json"
target = "target.json"
patch_type = "JsonMerge" # or "JsonPatch"

Patch Types

ValueDescription
JsonMergeApply patch according to RFC 7396.
JsonPatchApply patch according to RFC 6902.

Advanced Usage (Source Table)

For more control, you can define source as a table with the following keys:

  • file (String): The path to the source file. This is mutually exclusive with text.
  • text (String): Inline content to be used as the source. This is useful for small, self-contained patches or for generating content dynamically. This is mutually exclusive with file.
  • pre_processing (String, Optional): Specifies a pre-processing step to be applied to the source content.
    • "Handlebars": Treats the source content as a Handlebars template and renders it before use. This allows for dynamic values in your patches.
  • rendered_file (String, Optional): When using text, hermitgrab writes the content to a temporary file. This key allows you to specify a persistent path for that file, making it easier to inspect the generated content. If not provided, a unique filename is generated in a temporary directory.
  • content_type (String, Optional): Defines how to parse the source and destination files. This is crucial for patch operations.
    • "Auto" (Default): Infers the content type from the source or destination file extension (.json, .yaml, .toml).
    • "Json"
    • "Yaml"
    • "Toml"

Examples

1. Explicit File Source

This is equivalent to the basic usage.

[[patch]]
source = { file = "test.json" }
target = "target2.json"
patch_type = "JsonMerge"

2. Inline Text Source

Use inline text for a simple, self-contained patch.

[[patch]]
source = { text = '{"version": "1.2.3"}' }
target = "package.json"
content_type = "Json"
patch_type = "JsonMerge"

3. Inline Text with Handlebars Pre-processing

Generate patch content dynamically. Here, we set num_cpus to half the system’s available CPUs.

# Requires access to system information (e.g., via a context you provide)
[[patch]]
source = { text = '{"num_cpus":{{math sys.cpu_num "/" 2}}}', pre_processing = "Handlebars" }
target = "config.json"
content_type = "Json"
patch_type = "JsonMerge"

4. Specifying content_type

Explicitly tell hermitgrab how to interpret files, which is useful for files with non-standard extensions.

[[patch]]
source = "my-config.txt"
target = "app.conf"
patch_type = "JsonMerge"
# Ensure both files are parsed as TOML, regardless of extension
content_type = "Toml"
LinkInstall