Docs: no documented backup/restore procedure; git bundle of refs/bugs works but cache invalidation is undocumented #1583

Problem

There is no documented way to back up and restore a git-bug store. Searching the repo and issues for "backup" / "restore" returns nothing on the topic. That matters because anyone evaluating a bridge has to mutate real data to learn anything — bridges push and pull against a live store, and there is currently no stated safe procedure for rolling that back.

git-bug bug --format json looks like the obvious candidate but is not a restore path: it is a lossy read-model snapshot, with no way to reconstruct the underlying operation DAG from it.

What actually works

git-bug's data lives entirely in refs/bugs/* and refs/identities/*, so a plain git bundle of those refs is a complete, verifiable, restorable backup:

# backup
git for-each-ref --format='%(refname)' | grep -E 'refs/(bugs|identities)' > refs.txt
git bundle create git-bug-refs.bundle $(cat refs.txt | tr '\n' ' ')
git bundle verify git-bug-refs.bundle          # -> "The bundle records a complete history"

# restore: resets modified bugs to the backed-up state
git fetch --force git-bug-refs.bundle 'refs/bugs/*:refs/bugs/*' 'refs/identities/*:refs/identities/*'

# drop bugs created after the backup (not present in the bundle, so unaffected by --force)
git update-ref -d refs/bugs/<full-hash>

# REQUIRED: the cache does not notice ref changes
rm .git/git-bug/cache/bugs

Verified on v0.10.1: after deliberately corrupting a 20-bug store via a bridge round trip (2 extra bugs imported, 3 comment threads duplicated), the above restored all 20 bugs to identical title / status / comment count / id.

The cache gotcha is the part that bites

Deleting a bug ref has no visible effect — git-bug bug keeps listing the deleted bug from .git/git-bug/cache/bugs until that file is removed. Anyone attempting a manual rollback will conclude the deletion silently failed. This is worth documenting regardless of whether the rest of this is adopted.

Suggestion

Add a short "Backup and restore" section to the docs covering the above, and note the cache invalidation requirement. Happy to open a PR if the approach looks right — mainly wanted to confirm there isn't an intended mechanism I missed before writing docs for a workaround.