Sigil

Sigil is a minimal symlink-based dotfile manager with per-package Lua config.

Install (dev)

go run . <command>

Commands

sigil apply — apply symlinks from ~/.dotfiles
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) and remove from repo
sigil remove <spec> — same as unlink, plus remove package/subpath

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

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.

`config.lua`

---@class SigilConfig
---@field target table<string, string|boolean>
---@field ignore? string[]

---@type SigilConfig
local config = {
  target = {
    linux = "~/.config/nvim",
    macos = "~/Library/Application Support/nvim",
    -- use false to skip applying on that platform
    windows = false,
    default = "~/.config/nvim",
  },
  ignore = {
    "**/.DS_Store",
    "**/*.tmp",
    "cache/**",
  },
}

return config

Spec formats

unlink/remove accept:

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

Notes

Uses SIGIL_REPO env var to override the repo path.
Conflicts are detected (existing non-symlink files will stop apply).
config.ignore supports gitignore-like globs (*, ?, **) relative to each package files/ directory.
Prefer sigil add over manual edits in files/.

2.1 KiB Raw Blame History