Skip to main content

How it stays out of Git

Skul never touches .gitignore, your history, or your index for files it creates. Three pieces make that work.

The cache and the registry​

PathHolds
~/.skul/library/Cloned bundle sources, reused by every project
~/.skul/registry.jsonWhat each repo wants, and what was written in each worktree

Wanted and written are tracked separately. A new linked worktree inherits the wanted state immediately; skul apply writes it.

Exclude, not ignore​

Files Skul creates are listed in .git/info/exclude — local to your clone, never committed or pushed. Remove the bundle and the entries go with it.

Skul also fingerprints everything it writes. If you edit a managed file, removal asks first (or fails under SKUL_NO_TUI=1) instead of silently destroying your change.

Root instructions​

AGENTS.md, CLAUDE.md, and QWEN.md are the hard case: your team may already commit them.

If Git tracks the file

Your layer stays local, with three costs:

  • Pull with skul sync, and wrap other Git commands that move HEAD in skul shadow --suspend and --refresh.
  • Don't edit the file by hand while Skul manages it.
  • Only one bundle can own a tracked file's shadow at a time.

Not tracked​

Skul writes the file like any other and hides it. A file that already existed locally is kept as the base, with bundle content appended inside SKUL:BUNDLE markers. Several bundles can share one file; when the last one leaves, your original comes back.

Use --root-instruction-mode replace to discard the base instead of appending to it (it's still restored on remove).

Tracked: the shadow​

If Git already tracks the file, Skul can't hide a diff with an exclude rule. Instead it renders HEAD plus your overlay into the working file and sets skip-worktree. git status stays clean; skul status lists it under Shadowed Instructions.

A tracked file has one shadow owner at a time, and Skul treats the rendered file as generated output. Don't edit it by hand — later commands refuse to overwrite a file that no longer matches what Skul wrote.

Pulling upstream changes​

skip-worktree hides upstream changes too, so shadows need a pause around anything that moves HEAD:

skul sync

That's git pull --ff-only wrapped in suspend and refresh. If the pull fails, shadows are restored first. If upstream stops tracking the file, the shadow is retired.

For other Git commands, do the same by hand:

skul shadow --suspend
git rebase origin/main
skul shadow --refresh

Skul refuses to create or refresh a shadow while the file has staged, unstaged, or unmerged changes.

Cleaning up​

skul reset

Removes everything Skul manages in this worktree, restores shadowed files from HEAD, and restores preserved local bases. Run it before git worktree remove; otherwise the registry keeps a record of a clone that no longer exists.