While writing about Git, I’ve noticed that a lot of folks struggle with Git’s error messages. I’ve had many years to get used to these error messages so it took me a really long time to understand why folks were confused, but having thought about it much more, I’ve realized that:

1. sometimes I actually am confused by the error messages, I’m just used to being confused
2. I have a bunch of strategies for getting more information when the error message git gives me isn’t very informative

So in this post, I’m going to go through a bunch of Git’s error messages, list a few things that I think are confusing about them for each one, and talk about what I do when I’m confused by the message.

improving error messages isn’t easy

Before we start, I want to say that trying to think about why these error messages are confusing has given me a lot of respect for how difficult maintaining Git is. I’ve been thinking about Git for months, and for some of these messages I really have no idea how to improve them.

Some things that seem hard to me about improving error messages:

• if you come up with an idea for a new message, it’s hard to tell if it’s actually better!
• work like improving error messages often isn’t funded
• the error messages have to be translated (git’s error messages are translated into 19 languages!)

That said, if you find these messages confusing, hopefully some of these notes will help clarify them a bit.

error: git push on a diverged branch

$ git push
To github.com:jvns/int-exposed
! [rejected]        main -> main (non-fast-forward)
error: failed to push some refs to 'github.com:jvns/int-exposed'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

$ git status
On branch main
Your branch and 'origin/main' have diverged,
and have 2 and 1 different commits each, respectively.

Some things I find confusing about this:

1. You get the exact same error message whether the branch is just behind or the branch has diverged. There’s no way to tell which it is from this message: you need to run git status or git pull to find out.
2. It says failed to push some refs, but it’s not totally clear which references it failed to push. I believe everything that failed to push is listed with ! [rejected] on the previous line– in this case just the main branch.

What I like to do if I’m confused:

• I’ll run git status to figure out what the state of my current branch is.
• I think I almost never try to push more than one branch at a time, so I usually totally ignore git’s notes about which specific branch failed to push – I just assume that it’s my current branch

error: git pull on a diverged branch

$ git pull
hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint:
hint:   git config pull.rebase false  # merge
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
hint:
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --no-rebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.
fatal: Need to specify how to reconcile divergent branches.

The main thing I think is confusing here is that git is presenting you with a kind of overwhelming number of options: it’s saying that you can either:

1. configure pull.rebase false, pull.rebase true, or pull.ff only locally
2. or configure them globally
3. or run git pull --rebase or git pull --no-rebase

It’s very hard to imagine how a beginner to git could easily use this hint to sort through all these options on their own.

If I were explaining this to a friend, I’d say something like “you can use git pull --rebase or git pull --no-rebase to resolve this with a rebase or merge right now, and if you want to set a permanent preference, you can do that with git config pull.rebase false or git config pull.rebase true.

git config pull.ff only feels a little redundant to me because that’s git’s default behaviour anyway (though it wasn’t always).

What I like to do here:

• run git status to see the state of my current branch
• maybe run git log origin/main or git log to see what the diverged commits are
• usually run git pull --rebase to resolve it
• sometimes I’ll run git push --force or git reset --hard origin/main if I want to throw away my local work or remote work (for example because I accidentally commited to the wrong branch, or because I ran git commit --amend on a personal branch that only I’m using and want to force push)

