empty-repo-bundle-preflight

SKILL: Empty Repo Bundle Preflight

Domain: safety-worktrees
Trigger: Apply before running git bundle create to ensure the repository actually has refs, avoiding the 128 exit code and providing a clearer error path. Source Pattern: Distilled from reviewed repo-safety, packaging, and worktree-management patterns.

Core Method

Run git for-each-ref --count=1 refs/ from the repository root; if the output is empty, report that the repo has no commits, record an analytics metric with the empty_repo outcome, and abort with a helpful message instead of invoking git bundle create, which would exit 128 on an empty repo. Sweep stale temporary refs first so the check reflects the true repo state, and treat the empty case as a known failure reason with a dedicated fail reason identifier that consumers can react to.

Key Rules

• Always clean up refs/seed/stash and refs/seed/root before testing for refs so old placeholders cannot make an empty repo appear populated.
• Capture the empty_repo outcome via analytics or logs so you can audit why bundling never ran.
• Return a structured error with a fail reason (empty_repo) so callers can distinguish it from git failures or oversized bundles.
• When the repo has refs, proceed to bundle creation without repeating the check unnecessarily.

Example Application

When building a git bundle upload helper, call this skill before _bundleWithFallback; if it signals an empty repo, stop and surface “Repository has no commits yet” to the UI and telemetry instead of letting git bundle create crash.

Anti-Patterns (What NOT to do)

• Do not rely on the git bundle exit code alone to detect emptiness; it produces a cryptic message and leaves temporary files behind.
• Do not skip the cleanup step—stale refs from prior runs can mask an empty repo and let you bundle garbage.
• Do not proceed to bundle creation when the guard reports no refs; the upload would stall and return a generic failure reason.