Git & cache

Shelling out, on purpose

star drives your system git rather than linking libgit2:

your SSH config, credential helpers, proxies, and url.insteadOf rewrites all just work — critical for private forges behind auth,
no C dependency: the nix build stays pure and the binary has no native-library portability concerns,
cost: git must be in PATH — detected up front with an actionable error if not.

Operation → command

Operation	Command
pin from remote	`git ls-remote <remote> HEAD`
clone	`git clone --no-checkout <remote> <path>`
refresh	`git -C <path> fetch --prune --tags origin`
verify pin	`git -C <path> rev-parse --verify <commit>^{commit}`
read tree	`git -C <path> archive --format=tar <commit> -- <prefix>`

git archive, not checkout, is how files are read: it needs no worktree, cannot race a dirty checkout, and produces exactly the pinned tree. Extraction happens in-process from the tar stream, with traversal checks (see security).

If a pin no longer resolves after a normal fetch — history was rewritten away — star retries with a direct SHA fetch (git fetch origin <sha>, allowed by most forges) before erroring with a star repo update hint.

Cache layout

Clones live under your platform cache directory, one directory per namespace, percent-escaped so every namespace is exactly one path component:

~/.cache/star/repos/          # Linux
  jingus%2Fstarters/
  star%2Fstarters/

No worktree is ever checked out — the clone exists to serve git archive at the pin.