Git Reference ยท Objects, Refs and Internals
Refs and ref storage
Reference for how Git stores branches, tags and other refs: loose files under .git/refs, the packed-refs file, symbolic refs, and the reftable backend.
A ref is a name that points to an object ID. Branches (refs/heads/main), remote-tracking branches (refs/remotes/origin/main), tags (refs/tags/v1.0), the stash (refs/stash) and notes (refs/notes/commits) are all refs. Commands accept short names like main and resolve them by searching a fixed list of prefixes; the full name always works.
Git stores refs in a "ref backend". The default, files, keeps one small file per ref plus an optional packed-refs file. A newer backend, reftable, keeps all refs and their logs in binary tables. Both are hidden behind the same commands (git for-each-ref, git update-ref, git show-ref), so you rarely need to look at the files directly.
git for-each-ref # every ref with its object git update-ref refs/heads/x <id> # create or move a ref safely git pack-refs --all # move loose refs into packed-refs
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
How refs are stored
Loose refs
A loose ref is a file whose path is the ref name, for example .git/refs/heads/feature. The file contains the 40 (or 64) hexadecimal digits of an object ID and a newline. Slashes in the ref name become directories, so feature/login is the file login in the directory feature. This also means you cannot have both a branch feature and a branch feature/login.
Git updates a ref by writing <name>.lock, then renaming it over the original. That makes updates atomic and prevents two processes from changing the same ref at once. A stale .lock file after a crash blocks the ref until you remove it.
Symbolic refs
A symbolic ref contains ref: <other-ref> instead of an ID. HEAD is the main example (see HEAD and detached HEAD). git symbolic-ref reads and changes them. refs/remotes/origin/HEAD is another one.
packed-refs
A repository with thousands of tags would be slow with one file each, so git pack-refs (run by git gc) collects them in .git/packed-refs, a sorted text file:
# pack-refs with: peeled fully-peeled sorted <object-id> refs/heads/feature <object-id> refs/tags/v1 ^<peeled-commit-id>
A line starting with ^ follows an annotated tag and gives the commit it points to, so tags can be peeled without opening the tag object. Lookup rule: if a loose file exists it wins; otherwise Git reads packed-refs. Deleting a packed ref therefore rewrites the file as well.
reftable
Reftable (git init --ref-format=reftable, or git refs migrate --ref-format=reftable) stores refs and the reflog in binary, sorted, block-compressed tables under .git/reftable/, with a tables.list file naming the active tables. It supports atomic multi-ref updates, case-insensitive file systems without conflicts, and very large ref counts. The repository records the choice in extensions.refStorage, so older Git versions refuse to open it instead of misreading it.
Usage notes
- Never write ref files by hand. Use
git update-ref, which takes the lock, checks the old value if you ask it to and writes the reflog. - Name rules. Names cannot contain spaces,
~,^,:,?,*,[or\, cannot have..or@{, and cannot end in.lockor/.git check-ref-formatvalidates a name. - Short-name lookup order. Git tries
<name>,refs/<name>,refs/tags/<name>,refs/heads/<name>,refs/remotes/<name>andrefs/remotes/<name>/HEAD. A branch and a tag with the same name cause an "ambiguous" warning. - Reflogs are separate:
.git/logs/<refname>for the files backend. Packing refs does not touch them. - Linked worktrees share most refs but keep their own
HEADand per-worktree refs, such asrefs/bisect/*. - Hosting. On a bare server repository the same layout lives directly in the repository folder, without
.git.