In the previous lesson we took the mystery apart: a branch is a 41-byte file with a hash inside, and HEAD is another file that records which branch you are on. Now we are going to put that machinery to work. Ana will finally open feature/task-counter, Bruno will do the same with feature/pending-filter, and the repository will stop having a single line of work.

Creating branches in Git is trivial — you will see that in a second — but moving between them has subtleties worth mastering from the start: what happens to the work you have half finished, why Git sometimes lets you switch and sometimes refuses, and what that detached HEAD state is, the one that turns up when you least expect it and frightens everybody the first time.

We will also settle a question that follows anyone who learned Git before 2019: the difference between git checkout and git switch, and why Git decided to split one command into two.

1. git branch: creating without moving
2. git switch: moving
3. git switch -c: create and move in one step
4. git switch versus git checkout
5. Creating a branch from a specific point in history
6. git switch -: toggling between two branches
7. Uncommitted changes when you switch branches
8. Detached HEAD
9. The team's repository, now with branches

Ana is on main, with the repository exactly as we left it:

She wants a branch for the task counter:

Complete silence. In Git, silence usually means success. Let us see exactly what happened:

A new file, holding the hash of the commit Ana was sitting on. (An interesting aside: because the branch name contains a slash, Git has created a directory called feature/ inside refs/heads/. Branch names with slashes are simply file paths; we will come back to naming conventions in lesson 03-06.)

Now the important part:

HEAD has not moved. Ana is still on main. She has created a new pointer but has not placed herself on it:

The asterisk marks the current branch. There are two branches and both point at the same commit.

Rule: git branch <name> creates the pointer and touches nothing else. Not HEAD, not the working tree, not the staging area.

If Ana committed now, the commit would land on main, because that is still where HEAD points. It is a classic mistake: create the branch and forget to switch to it. That is why, in practice, plain git branch is almost never used to start work; the variant in section 3 is.

To place herself on the branch she has just created:

And now:

That is all Git did in this case: rewrite the file .git/HEAD. Because both branches pointed at the same commit, the working tree did not change by a single byte.

When the branches point at different commits, git switch does more: as well as rewriting HEAD, it updates the working tree and the staging area so they match the tree of the target commit. In other words, it changes the files on your disk. That is what happens in the three internal operations of a branch switch:

Ana writes the task counter in app.js and commits:

Look at the name in square brackets: [feature/task-counter 6f2b9d4]. Git is telling you which branch the commit landed on. It is a free check, and one worth reading every time.

Ana then adds the "mark as done" behaviour:

Current state:

main has stayed put at c5d9b1e, exactly where it was. Ana's work is isolated: she can commit as much as she likes without touching the project's main line.

Creating a branch and not switching to it is unusual. Hence the shortcut:

The -c stands for create. It is exactly equivalent to:

This is the form you will use 95% of the time. Plain git branch <name> is reserved for the cases where you want to mark a point in history without abandoning what you are doing (for instance, leaving a bookmark before a risky operation).

One important detail that often gets overlooked: the new branch is created from wherever you are right now. If Ana ran that command while on feature/task-counter, the new branch would start at 9d1e4b7 and drag the task counter along with it, which is not what she wants. For Bruno's work, the correct starting point is main:

Or, better still, by stating it explicitly in a single command — the form we will see in section 5.

There is a capital-letter variant, -C, which creates the branch or resets it if it already exists:

Use it carefully: if the branch already existed pointing somewhere else, -C moves the pointer without asking and you can leave commits orphaned. -c, by contrast, fails with fatal: a branch named '…' already exists, which is almost always what you want.

If you have seen Git in any tutorial written before 2019, or in most of the ones on the internet today, you will have seen this:

It works. git checkout is not deprecated and is not going away. But since Git 2.23 (August 2019) we have git switch and git restore, and for new work they are the recommended option. The reason is simple: git checkout did far too many different things.

Look at the last three rows, which are the important ones. git checkout served both to navigate between branches (a harmless, reversible operation) and to destroy working-tree changes (an irreversible one). The same verb for two things of opposite risk.

