The Git reftable format is a binary, transactional storage backend for Git references (branches, tags) and reflogs, designed to replace traditional loose files and packed-refs.
In standard Git repositories, references are stored as loose files under .git/refs/ and periodically combined into .git/packed-refs. While simple, this architecture degrades on repositories containing tens or hundreds of thousands of refs, leading to file system directory thrashing, lock contention during concurrent reference updates, and linear scan overhead.
Introduced in Git 2.45, the reftable format stores references in compact, indexed binary files inside .git/reftable/. When enabled, Git declares the extension in .git/config:
[extensions]
refstorage = reftable
[core]
repositoryformatversion = 1
Per the Git repository specification, any Git client or library encountering an unrecognized extension under [extensions] must abort immediately to avoid corrupting reference metadata.
While the native upstream git CLI (version 2.45+) fully supports reftables, secondary Git implementations and embedded libraries may not yet implement the specification.
Nix uses libgit2 to read and evaluate local Git repository inputs (such as git+file://... or use flake in .envrc via direnv). Because libgit2 does not yet support extensions.refstorage, invoking Nix commands or direnv allow in a reftable repository aborts with:
error: opening Git repository "...": unsupported extension name extensions.refstorage (libgit2 error code = 6)
Toolchains that read .git/HEAD directly or rely on libgit2 bindings (such as IDE Git status indicators or AI coding agent harnesses) may fail to resolve the current branch or report corrupted repository metadata when reftable is active.
Existing repositories can be safely migrated back to the standard loose-files format without modifying commit history, branch pointers, or the working tree:
git refs migrate --ref-format=files
This command converts .git/reftable/ records into standard .git/refs/ and .git/packed-refs, and removes the extensions.refstorage entry from .git/config.
After completing the migration back to files, Nix and direnv will evaluate flakes normally:
direnv allow
If a newer Git build or system-wide configuration defaults to reftable for newly initialized or cloned repositories, configure Git to default to the files backend:
git config --global init.defaultRefFormat files