HEAD, refs, origin, upstream, tracking, detached HEAD

Why this matters

Git's output is full of names: HEAD -> main, origin/main, HEAD~1, detached HEAD. They are not jargon for its own sake; each one is a pointer to a commit, and once you know where each points, git log and git status read like a map with labels on it.

Everything is a label on a commit

A commit is identified by its hash. Nobody wants to remember hashes, so Git keeps refs: named pointers to commits, stored as tiny files inside .git/refs. There are three kinds:

$ git log --oneline --decorate

97773ae (HEAD -> main) docs: add Windows steps to installation guide (#12)
0d9eb38 (tag: v1.2.0, origin/main) docs: add map question to FAQ (#9)
8fa922e Initial import of trailguide

Read the parentheses: main points at 97773ae; HEAD points at main; the tag v1.2.0 and the remote-tracking name origin/main both point at 0d9eb38. So the local main is one commit ahead of the remote, exactly what git status says.

HEAD: where you are

HEAD is the pointer that answers "where am I?". Normally it points at a branch (HEAD -> main), which in turn points at a commit. When you commit, the branch moves, and HEAD follows because it is attached to the branch.

$ cat .git/HEAD

ref: refs/heads/main

Relative names count backwards from HEAD along parent links:

~ and ^ mean the same for ordinary commits; they differ only on merge commits, which have two parents (^2 picks the second). You can use these names anywhere a hash is accepted: git show HEAD~1, git diff HEAD~2.

origin, origin/main, upstream, tracking

Four names that beginners hear as one:

• origin is the nickname of the remote repository you cloned from: a name for a URL. git push origin main means "push main to that URL". Almost every project has exactly one remote and it is called origin.
• origin/main is a remote-tracking branch: your local bookmark of where the remote's main was the last time you fetched or pushed. It is not the remote itself; it is a snapshot of your knowledge of it. Only git fetch, git pull and git push move it.
• Tracking branch (or upstream): a local branch that is linked to a remote branch, so that git status can report ahead/behind, and git pull and git push know where to go without arguments. main tracks origin/main automatically after a clone. A new branch tracks nothing until you git push -u origin <branch> (the -u sets the upstream).

$ git branch -a

* main
  remotes/origin/main

git branch -a lists local branches (the * marks the current one) and the remote-tracking ones under remotes/.

Detached HEAD

Sometimes HEAD points directly at a commit instead of at a branch. That is detached HEAD, and Git warns you loudly when it happens, for example after checking out an old commit to look at it:

$ git checkout HEAD~1

Note: switching to 'HEAD~1'.

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 <new-branch-name>

Or undo this operation with:

  git switch -

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

HEAD is now at 0d9eb38 docs: add map question to FAQ (#9)

$ git status

HEAD detached at 0d9eb38
nothing to commit, working tree clean

Nothing is broken. Your files now show the project as it was at that commit. The danger is only this: if you commit while detached, no branch label moves to your new commit, so when you switch back to main the commit is left behind and easy to lose. The message tells you both exits:

• To look and leave: git switch - (back to the previous branch).
• To keep new work: git switch -c new-branch-name, which creates a branch at the current commit and attaches HEAD to it.

$ git switch -

Previous HEAD position was 0d9eb38 docs: add map question to FAQ (#9)
Switched to branch 'main'
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

You also land in detached HEAD when checking out a tag (git checkout v1.2.0) or a remote-tracking branch (git checkout origin/main), and pipelines run in that state on purpose. Lesson 12.5 shows how to rescue commits made while detached.

Common mistakes

• Reading origin/main as "the remote right now". It is the remote as of your last fetch. git fetch updates it.
• Committing in detached HEAD and switching away. The commit becomes an orphan. If it happens, git reflog finds it (lesson 12.1); prevention is git switch -c before committing.
• Expecting git push to work on a new branch. The first push needs -u origin <branch> to set the upstream; Git prints the exact command when you forget.
• Confusing HEAD with main. They usually point at the same commit, but HEAD is "where I am" and main is a branch; after git switch feature/21, HEAD points at feature/21.