The potential disaster lay in the ambiguity. Imagine there is a file called report and also a branch called report:

Does it switch branch or discard the file's changes? Git resolved in favour of the branch, and you had to write git checkout -- report (with the double-dash separator) to force the file interpretation. Forget the -- and you could lose work with no warning.

The split introduced in Git 2.23 removes the ambiguity at the root:

• git switch only works with branches. It cannot touch files.
• git restore only works with files. It cannot switch branches.

You already used git restore in lesson 02-04, so you know half of the reform already. This lesson gives you the other half.

What to do in practice:

• Type git switch and git restore in your everyday work.
• Learn to read git checkout, because you will see it everywhere: old documentation, Stack Overflow answers, continuous integration scripts and colleagues with ingrained habits.
• Do not convert existing scripts that work purely for the sake of fashion; checkout remains perfectly valid.

By default, a new branch starts from HEAD. But you can give it another starting point as a second argument, and that works for both forms of the command:

The starting point can be anything Git knows how to resolve to a commit, with all the syntax you learned in lesson 02-06:

The first is Bruno's case and it is the right way to do it: it creates the branch from main without needing to switch to main first. One command instead of two, and no risk of forgetting.

A real case where this saves your afternoon: you have been coding on main for half an hour by mistake, you have made three commits, and you realise they should have gone on a branch. The fix:

Notice that step 1 uses git branch without switching: it creates the bookmark before moving anything. (git reset --hard is powerful and dangerous; we will study it thoroughly in lesson 09-02. It is safe here because the commits are still reachable from the new branch.)

When you are reviewing a colleague's work and hopping constantly between two branches, typing the full name gets tiring. A lone dash means "the previous branch":

It is the same idea as cd - in the shell. It works with branch names as long as feature/export-list-to-csv and saves an enormous number of keystrokes.

Under the bonnet, the dash is an alias for @{-1}, meaning "the branch I was on one switch ago". And there is more:

This information comes from the reflog, the record Git keeps of every movement of HEAD. It is the same tool that lets you recover apparently lost work, and we will study it in lesson 09-04.

Here is the subtlety that causes the most confusion. What happens to your half-finished work when you switch branches?

The short answer: Git tries to bring it with you, and if it cannot do so without losing anything, it refuses.

The long answer depends on whether the changes affect files that differ between the two branches.

Ana is on feature/task-counter and has started reworking README.md, a file that is identical on both branches:

It worked, and that M README.md line is Git's way of saying that the file arrived modified and is still modified. The change has travelled with Ana to the other branch. It is still uncommitted, in her working tree:

This is deliberately useful: it lets you start writing something, realise you are on the wrong branch and put it right without losing anything.

Now Ana is on main and modifies app.js, which does differ between main and the counter branch (that is where the counter changed it):

Git has refused, and rightly so. To place itself on the other branch it would have to overwrite app.js with the version from there, and that would destroy Ana's changes beyond recovery, because they have never been in the object database.

The important thing is that the operation was aborted entirely. You are still where you were and your changes are untouched.

1. Commit. If the work makes sense on the current branch, commit it. If it is half finished, you can make a provisional commit and tidy it up later with git commit --amend (lesson 02-04) or with an interactive rebase (lesson 05-02).

2. Discard. If the change is worthless, git restore app.js removes it and the branch switch becomes possible.

3. Stash it. For the realistic case — half-finished work you want to keep but that does not yet deserve a commit — Git has a dedicated tool: git stash, which sets the changes aside in a temporary store, leaves the working tree clean and lets you get them back later with git stash pop:

It is a command with a great deal more depth than this example suggests (several stacked entries, including untracked files, applying on another branch…). We will study it in full in lesson 05-04; for now, just remember it exists and that it is the standard answer to this problem.

There is an option to discard the changes and switch branch anyway:

(The old equivalent was git checkout -f.) It is destructive and irreversible: uncommitted changes are not in any Git object, so there is no reflog and no possible recovery. Use it only when you are absolutely certain you want to throw that work away.

