Skip to main content

How It Works

skul separates desired state from materialized state.

Cache​

Remote bundle sources are cloned once into:

~/.skul/library/

Later add operations reuse that cache unless you clear it.

Registry​

skul stores repository-wide and worktree-specific state in:

~/.skul/registry.json

The registry records:

  • which bundles a repository wants
  • which source revision was used
  • which files were written into each worktree

Materialization​

When you apply a bundle, skul writes the corresponding files into the current repository clone and updates .git/info/exclude so those files stay untracked locally.

That means:

  • no .gitignore edits
  • no committed generated tool files
  • safe re-application in new worktrees

Tracked root-instruction shadows​

Root instruction targets are special when the repository already tracks them.

In that case, skul:

  • reads the file's HEAD content
  • renders bundle overlay content on top of that base
  • marks the file with skip-worktree
  • tracks enough state to suspend, refresh, retire, or restore the shadow later

This is why tracked-root workflows use:

skul sync

or, when run manually:

skul shadow --suspend
git pull --ff-only
skul shadow --refresh

Re-applying in a new worktree​

Because desired state is tracked separately, a fresh linked worktree can inherit the same bundle setup:

skul apply