References and the Commit Graph

Refs are names for commits

Commit IDs are unwieldy, so git lets you store one under a name. These names are references, or refs, and in the usual layout each is a small file under .git/refs holding one ID ¹:

me@linuxbox:~/garden$ cat .git/refs/heads/main
04fa6fb7dda18fbd9d43b95f1aaa6ed4ed5a8d99
me@linuxbox:~/garden$ git rev-parse main
04fa6fb7dda18fbd9d43b95f1aaa6ed4ed5a8d99

That’s all a branch is, as module 3 said: a file with a commit ID in it ¹. Making a branch writes one more file; committing rewrites the file for your current branch. There are three kinds of refs, by folder:

• refs/heads/: your branches.
• refs/tags/: tags.
• refs/remotes/: remote-tracking branches like origin/main (module 4). They’re read-only: git moves them when you fetch or push, never when you commit ¹.

git rev-parse turns any name, branch, tag, or HEAD~2, into the full ID.

Pro Git warns against editing ref files directly; the plumbing command git update-ref does it safely, and records the move in the reflog ¹.

HEAD

HEAD is one more ref, in .git/HEAD. Usually it’s a symbolic reference: instead of an ID, it holds the name of another ref ¹:

me@linuxbox:~/garden$ cat .git/HEAD
ref: refs/heads/main
me@linuxbox:~/garden$ git symbolic-ref HEAD
refs/heads/main
me@linuxbox:~/garden$ git switch -c fence
Switched to a new branch 'fence'
me@linuxbox:~/garden$ cat .git/HEAD
ref: refs/heads/fence

That’s how git knows which branch to move when you commit: it makes the new commit with HEAD’s commit as the parent, then updates whatever branch HEAD names ¹. Switching branches just rewrites this one line (and your files).

In detached HEAD (module 3), .git/HEAD holds a commit ID instead of a branch name ¹:

me@linuxbox:~/garden$ git switch --detach HEAD~1
HEAD is now at cc36fee Add beans
me@linuxbox:~/garden$ cat .git/HEAD
cc36feeb19d92e3a7d49b1db9bffe3c78a4a8959

Commits made now have no branch to move, which is why they’re easy to lose.

Tags

A tag names a commit that never moves, such as a release or “the version that worked.” There are two kinds ¹:

A lightweight tag is just a ref in refs/tags with a commit ID in it, a branch that doesn’t move:

me@linuxbox:~/garden$ git tag v0.1 HEAD~1
me@linuxbox:~/garden$ cat .git/refs/tags/v0.1
cc36feeb19d92e3a7d49b1db9bffe3c78a4a8959

An annotated tag, made with -a and a message, is a full object, a fourth type alongside blobs, trees, and commits. The ref points to the tag object, which points to the commit and records who tagged it, when, and why ¹:

me@linuxbox:~/garden$ git tag -a v1.0 -m "Spring planting plan"
me@linuxbox:~/garden$ cat .git/refs/tags/v1.0
c1a9ca46a1c3581e92a2adcfd39ffe27cd0b4944
me@linuxbox:~/garden$ git cat-file -t v1.0
tag
me@linuxbox:~/garden$ git cat-file -p v1.0
object 04fa6fb7dda18fbd9d43b95f1aaa6ed4ed5a8d99
type commit
tag v1.0
tagger Me <me@example.com> 1791216240 -0500

Spring planting plan

Pro Git recommends annotated tags for anything you’ll share ¹; lightweight ones suit private, temporary labels. git tag lists tags, and you can use a tag anywhere you’d use a commit ID: git switch --detach v1.0, git diff v1.0 main. git show-ref lists every ref with its ID:

me@linuxbox:~/garden$ git show-ref
04fa6fb7dda18fbd9d43b95f1aaa6ed4ed5a8d99 refs/heads/fence
04fa6fb7dda18fbd9d43b95f1aaa6ed4ed5a8d99 refs/heads/main
cc36feeb19d92e3a7d49b1db9bffe3c78a4a8959 refs/tags/v0.1
c1a9ca46a1c3581e92a2adcfd39ffe27cd0b4944 refs/tags/v1.0

Two things to know about tags in practice:

• git push doesn’t send tags. Push one with git push origin v1.0, or all of them with git push origin --tags ¹.

• git describe names the current commit relative to the newest annotated tag before it ²:

  me@linuxbox:~/garden$ git describe
  v1.0-2-g9cc8b1b
  

  That reads: two commits after v1.0, at commit 9cc8b1b (the g stands for git) ². Scripts use it to stamp a version on a build.

Packed refs

One file per ref gets slow with thousands of tags, so git gc (or git pack-refs) moves them into a single file, .git/packed-refs ¹:

me@linuxbox:~/garden$ git pack-refs --all
me@linuxbox:~/garden$ ls .git/refs/heads .git/refs/tags
.git/refs/heads:

