104 lines
2.4 KiB
Markdown
104 lines
2.4 KiB
Markdown
# Sigil
|
|
|
|
Sigil is a minimal symlink-based dotfile manager with per-package Lua config.
|
|
|
|
## Install
|
|
|
|
### Build and install to ~/.local/bin
|
|
```bash
|
|
cd ~/programming/sigil
|
|
go build -o ~/.local/bin/sigil .
|
|
```
|
|
|
|
### Install via go install
|
|
```bash
|
|
cd ~/programming/sigil
|
|
go install .
|
|
# Binary will be at $(go env GOPATH)/bin/sigil
|
|
# Make sure $(go env GOPATH)/bin is in your PATH
|
|
```
|
|
|
|
### Run without installing (dev)
|
|
```bash
|
|
cd ~/programming/sigil
|
|
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`
|
|
|
|
```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/`.
|