Link – HermitGrab

Link

The link action in hermit.toml creates a link (symlink, hardlink, or copy) from a source to a target. The source parameter is highly flexible, allowing you to define the source content on the fly.

Basic Usage

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

[[link]]
# Creates a symlink from "dotfiles/.bashrc" to "~/.bashrc"
source = "dotfiles/.bashrc"
target = "~/.bashrc"

The [[link]] table defines a file or directory to be linked.

Key	Type	Default	Description
`source`	String or Table	Required	Path to the source file or directory relative to the `hermit.toml`.
`target`	String	Required	Path to the destination on the target system. Supports Handlebars and XDG variables.
`link`	String	`soft`	The type of link to create. Possible values are `soft`, `hard`, `copy`.
`requires`	Array of Strings	`[]`	A list of tags that must be active for this link to be processed.
`fallback`	String	`abort`	What to do if the target already exists. See below for possible values.
`order`	Unsinged int	`0`	The order in which to execute this action. Link actions with the same order number will be potentially be executed in parallel.

Fallback Operations

The fallback key determines the behavior when a file or directory already exists at the target location.

Value	Description
`abort`	(Default) Abort the apply command.
`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 or directory already exists.

Advanced Usage (Source Table)

For more complex scenarios, especially when generating file content dynamically, 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. When you use text, hermitgrab automatically writes this content to a file, which then serves as the source for the link operation. This is mutually exclusive with file.
pre_processing (String, Optional): Specifies a pre-processing step to be applied to the text content before it’s written to the source file.
- "Handlebars": Treats the text content as a Handlebars template and renders it. This is perfect for creating configuration files with dynamic values.
rendered_file (String, Optional): When using text, this key allows you to specify a persistent path for the generated source file. This is useful for inspecting the output or if you need a predictable file path. If not provided, a unique filename is generated in a temporary directory.

Note: The content_type key is not applicable to link actions as they operate on the file level and do not parse the content.

Examples

1. Explicit File Source

This is equivalent to the basic usage.

[[link]]
source = { file = "dotfiles/.gitconfig" }
target = "~/.gitconfig"

2. Inline Text Source

Directly embed the content of the source file in your hermit.toml. hermitgrab will save this to a file and link it.

[[link]]
source = { text = "export EDITOR=vim" }
target = "~/.bash_aliases"

3. Inline Text with Handlebars Pre-processing

Generate a source file from a template. In this example, we create a .wslconfig file and dynamically set the number of processors.

# This requires a context that provides `sys.cpu_num`
[[link]]
source = { text = """
[wsl2]
processors = {{math sys.cpu_num "/" 2}}
""", pre_processing = "Handlebars" }
target = "~/.wslconfig"

4. Using rendered_file for versioning

By providing a rendered_file path, you can set the name of the pre-processed file to have the rendered content in your dot-file repository.

[[link]]
source = { text = """
[wsl2]
processors = {{math sys.cpu_num "/" 2}}
""", pre_processing = "Handlebars", rendered_file = ".wslconfig.rendered" }
target = "~/.wslconfig"

After running hermitgrab, the file .wslconfig.rendered will exist in your project directory with the rendered content, and ~/.wslconfig will be a symlink to it.

[[link]]
source = "fish/config.fish"
target = "~/.config/fish/config.fish"
fallback = "backupoverwrite"
requires = ["fish", "+os_family=unix"]

Folder structure Patch