git refs

Switching from files to reftable, etc. Plumbing-adjacent.

🎯 What & why

git refs is the porcelain for the refs backend itself, not for individual references. It exists because Git is migrating from the ancient files backend to reftable, and someone has to drive that.

🧠 Mental model

Think of it as fsck/migrate for the ref storage layer. You don't use it daily; you use it once when you flip a repo from files to reftable, or when you want to audit the backend's integrity.

🛠️ Synopsis

git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]
git refs list
git refs verify [--strict] [--verbose]

🎚️ Switches & options

Flag	What it does
`--ref-format=<fmt>`	Target backend: `files` or `reftable`. The whole point of `migrate`.
`--no-reflog`	Skip reflog entries during migration. Faster, lossy — you lose history of ref movement.
`--dry-run`	Show what would happen without touching the repo. Always run this first.
`--strict`	On `verify`, treat warnings as errors. Use in CI.
`--ref-format=files`	⚠️ Migrating back to `files` from `reftable` is supported but rarely what you want; reftable is the future.
`-v / --verbose`	Print every ref touched. Useful for debugging a stuck migration.

📦 Subcommands

migrate — Convert the on-disk refs backend in place.

git refs migrate --ref-format=reftable --dry-run

list — Print which backend the repo currently uses.

git refs list

verify — Check refs backend consistency. Cheaper than full git fsck.

git refs verify --strict

💡 Use cases

Migrating a monorepo from files to reftable for ref-lookup performance.
Auditing a suspicious repo where git fsck complained about ref storage.
Standardizing a fleet of repos on one backend during a server upgrade.
CI hook that asserts every cloned repo uses the expected backend.

🧪 Examples

Check current backend

git refs list

Dry-run a reftable migration

git refs migrate --ref-format=reftable --dry-run

Actually migrate, keeping reflogs

git refs migrate --ref-format=reftable

Strict integrity check

git refs verify --strict --verbose

🎓 Recommendations

Always --dry-run first on anything bigger than a toy repo.
Back up .git/ before any non-dry migration. It's cheap, the migration isn't transactional in the way you'd hope.
Prefer reftable for repos with >10k refs — lookups go from O(n) directory scans to indexed reads.

🪤 Common pitfalls

Old Git versions (<2.45) cannot read reftable. Migrate the server, not just the client, or your tooling breaks.
--no-reflog discards the audit trail. Don't use it on a repo where you investigate force-pushes.
Some third-party tools (older libgit2, hooks that grep .git/refs/) assume the files layout and silently break post-migration.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.