Remember the previous lesson: HEAD normally contains ref: refs/heads/<branch>. But it can contain a hash directly. That state is called a detached HEAD.

The deliberate way is to ask for it:

Git gives you a whole speech because the state is unusual, not because it is dangerous. In fact that text already explains almost everything you need to know.

The accidental ways of getting there are the frightening ones:

• git checkout <hash> (without -b), the most common with the old command.
• git checkout v1.2.0, when landing on a tag — tags point at commits, they are not branches.
• During a git rebase or a git bisect, which work internally in this state (modules 5 and 6).
• Landing on origin/main instead of main, a very common mistake we will see in module 4.

A hash directly, with no ref:. HEAD points at the commit, not at a branch.

The working tree holds the files exactly as they were at that commit. It is a perfectly legitimate state: you can build, run the tests, look at old code or even commit.

It is not an accident to be avoided; it is a tool:

• Reviewing how the project looked at a given moment. Ana wants to see the application as it was on the day of the first commit: git switch --detach 1a4c8d6, open index.html in the browser, done.
• Testing whether a bug existed in an older version, by landing on different points in history.
• Experimenting without committing yourself. You can commit in this state, and if the result is no good you go back to a branch and the commits are left orphaned.

The danger is not being in this state. It is committing in it and then leaving without a trace:

That commit 7d2f9a1 is real and is in the object database, but no branch reaches it. If Ana now runs git switch main:

Git warns you, and even hands you the exact command. But if you do not read that warning and close the terminal, the hash disappears from view and the commit is orphaned. It stays recoverable for a while through the reflog (module 9), but it is not a situation you want.

If you have committed nothing (you were only looking):

Or git switch main, or any branch. There is nothing to save.

If you have committed and want to keep it, create a branch before you leave:

Now HEAD points at a branch again, that branch points at 7d2f9a1, and the commit is reachable. Nothing is orphaned any more.

If you have already left and the commit stayed behind, you can still create the branch after the fact, as long as you have the hash (it appears in the warning, and if you lost it, in git reflog):

Let us recap where we are. Ana has her branch with two commits. Bruno has been working on his, with the three commits we saw at the end of module 2 — the pending filter, the styling of completed tasks and the focus fix — now on feature/pending-filter rather than directly on main.

For the rest of the module we will reason as though the three branches lived in one and the same local repository, Ana's. How the team gets work to travel between Ana's laptop and Bruno's MacBook is precisely the subject of module 4; here we concentrate on branch mechanics, which are identical wherever the work comes from.

Three lines of work, three pointers, 123 bytes of total cost. The four base commits sit once in the object database and all three branches share them.

And here is the problem we will solve in the next lesson: both features are finished and tested, but the real project — main — is still exactly where it was a week ago. Nothing Ana and Bruno have done is on the main line.

Mistake 1: git branch <name> and then getting to work. You create the branch, forget the git switch, make five commits and every one lands on main. Two-part prevention: use git switch -c instead of git branch, and read the line in square brackets that git commit prints, which tells you the target branch.

Mistake 2: creating the branch from the wrong place. Running git switch -c fix/urgent while on a half-finished feature branch drags all that unfinished work into the urgent fix. Before creating a branch, check where you are with git branch --show-current, or state the starting point explicitly: git switch -c fix/urgent main.

Mistake 3: panicking about detached HEAD. It is neither an error nor corruption: it is a normal state. The message is long because it explains, not because it is warning you of a disaster. If you were only looking, git switch - and that is that. If you committed, git switch -c <name> before you leave.

Mistake 4: using git checkout -f or --discard-changes to "get unstuck". That command destroys uncommitted changes irreversibly: they are in no Git object and no reflog will help. When Git refuses to switch branch, the right answer is to commit, to discard deliberately with git restore, or to set aside with git stash.

Mistake 5: git switch -C instead of -c. The capital letter resets an existing branch without asking. If the branch already had work on it, the pointer moves and that work is left orphaned. -c fails with a clear error, which in 99% of cases is exactly what you want to happen.

