Branches for the risky change

A branch is a sticky note

Inside your project, .git/refs/heads/main is a file containing forty-one bytes: the id of a commit and a newline. That is a branch. It is a name that points at a commit, and when you commit on that branch the name moves forward to the new one.

main is not special. It is the default name and nothing more. Creating a branch writes another forty-one-byte file, which is why it is instant and free, and why the advice in this lesson is to use them more often than you would guess.

git switch -c payments      # create and move to it (older form: git checkout -b)
git branch                  # list branches; the * marks where you are
git switch main             # go back

What travels with you

Your uncommitted edits are in the working tree, and the working tree belongs to no branch. Switch branches and they come along. Git refuses the switch only when it would have to overwrite a file you have edited with a different version from the target branch; then it says so and stops, and the answer is to commit or to stash.

The earlier lesson used git stash to set work aside for a test. The same command lets you park half-finished work, switch to main to fix something urgent, and return with git stash pop. A stash is a stack; git stash list shows what is parked. Forgotten stashes are the common way work goes missing, so pop them the same day.

Merging back

git switch main
git merge payments
git branch -d payments      # tidy up once merged

Two things can happen at the merge. If main has not moved since you branched, git slides the main name forward to your latest commit: a fast-forward, no new commit made. If main has moved, git makes a merge commit with two parents, one from each line of work. Both are normal.

git branch -d refuses to delete a branch whose commits are not merged anywhere. -D deletes it regardless. That capital letter is the one to use on purpose, and it is the point of the next section.

One branch per agent task

This is the single most protective habit in the course for people working with an agent.

Before you hand an agent a feature, git switch -c feature-name. Let it work. When it goes well, merge. When it goes badly (three hours, forty files, an app that will not start) the exit is two commands:

git switch main
git branch -D feature-name

The mess is gone. Main is exactly what it was this morning, because main was never on the receiving end. Compare that with the alternative of picking through forty files deciding what to keep.

Branch for anything you might abandon or that will take more than one session: a redesign, swapping a library, “let us try Postgres instead”. Do not branch for a one-line fix; the overhead is real and the protection is not needed.

Two folders at once

A branch checked out in one folder cannot be checked out in another. git worktree add ../app-payments payments creates a second folder with the payments branch in it, sharing the same history. Two agents can work on two features without editing the same files, and main stays runnable in its own folder while a branch is broken.

The cost is that each worktree needs its own node_modules; a symlink between them breaks some build tools, so install separately or copy.

The word you will hear: rebase

Rebase rewrites your branch so its commits appear to start from the current tip of main, giving a straight-line history instead of merge commits. It does this by making new commits with new ids. That is fine on a branch only you have; it is the reason for the one rule people learn the hard way: never rebase commits that have been pushed and that somebody else may have built on.

You can build real software for years without rebasing. It is mentioned here so that when an agent proposes it, you know it rewrites history and can decline.

Branch names are a message

fix-cancel-button beats fix. In a fortnight the list of branches is the list of things you started, and the name is all you have. Most hosts also turn a branch into a preview URL that carries the name, which is where the shipping half of this block picks up.