error: git checkout asdf (a branch that doesn't exist)

$ git checkout asdf
error: pathspec 'asdf' did not match any file(s) known to git

This is a little weird because we my intention was to check out a branch, but git checkout is complaining about a path that doesn’t exist.

This is happening because git checkout’s first argument can be either a branch or a path, and git has no way of knowing which one you intended. This seems tricky to improve, but I might expect something like “No such branch, commit, or path: asdf”.

What I like to do here:

• in theory it would be good to use git switch instead, but I keep using git checkout anyway
• generally I just remember that I need to decode this as “branch asdf doesn’t exist”

error: git switch asdf (a branch that doesn't exist)

$ git switch asdf
fatal: invalid reference: asdf

git switch only accepts a branch as an argument (unless you pass -d), so why is it saying invalid reference: asdf instead of invalid branch: asdf?

I think the reason is that internally, git switch is trying to be helpful in its error messages: if you run git switch v0.1 to switch to a tag, it’ll say:

$ git switch v0.1
fatal: a branch is expected, got tag 'v0.1'`

So what git is trying to communicate with fatal: invalid reference: asdf is “asdf isn’t a branch, but it’s not a tag either, or any other reference”. From my various git polls my impression is that a lot of git users have literally no idea what a “reference” is in git, so I’m not sure if that’s coming across.

What I like to do here:

90% of the time when a git error message says reference I just mentally replace it with branch in my head.

error: git checkout HEAD^

$ git checkout HEAD^
Note: switching to 'HEAD^'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c 

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

HEAD is now at 182cd3f add "swap byte order" button

This is a tough one. Definitely a lot of people are confused about this message, but obviously there's been a lot of effort to improve it too. I don't have anything smart to say about this one.

What I like to do here:

• my shell prompt tells me if I’m in detached HEAD state, and generally I can remember not to make new commits while in that state
• when I’m done looking at whatever old commits I wanted to look at, I’ll run git checkout main or something to go back to a branch

message: git status when a rebase is in progress

This isn’t an error message, but I still find it a little confusing on its own:

$ git status
interactive rebase in progress; onto c694cf8
Last command done (1 command done):
   pick 0a9964d wip
No commands remaining.
You are currently rebasing branch 'main' on 'c694cf8'.
  (fix conflicts and then run "git rebase --continue")
  (use "git rebase --skip" to skip this patch)
  (use "git rebase --abort" to check out the original branch)

Unmerged paths:
  (use "git restore --staged ..." to unstage)
  (use "git add ..." to mark resolution)
  both modified:   index.html

no changes added to commit (use "git add" and/or "git commit -a")

Two things I think could be clearer here:

1. I think it would be nice if You are currently rebasing branch 'main' on 'c694cf8'. were on the first line instead of the 5th line – right now the first line doesn’t say which branch you’re rebasing.
2. In this case, c694cf8 is actually origin/main, so I feel like You are currently rebasing branch 'main' on 'origin/main' might be even clearer.

What I like to do here:

My shell prompt includes the branch that I’m currently rebasing, so I rely on that instead of the output of git status.

error: git rebase when a file has been deleted

$ git rebase main
CONFLICT (modify/delete): index.html deleted in 0ce151e (wip) and modified in HEAD.  Version HEAD of index.html left in tree.
error: could not apply 0ce151e... wip

The thing I still find confusing about this is – index.html was modified in HEAD. But what is HEAD? Is it the commit I was working on when I started the merge/rebase, or is it the commit from the other branch? (the answer is “HEAD is your branch if you’re doing a merge, and it’s the “other branch” if you’re doing a rebase, but I always find that hard to remember)

I think I would personally find it easier to understand if the message listed the branch names if possible, something like this:

CONFLICT (modify/delete): index.html deleted on `main` and modified on `mybranch`

error: git status during a merge or rebase (who is "them"?)

$ git status 
On branch master
You have unmerged paths.
  (fix conflicts and run "git commit")
  (use "git merge --abort" to abort the merge)
Unmerged paths:
(use “git add/rm …” as appropriate to mark resolution)
deleted by them: the_file
no changes added to commit (use “git add” and/or “git commit -a”)

I find this one confusing in exactly the same way as the previous message: it says deleted by them:, but what “them” refers to depends on whether you did a merge or rebase or cherry-pick.

• for a merge, them is the other branch you merged in
• for a rebase, them is the branch that you were on when you ran git rebase
• for a cherry-pick, I guess it’s the commit you cherry-picked

What I like to do if I’m confused:

• try to remember what I did
• run git show main --stat or something to see what I did on the main branch if I can’t remember

error: git clean

$ git clean
fatal: clean.requireForce defaults to true and neither -i, -n, nor -f given; refusing to clean

I just find it a bit confusing that you need to look up what -i, -n and -f are to be able to understand this error message. I’m personally way too lazy to do that so even though I’ve probably been using git clean for 10 years I still had no idea what -i stood for (interactive) until I was writing this down.

What I like to do if I’m confused:

Usually I just chaotically run git clean -f to delete all my untracked files and hope for the best, though I might actually switch to git clean -i now that I know what -i stands for. Seems a lot safer.

that’s all!

Hopefully some of this is helpful!

I noticed some tech bloggers I follow have been making April Cools Day posts about topics they don’t normally write about (like decaf or microscopes). The goal isn’t to trick anyone, just to write about something different for a day.

I thought those posts were fun so here is a post with some notes on learning to crochet tiny cacti.

first, the cacti

I’ve been trying to do some non-computer hobbies, without putting a lot of pressure on myself to be “good” at them. Here are some cacti I crocheted:

They are a little wonky and I like them.

a couple of other critters

Here are a couple of other things I made: an elephant, an orange guy, a much earlier attempt at a cactus, and an in-progress cactus

Some of these are also pretty wonky, but sometimes it adds to the charm: for example the elephant’s head is attached at an angle which was not on purpose but I think adds to the effect. (orange guy pattern, elephant pattern)

I haven’t really been making clothing: I like working in a pretty chaotic way and I think you need to be a lot more careful when you make clothing so that it will actually fit.

the first project: a mouse

The first project I made was this little mouse. It took me a few hours (maybe 3 hours?) and I made a lot of mistakes and it definitely was not as cute as it was in the pictures in the pattern, but it was still good! I can’t find a picture right now though.

buying patterns is great

Originally I started out using free patterns, but I found some cacti patterns I really liked in an ebook called Knotmonsters: Cactus Gardens Edition, so I bought it.

I like the patterns in that book and also buying patterns seems like a nice way to support people who are making fun patterns. I found this guide to designing your own patterns through searching on Ravelry and it seems like a lot of work! Maybe I will do it one day but for now I appreciate the work of other people who make the patterns.

modifying patterns chaotically is great too

I’ve been modifying all of the patterns I make in a somewhat chaotic way, often just because I made a mistake somewhere along the way and then decide to move forward and change the pattern to adjust for the mistake instead of undoing my work. Some of of the changes I’ve made are:

• remove rows
• put fewer stitches in a row
• use a different stitch

This doesn’t always work but often it works well enough, and I think all of the mistakes help me learn.

no safety eyes

A lot of the patterns I’ve been seeing for animals suggest using “safety eyes” (plastic eyes). I didn’t really feel like buying those , so I’ve been embroidering eyes on instead. “Embroidering” might not be accurate, really I just sew some black yarn on in a haphazard way and hope it doesn’t come out looking too weird.

My crochet kit came with a big plastic yarn needle that I’ve been using to embroider and also

no stitch markers

My crochet kit came with some plastic “stitch markers” which you can use to figure out where the beginning of your row is, so you know when you’re done. I’ve been finding it easier to just use a short piece of scrap yarn instead.

on dealing with all the counting

In crochet there is a LOT of counting. Like “single crochet 3 times, then double crochet 1 time, then repeat that 6 times”. I find it hard to do that accurately without making mistakes, and all of the counting is not that fun! A few things that have helped:

• go back and look at my stitches to see what I did (“have I done 1 single crochet, or 2?”). I’m not actually very good at doing this, but I find it easier to see my stitches with wool/cotton yarn than with acrylic yarn for some reason.
• count how many stitches in total I’ve done since the last row, and make sure it seems approximately right (“well, I’m supposed to have 20 stitches and I have 19, that’s pretty close!”). Then I’ll maybe just add an extra stitch in the wrong place to adjust, or maybe just leave it the way it is.

notes on yarn

So far I’ve tried three kinds of yarn: merino (for the elephant), cotton (for the cacti), and acrylic (for the orange dude). I still don’t know which one I like best, but since I’m doing small projects it feels like the right move is still to just buy small amounts of yarn and experiment. I think I like the cotton and merino more than the acrylic.

For the cacti I used Ricorumi cotton yarn, which comes in tiny balls (which is good for me because if I don’t end up liking it, I don’t have a lot of extra!) and in a lot of different colours.

There are a lot of yarn weights (lace! sock! sport! DK! worsted! bulky! and more!). I don’t really underestand them yet but I think so far I’ve been mostly using DK and worsted yarn.

hook size? who knows!

I’ve mostly been using a 3.5mm hook, probably because I read a tutorial that said to use a 3.5mm hook. It seems to work fine! I used a larger hook size when making a hat, and that also worked.

I still don’t really know how to choose hook sizes but that doesn’t seem to have a lot of consequences when making cacti.

every stitch I’ve learned

I think I’ve probably only learned how to do 5 things in crochet so far:

• magic ring (mr)
• single crochet (sc)
• half double crochet (hdc)
• front post half double crochet (fphdc)
• double crochet (dc)
• back loops only/front loops only (flo/blo)
• increase/decrease

The way I’ve been approaching learning new crochet stitches is:

1. find a pattern I want to make
2. start it without reviewing it very much at all
3. when I get to a stitch I don’t know, watch youtube videos
4. don’t watch it very carefully and get it wrong
5. eventually realize that it doesn’t look right at all, rewatch the video, and continue

I’ve been using Sarah Maker’s pages a lot, except for the magic ring where I used this 3-minute youtube video.

The magic ring took me a very long time to learn to do correctly, I didn’t pay attention very closely to the 3-minute youtube video so I did it wrong in maybe 4 projects before I figured out how to do it right.

every single thing I’ve bought

So far I’ve only needed:

1. a crochet kit (which I got as a gift). it came with yarn, a bunch of crochet needles in different sizes, big sewing needles, and some other things I haven’t needed yet.
2. some Ricorumi cotton (for the cacti)
3. 1 ball of gray yarn (for the elephant)

I’ve been trying to not buy too much stuff, because I never know if I’ll get bored with a new hobby, and if I get bored it’s annoying to have a bunch of stuff lying around. Some examples of things I’ve avoided buying so far:

• Instead of buying polyester fiberfill, to fill all of the critters I’ve just been cutting up an old sweater I have that was falling apart.
• I’ve been embroidering the eyes instead of buying safety eyes

Everything I have right now fits in a the box the crochet kit came in (which is about the size of a large shoebox), and my plan is to keep it that way for a while.

that’s all!

Mainly what I like about crochet so far is that:

• it’s a way to not be on the computer, and you can chat with people while doing it
• you can do it without buying too much stuff, it’s pretty compact
• I end up with cacti in our living room which is great (I also have a bunch of real succulents, so they go with those)
• it seems extremely forgiving of mistakes and experimentation

There are definitely still a lot of things I’m doing “wrong” but it’s fun to learn through trial and error.

A new thing I’ve been trying while writing this Git zine is doing a bunch of polls on Mastodon to learn about:

• which git commands/workflows people use (like “do you use merge or rebase more?” or “do you put your current git branch in your shell prompt?”)
• what kinds of problems people run into with git (like “have you lost work because of a git problem in the last year or two?”)
• which terminology people find confusing (like “how confident do you feel that you know what HEAD means in git?”)
• how people think about various git concepts (“how do you think about git branches?”)
• in what ways my usage of git is “normal” and in what ways it’s “weird”. Where am I pretty similar to the majority of people, and where am I different?

It’s been a lot of fun and some of the results have been surprising to me, so here are some of the results. I’m partly just posting these so that I can have them all in one place for myself to refer to, but maybe some of you will find them interesting too.

these polls are highly unscientific

Polls on social media that I thought about for approximately 45 seconds before posting are not the most rigorous way of doing user research, so I’m pretty cautious about drawing conclusions from them. Potential problems include: I phrased the poll badly, the set of possible responses aren’t chosen very carefully, some of the poll responses I just picked because I thought they were funny, and the set of people who follow me on Mastodon is not representative of all git users.

But here are a couple of examples of why I still find these poll results useful:

• The first poll is “what’s your approach to merge commits and rebase in git”? 600 people (30% of responders) replied “I usually use merge, rarely/never rebase”. It’s helpful for me to know that there are a lot of people out there who rarely/never use rebase, because I use rebase all the time – it’s a good reminder that my experiences isn’t necessarily representative.
• For the poll “how confident do you feel that you know what HEAD means in git?”, 14% of people replied “literally no idea”. That tells me to be careful about assuming that people know what HEAD means in my writing.

where to read more

If you want to read more about any given poll, you can click at the date at the bottom – there’s usually a bunch of interesting follow-up discussion.

Also this post has a lot of CSS so it might not work well in a feed reader.

Now! Here are the polls! I’m mostly just going to post the results without commenting on them.

merge and rebase

merge conflicts

I thought it was interesting in the next one that “edit the weird text file by hand” was most people’s preference:

git pull

commits

branches

git environment

losing work

meaning of various git terms

These polls gave me the impression that for a lot of git terms (fast-forward, reference, HEAD), there are a lot of git users who have “literally no idea” what they mean. That makes me want to be careful about using and defining those terms.

other version control systems

I occasionally hear “SVN was better than git!” but this “svn vs git” poll makes me think that’s a minority opinion. I’m much more cautious about concluding anything from the hg-vs-git poll but it does seem like some people prefer git and some people prefer Mercurial.

that’s all!

It’s been very fun to run all of these polls and I’ve learned a lot about how people use and think about git.

Hello! I know I just wrote a blog post about HEAD in git, but I’ve been thinking more about what the term “current branch” means in git and it’s a little weirder than I thought.

four possible definitions for “current branch”

1. It’s what’s in the file .git/HEAD. This is how the git glossary defines it.
2. It’s what git status says on the first line
3. It’s what you most recently checked out with git checkout or git switch
4. It’s what’s in your shell’s git prompt. I use fish_git_prompt so that’s what I’ll be talking about.

I originally thought that these 4 definitions were all more or less the same, but after chatting with some people on Mastodon, I realized that they’re more different from each other than I thought.

So let’s talk about a few git scenarios and how each of these definitions plays out in each of them. I used git version 2.39.2 (Apple Git-143) for all of these experiments.

scenario 1: right after git checkout main

Here’s the most normal situation: you check out a branch.

1. .git/HEAD contains ref: refs/heads/main
2. git status says On branch main
3. The thing I most recently checked out was: main
4. My shell’s git prompt says: (main)

In this case the 4 definitions all match up: they’re all main. Simple enough.

scenario 2: right after git checkout 775b2b399

Now let’s imagine I check out a specific commit ID (so that we’re in “detached HEAD state”).

1. .git/HEAD contains 775b2b399fb8b13ee3341e819f2aaa024a37fa92
2. git status says HEAD detached at 775b2b39
3. The thing I most recently checked out was 775b2b399
4. My shell’s git prompt says ((775b2b39))

Again, these all basically match up – some of them have truncated the commit ID and some haven’t, but that’s it. Let’s move on.

scenario 3: right after git checkout v1.0.13

What if we’ve checked out a tag, instead of a branch or commit ID?

1. .git/HEAD contains ca182053c7710a286d72102f4576cf32e0dafcfb
2. git status says HEAD detached at v1.0.13
3. The thing I most recently checked out was v1.0.13
4. My shell’s git prompt says ((v1.0.13))

Now things start to get a bit weirder! .git/HEAD disagrees with the other 3 indicators: git status, the git prompt, and what I checked out are all the same (v1.0.13), but .git/HEAD contains a commit ID.

The reason for this is that git is trying to help us out: commit IDs are kind of opaque, so if there’s a tag that corresponds to the current commit, git status will show us that instead.

Some notes about this:

• If we check out the commit by its ID (git checkout ca182053c7710a286d72) instead of by its tag, what shows up in git status and in my shell prompt are exactly the same – git doesn’t actually “know” that we checked out a tag.
• it looks like you can find the tags matching HEAD by running git describe HEAD --tags --exact-match (here’s the fish git prompt code)
• You can see where git-prompt.sh added support for describing a commit by a tag in this way in commit 27c578885 in 2008.
• I don’t know if it makes a difference whether the tag is annotated or not.
• If there are 2 tags with the same commit ID, it gets a little weird. For example, if I add the tag v1.0.12 to this commit so that it’s with both v1.0.12 and v1.0.13, you can see here that my git prompt changes, and then the prompt and git status disagree about which tag to display:

bork@grapefruit ~/w/int-exposed ((v1.0.12))> git status
HEAD detached at v1.0.13

(my prompt shows v1.0.12 and git status shows v1.0.13)

scenario 4: in the middle of a rebase

Now: what if I check out the main branch, do a rebase, but then there was a merge conflict in the middle of the rebase? Here’s the situation:

1. .git/HEAD contains c694cf8aabe2148b2299a988406f3395c0461742 (the commit ID of the commit that I’m rebasing onto, origin/main in this case)
2. git status says interactive rebase in progress; onto c694cf8
3. The thing I most recently checked out was main
4. My shell’s git prompt says (main|REBASE-i 1/1)

Some notes about this:

• I think that in some sense the “current branch” is main here – it’s what I most recently checked out, it’s what we’ll go back to after the rebase is done, and it’s where we’d go back to if I run git rebase --abort
• in another sense, we’re in a detached HEAD state at c694cf8aabe2. But it doesn’t have the usual implications of being in “detached HEAD state” – if you make a commit, it won’t get orphaned! Instead, assuming you finish the rebase, it’ll get absorbed into the rebase and put somewhere in the middle of your branch.
• it looks like during the rebase, the old “current branch” (main) is stored in .git/rebase-merge/head-name. Not totally sure about this though.

scenario 5: right after git init

What about when we create an empty repository with git init?

1. .git/HEAD contains ref: refs/heads/main
2. git status says On branch main (and “No commits yet”)
3. The thing I most recently checked out was, well, nothing
4. My shell’s git prompt says: (main)

So here everything mostly lines up, except that we’ve never run git checkout or git switch. Basically Git automatically switches to whatever branch was configured in init.defaultBranch.

scenario 6: a bare git repository

What if we clone a bare repository with git clone --bare https://github.com/rbspy/rbspy?

1. HEAD contains ref: refs/heads/main
2. git status says fatal: this operation must be run in a work tree
3. The thing I most recently checked out was, well, nothing, git checkout doesn’t even work in bare repositories
4. My shell’s git prompt says: (BARE:main)

So #1 and #4 match (they both agree that the current branch is “main”), but git status and git checkout don’t even work.

Some notes about this one:

• I think HEAD in a bare repository mainly only really affects 1 thing: it’s the branch that gets checked out when you clone the repository. It’s also used when you run git log.
• if you really want to, you can update HEAD in a bare repository to a different branch with git symbolic-ref HEAD refs/heads/whatever. I’ve never needed to do that though and it seems weird because git symbolic ref doesn’t check if the thing you’re pointing HEAD at is actually a branch that exists. Not sure if there’s a better way.

all the results

Here’s a table with all of the results:

“current branch” doesn’t seem completely well defined

My original instinct when talking about git was to agree with the git glossary and say that HEAD and the “current branch” mean the exact same thing.

But this doesn’t seem as ironclad as I used to think anymore! Some thoughts:

• .git/HEAD is definitely the one with the most consistent format – it’s always either a branch or a commit ID. The others are all much messier
• I have a lot more sympathy than I used to for the definition “the current branch is whatever you last checked out”. Git does a lot of work to remember which branch you last checked out (even if you’re currently doing a bisect or a merge or something else that temporarily moves HEAD off of that branch) and it feels weird to ignore that.
• git status gives a lot of helpful context – these 5 status messages say a lot more than just what HEAD is set to currently
  1. on branch main
  2. HEAD detached at 775b2b39
  3. HEAD detached at v1.0.13
  4. interactive rebase in progress; onto c694cf8
  5. on branch main, no commits yet

some more “current branch” definitions

I’m going to try to collect some other definitions of the term current branch that I heard from people on Mastodon here and write some notes on them.

1. “the branch that would be updated if i made a commit”

• Most of the time this is the same as .git/HEAD
• Arguably if you’re in the middle of a rebase, it’s different from HEAD, because ultimately that new commit will end up on the branch in .git/rebase-merge/head-name

2. “the branch most git operations work against”

• This is sort of the same as what’s in .git/HEAD, except that some operations (like git status) will behave differently in some situations, like how git status won’t tell you the current branch if you’re in a bare repository

on orphaned commits

One thing I noticed that wasn’t captured in any of this is whether the current commit is orphaned or not – the git status message (HEAD detached from c694cf8) is the same whether or not your current commit is orphaned.

I imagine this is because figuring out whether or not a given commit is orphaned might take a long time in a large repository: you can find out if the current commit is orphaned with git branch --contains HEAD, and that command takes about 500ms in a repository with 70,000 commits.

Git will warn you if the commit is orphaned (“Warning: you are leaving 1 commit behind, not connected to any of your branches…”) when you switch to a different branch though.

that’s all!

I don’t have anything particularly smart to say about any of this. The more I think about git the more I can understand why people get confused.

Hello! The other day I ran a Mastodon poll asking people how confident they were that they understood how HEAD works in Git. The results (out of 1700 votes) were a little surprising to me:

• 10% “100%”
• 36% “pretty confident”
• 39% “somewhat confident?”
• 15% “literally no idea”

I was surprised that people were so unconfident about their understanding – I’d been thinking of HEAD as a pretty straightforward topic.

Usually when people say that a topic is confusing when I think it’s not, the reason is that there’s actually some hidden complexity that I wasn’t considering. And after some follow up conversations, it turned out that HEAD actually was a bit more complicated than I’d appreciated!

Here’s a quick table of contents:

• HEAD is actually a few different things
• the file .git/HEAD
• HEAD as in git show HEAD
• next: all the output formats
  • git status: “on branch main” or “HEAD detached”
  • detached HEAD state
  • git log: (HEAD -> main)
  • merge conflicts: <<<<<<< HEAD is just confusing

HEAD is actually a few different things

After talking to a bunch of different people about HEAD, I realized that HEAD actually has a few different closely related meanings:

1. The file .git/HEAD
2. HEAD as in git show HEAD (git calls this a “revision parameter”)
3. All of the ways git uses HEAD in the output of various commands (<<<<<<<<<<HEAD, (HEAD -> main), detached HEAD state, On branch main, etc)

These are extremely closely related to each other, but I don’t think the relationship is totally obvious to folks who are starting out with git.

the file .git/HEAD

Git has a very important file called .git/HEAD. The way this file works is that it contains either:

1. The name of a branch (like ref: refs/heads/main)
2. A commit ID (like 96fa6899ea34697257e84865fefc56beb42d6390)

This file is what determines what your “current branch” is in Git. For example, when you run git status and see this:

$ git status
On branch main

it means that the file .git/HEAD contains ref: refs/heads/main.

If .git/HEAD contains a commit ID instead of a branch, git calls that “detached HEAD state”. We’ll get to that later.

HEAD as in git show HEAD

It’s very common to use HEAD in git commands to refer to a commit ID, like:

• git diff HEAD
• git rebase -i HEAD^^^^
• git diff main..HEAD
• git reset --hard HEAD@{2}

All of these things (HEAD, HEAD^^^, HEAD@{2}) are called “revision parameters”. They’re documented in man gitrevisions, and Git will try to resolve them to a commit ID.

(I’ve honestly never actually heard the term “revision parameter” before, but that’s the term that’ll get you to the documentation for this concept)

HEAD in git show HEAD has a pretty simple meaning: it resolves to the current commit you have checked out! Git resolves HEAD in one of two ways:

1. if .git/HEAD contains a branch name, it’ll be the latest commit on that branch (for example by reading it from .git/refs/heads/main)
2. if .git/HEAD contains a commit ID, it’ll be that commit ID

next: all the output formats

Now we’ve talked about the file .git/HEAD, and the “revision parameter” HEAD, like in git show HEAD. We’re left with all of the various ways git uses HEAD in its output.

git status: “on branch main” or “HEAD detached”

When you run git status, the first line will always look like one of these two:

1. on branch main. This means that .git/HEAD contains a branch.
2. HEAD detached at 90c81c72. This means that .git/HEAD contains a commit ID.

I promised earlier I’d explain what “HEAD detached” means, so let’s do that now.

detached HEAD state

“HEAD is detached” or “detached HEAD state” mean that you have no current branch.

Having no current branch is a little dangerous because if you make new commits, those commits won’t be attached to any branch – they’ll be orphaned! Orphaned commits are a problem for 2 reasons:

1. the commits are more difficult to find (you can’t run git log somebranch to find them)
2. orphaned commits will eventually be deleted by git’s garbage collection

Personally I’m very careful about avoiding creating commits in detached HEAD state, though some people prefer to work that way. Getting out of detached HEAD state is pretty easy though, you can either:

1. Go back to a branch (git checkout main)
2. Create a new branch at that commit (git checkout -b newbranch)
3. If you’re in detached HEAD state because you’re in the middle of a rebase, finish or abort the rebase (git rebase --abort)

Okay, back to other git commands which have HEAD in their output!

git log: (HEAD -> main)

When you run git log and look at the first line, you might see one of the following 3 things:

1. commit 96fa6899ea (HEAD -> main)
2. commit 96fa6899ea (HEAD, main)
3. commit 96fa6899ea (HEAD)

It’s not totally obvious how to interpret these, so here’s the deal:

• inside the (...), git lists every reference that points at that commit, for example (HEAD -> main, origin/main, origin/HEAD) means HEAD, main, origin/main, and origin/HEAD all point at that commit (either directly or indirectly)
• HEAD -> main means that your current branch is main
• If that line says HEAD, instead of HEAD ->, it means you’re in detached HEAD state (you have no current branch)

if we use these rules to explain the 3 examples above: the result is:

1. commit 96fa6899ea (HEAD -> main) means:
   • .git/HEAD contains ref: refs/heads/main
   • .git/refs/heads/main contains 96fa6899ea
2. commit 96fa6899ea (HEAD, main) means:
   • .git/HEAD contains 96fa6899ea (HEAD is “detached”)
   • .git/refs/heads/main also contains 96fa6899ea
3. commit 96fa6899ea (HEAD) means:
   • .git/HEAD contains 96fa6899ea (HEAD is “detached”)
   • .git/refs/heads/main either contains a different commit ID or doesn’t exist

merge conflicts: <<<<<<< HEAD is just confusing

When you’re resolving a merge conflict, you might see something like this:

<<<<<<< HEAD
def parse(input):
    return input.split("\n")
=======
def parse(text):
    return text.split("\n\n")
>>>>>>> somebranch

I find HEAD in this context extremely confusing and I basically just ignore it. Here’s why.

• When you do a merge, HEAD in the merge conflict is the same as what HEAD was when you ran git merge. Simple.
• When you do a rebase, HEAD in the merge conflict is something totally different: it’s the other commit that you’re rebasing on top of. So it’s totally different from what HEAD was when you ran git rebase. It’s like this because rebase works by first checking out the other commit and then repeatedly cherry-picking commits on top of it.

Similarly, the meaning of “ours” and “theirs” are flipped in a merge and rebase.

The fact that the meaning of HEAD changes depending on whether I’m doing a rebase or merge is really just too confusing for me and I find it much simpler to just ignore HEAD entirely and use another method to figure out which part of the code is which.

some thoughts on consistent terminology

I think HEAD would be more intuitive if git’s terminology around HEAD were a little more internally consistent.

For example, git talks about “detached HEAD state”, but never about “attached HEAD state” – git’s documentation never uses the term “attached” at all to refer to HEAD. And git talks about being “on” a branch, but never “not on” a branch.

So it’s very hard to guess that on branch main is actually the opposite of HEAD detached. How is the user supposed to guess that HEAD detached has anything to do with branches at all, or that “on branch main” has anything to do with HEAD?

that’s all!

If I think of other ways HEAD is used in Git (especially ways HEAD appears in Git’s output), I might add them to this post later.

If you find HEAD confusing, I hope this helps a bit!