Sigil usage (for agents)

This repo is managed by Sigil, a minimal symlink-based dotfile tool.

Repo layout

~/.dotfiles/
  <package>/
    config.lua
    files/              # common files (all OSes)
    files.linux/        # Linux-specific overrides
    files.macos/        # macOS-specific overrides
    files.windows/      # Windows-specific overrides

Each package has a config.lua that defines its target path per OS.

Per-OS file variants

Create files.<os>/ directories alongside files/ for OS-specific overlays:

pi-agent/
  files/
    settings.json       # shared config
  files.linux/
    agent.json          # Linux-specific
  files.macos/
    agent.json          # macOS-specific

On Linux, agent.json links to files.linux/agent.json. On macOS, it links to files.macos/agent.json. Files in files/ are applied first, then OS-specific variants overlay on top.

Common commands

sigil apply — apply symlinks (prompts for stale links)
sigil apply --prune — prune stale links without prompting
sigil add <path> — add a file/dir to the repo and symlink it
sigil status — show stale links
sigil unlink <spec> — restore file(s) to target and remove from repo
sigil remove <spec> — same as unlink, plus remove package/subpath from repo

Spec formats

unlink/remove accept these:

package (entire package)
package:relative/path
repo path: ~/.dotfiles/<pkg>/files/...
target path: e.g. ~/.config/<app>/...

Examples:

sigil unlink wezterm
sigil unlink wezterm:lua
sigil unlink ~/.dotfiles/wezterm/files/wezterm.lua
sigil unlink ~/.config/wezterm/wezterm.lua

Notes

If a repo file is missing, stale links should be pruned.
Prefer sigil add over manual moves into files/.

Development

When modifying this repo, rebuild and install the binary: go build -o ~/.local/bin/sigil .
Bump the version constant in main.go for every change (follow semver: bugfix = patch, feature = minor, breaking = major)

IMPORTANT: Update AGENTS.md files when Sigil changes

Whenever Sigil is modified (new features, behavior changes, new commands), you MUST update the AGENTS.md documentation in BOTH locations:

This repo: /home/thomasgl/programming/sigil/AGENTS.md
Dotfiles repo: /home/thomasgl/.dotfiles/AGENTS.md

Keep them in sync so agents have correct instructions regardless of which directory they're working in.

2.4 KiB Raw Blame History