Skip to Content

A stick figure smiling

If you want to see more comics like this, sign up for my saturday comics newsletter or browse more comics!

Image of a comic. To read the full HTML alt text, click "read the transcript".

browse more comics! get the zine!
read the transcript!

git often uses the term “reference” in error messages

$ git switch asdf
fatal: invalid reference: asdf

$ git push
 ! [rejected]    main -> main 
error: failed to push some refs to ''

“ref” and “reference” mean the same thing

Illustration of a tiny worried-looking stick person with a thought bubble reading “!”

“reference” often just means “branch”

in those two error messages, you can replace “reference” with “branch”

in my experience, it’s:
96% “branch”
3% “tag”
3% “HEAD”
0.01% something else

it’s an umbrella term

Illustration of git, represented by a box with a smiley face

git, thinking: “well, I COULD check if the thing we failed to push is a branch or tag or what, and customize the error message based on that….”
git, thinking: “seems complicated, let’s just print out “reference””

sad person: “why?”

reference: the definition

References are files: either .git/HEAD or files in .git/refs. There are 5 main types.

Here’s a list of every type of git reference that I have ever used:

  • HEAD: .git/HEAD
  • branches: .git/refs/heads/BRANCH
  • tags: .git/refs/tags/TAG
  • remote-tracking branches: .git/refs/remotes/REMOTE/BRANCH
  • stash: .git/refs/stash

all of these files contain a commit ID, but the way that commit ID is used depends on what type of reference it is

(examples of more obscure references are .git/FETCH_HEAD and .git/refs/notes/... but I’ve never needed to think about those and your repository probably doesn’t even have notes)

git’s garbage collection starts with references

the algorithm is: 1. find all references, and every commit in every reference’s reflog 2. find every commit in the history of any of those commits 3. delete every commit that wasn’t found

Saturday Morning Comics!

Want another comic like this in your email every Saturday? Sign up here!

I'll send you one of my favourite comics from my archives every Saturday.
© Julia Evans 2024 | All rights reserved (see the FAQ for notes about licensing)