Tip 1: one branch per task, and short-lived. Branches are free, so do not pile work up in them. A branch that lives three weeks accumulates divergence and guarantees conflicts; one that lives two days almost never has any.

Tip 2: turn on Git's autocompletion. With names like feature/pending-filter, typing git switch fea<TAB> is the difference between working comfortably and landing on the wrong branch. The git-completion.bash script ships with Git and many distributions enable it by default.

Tip 3: check where you are before committing. It costs one second:

Tip 4: do not reuse old branches for new tasks. It is tempting (I already have the tests branch, I will reuse it), but it ends in histories nobody can follow and merges that drag in changes nobody asked for. Create a new branch and delete the old one once it is no longer useful; tidying up is the subject of lesson 03-06.

In a test repository with at least three commits, create two branches — experiment/one and experiment/two — without switching to either of them, such that:

• experiment/one starts from the current commit.
• experiment/two starts from two commits back.

Then prove with commands that HEAD has not moved and that both branches point where they should.

Design the minimal sequence of commands that triggers the error Your local changes to the following files would be overwritten by checkout, then resolve it in three different ways, explaining when you would use each.

Deliberately land in a detached HEAD, make a commit there and keep it on a new branch. Then repeat the process but abandon the state without creating the branch, and observe what Git tells you. Which piece of information in the message is essential to note down?

Solution 1:

Checking:

The asterisk is still on main: HEAD has not moved. experiment/one matches main and experiment/two is two commits back, as the exercise asked.

Byte-by-byte verification:

Solution 2:

Two conditions are needed to trigger the error: a file that differs between the two branches, and an uncommitted modification to that same file.

The three resolutions:

When: when the change is valid and makes sense on the current branch.

When: experiments, debugging traces or anything you do not want to keep. It is irreversible.

When: the most common case in daily work, and the reason git stash exists (lesson 05-04).

Solution 3:

The commit is now reachable from a branch: nothing is orphaned.

Second part, leaving without creating a branch:

The essential piece of information is the hash: 3c9d4a2. As long as you have it, recovering the work is a single command:

And if you lose the hash as well, the situation is not hopeless: git reflog stores every movement of HEAD for 90 days by default and lets you find it. That is the subject of lesson 09-04.

You can now create branches and move between them with judgement:

• git branch <name> creates the pointer and touches nothing else: not HEAD, not the working tree, not the index. Useful for marking a point without abandoning what you are doing.
• git switch <branch> places you on a branch: it rewrites .git/HEAD and updates the working tree to the target tree.
• git switch -c <name> [start-point] is the usual way to begin a task: it creates and switches in one step, and accepts any reference as its origin (another branch, a hash, HEAD~2…).
• git switch and git restore replace git checkout as of Git 2.23, splitting up what used to be a single ambiguous command: navigating between branches and destroying changes no longer share a verb. checkout still works and you will keep seeing it in documentation and scripts.
• git switch - toggles back to the previous branch, just like cd -.
• When you switch branches, Git brings uncommitted changes with you if it can do so without losing anything, and aborts cleanly if the file differs between the two branches. The ways out are to commit, to discard with git restore or to set aside with git stash (lesson 05-04).
• A detached HEAD is HEAD holding a hash instead of ref: refs/heads/…. It is not an error: it is there for inspecting and experimenting. The only precaution is to create a branch with git switch -c before leaving it if you have committed anything.

The team now has three branches: main sitting where it was, feature/task-counter with two commits from Ana and feature/pending-filter with three from Bruno. Two finished features that are not in the project.

Isolating the work was half the problem; the other half is bringing it back together. In the next lesson, Merging Branches, Ana will finally integrate both features into main. We will see the two scenarios Git distinguishes — the fast-forward, where the pointer simply moves along, and the three-way merge, which creates a special commit with two parents — how Git finds the common ancestor we studied in the previous lesson, and why it is sometimes worth forcing a merge commit even when one is not needed.