.git/refs/tags:
me@linuxbox:~/garden$ cat .git/packed-refs
# pack-refs with: peeled fully-peeled sorted 
e96af3cfd72c5017c6495d7f45f4a3066cbd3a12 refs/heads/fence
05c397d6f8cad48fa356c67233c2c244d0c6e918 refs/heads/main
cc36feeb19d92e3a7d49b1db9bffe3c78a4a8959 refs/tags/v0.1
c1a9ca46a1c3581e92a2adcfd39ffe27cd0b4944 refs/tags/v1.0
^04fa6fb7dda18fbd9d43b95f1aaa6ed4ed5a8d99

The ^ line under v1.0 is the commit that annotated tag points to ¹. When a ref changes later, git writes a fresh file under refs/ again, and it checks there first, then in packed-refs ¹. That’s another reason to use git commands rather than reading .git/refs yourself: a branch can exist without a file there.

Git 3.0 plans a bigger change: a storage format called reftable, which doesn’t keep each ref as its own file, becomes the default for new repositories ³. The commands don’t change; only what’s in .git does.

The commit graph

Each commit names its parents, so commits link into a graph, running from each commit back to the first. A normal commit has one parent; a merge commit has two (or more) ¹:

me@linuxbox:~/garden$ git log --oneline --graph
*   05c397d Merge branch 'fence'
|\  
| * e96af3c Plan the fence
* | 9cc8b1b Add tomatoes
* | c93309a Add squash
|/  
* 04fa6fb Add garlic
* cc36fee Add beans
* fc026ad Plan the beds
me@linuxbox:~/garden$ git cat-file -p HEAD
tree ac1941be7fbfb846b2f5220b16ee809da8d36d82
parent 9cc8b1b2e72adde0d0145a0b9e403d3fec3ca7ad
parent e96af3cfd72c5017c6495d7f45f4a3066cbd3a12
author Me <me@example.com> 1791216480 -0500
committer Me <me@example.com> 1791216480 -0500

Merge branch 'fence'

The first parent is the branch you were on (main), the second the branch you merged in (fence) ¹. Arrows only point backward: a commit knows its parents, never its children. That’s why git log starts from a ref and walks back.

Walking the graph

Two suffixes walk it ⁴:

• ^n means the nth parent. HEAD^ (same as HEAD^1) is the first parent; HEAD^2 is a merge’s second parent.
• ~n means go back n generations, following first parents. HEAD~2 is the same as HEAD^^.

me@linuxbox:~/garden$ git log --oneline -1 HEAD^1
9cc8b1b Add tomatoes
me@linuxbox:~/garden$ git log --oneline -1 HEAD^2
e96af3c Plan the fence
me@linuxbox:~/garden$ git log --oneline -1 HEAD~2
c93309a Add squash

HEAD^ and HEAD~ both mean the first parent. The numbers differ: ^2 picks a second parent, which only merges have, while ~2 goes back two generations. Don’t confuse either with HEAD@{2} (module 5), which is where HEAD was two moves ago, from the reflog.

git merge-base finds where two branches split, their newest common ancestor. It’s the base a three-way merge compares against (module 3):

me@linuxbox:~/garden$ git merge-base main~1 fence
04fa6fb7dda18fbd9d43b95f1aaa6ed4ed5a8d99

The double-dot range from module 5, main..fence, is defined by the graph too: commits reachable from fence but not from main ¹.

What git keeps

A commit is reachable if you can get to it by starting at some ref and following parents. git log shows what’s reachable from HEAD; git log --all from every ref. Reachability is also what git uses to decide what to keep.

Delete a branch whose commits aren’t anywhere else, and they become unreachable. git branch -D prints the ID on its way out, which is the quickest way back:

me@linuxbox:~/garden$ git branch -D idea
Deleted branch idea (was 29df69d).

git branch idea 29df69d would restore it. If you’ve lost that line, the reflog (module 5) still has the commit, and git fsck, which checks the repository’s integrity, can list commits that nothing points to ¹. Its --no-reflogs option doesn’t count reflog entries as a reason to keep a commit, so it finds commits that used to be on a branch ⁵:

me@linuxbox:~/garden$ git fsck --no-reflogs
dangling commit 29df69daf037e8a2a5ad25bdeec66990b0de8270

A dangling commit is one that’s in the database but that nothing uses ⁵. It isn’t deleted right away. Only git gc removes objects, and it tries hard not to remove anything still referenced by a branch, tag, remote-tracking branch, the index, or a reflog entry; unreferenced objects also get a grace period, two weeks by default ⁶. Reflog entries for unreachable commits last 30 days (module 5). Together, that gives you weeks to notice a mistake.

The flip side: anything reachable is kept forever. A large file or a password committed once stays in every clone’s history even after you delete it in a later commit ¹. That’s why module 2 said to change a leaked secret rather than just delete the file.

Your turn

So

A ref is a name holding a commit ID: branches in refs/heads, tags in refs/tags, remote-tracking branches in refs/remotes, sometimes packed into .git/packed-refs. HEAD usually names a branch (ref: refs/heads/main) and holds a bare ID when detached. Lightweight tags are plain refs; annotated tags are objects with a tagger and message, pushed explicitly with git push origin <tag>. Parents link commits into a graph: ^n picks a parent, ~n walks back first parents, and git merge-base finds where branches split. Git keeps everything reachable from a ref or the reflog; dangling commits linger for weeks before git gc removes them.