Documentation
TOML Reference
XDG Support

XDG Support

HermitGrab provides comprehensive support for XDG Base Directory Specification and platform-specific directory standards. For detailed information about all available directory variables, see Handlebars Support.

Path Expansion and XDG Substitution

HermitGrab automatically replaces common directory patterns with their XDG environment variable equivalents when expanding paths. This ensures that configurations respect user-defined XDG paths.

Automatic XDG Path Substitution

When a target path contains these patterns, they are replaced with the corresponding XDG variable:

Pattern in PathReplaced WithExample
~/.config$XDG_CONFIG_HOME~/.config/fish/config.fish → $XDG_CONFIG_HOME/fish/config.fish
~/.local/share$XDG_DATA_HOME~/.local/share/applications → $XDG_DATA_HOME/applications
~/.local/state$XDG_STATE_HOME~/.local/state/nvim → $XDG_STATE_HOME/nvim
~/.cache$XDG_CACHE_HOME~/.cache/myapp → $XDG_CACHE_HOME/myapp
~/.local/bin$XDG_BIN_HOME~/.local/bin/script → $XDG_BIN_HOME/script

How It Works

  1. Environment Variable Check: HermitGrab first checks if the XDG environment variable is set
  2. Fallback to Default: If not set, uses the XDG default path
  3. Path Replacement: Replaces the pattern in your configuration with the actual path

Example

If you have this in your hermit.toml:

[[link]]
source = "config.fish"
target = "~/.config/fish/config.fish"

The behavior depends on environment variables:

Scenario$XDG_CONFIG_HOMEActual Target
Not set(unset)~/.config/fish/config.fish
Set to custom path/custom/config/custom/config/fish/config.fish
Using {{dir.xdg_config}}(any value)$XDG_CONFIG_HOME/fish/config.fish

Using Handlebars for Explicit Control

If you don’t want automatic path substitution, you can use Handlebars variables for explicit control. For example, use {{dir.home}} instead of ~ to prevent automatic substitution and access platform-specific directories. This requires Handlebars support enabled in the field.

DetectorsHandlebars Support