What a branch really is
It is easy to imagine a branch as a copy of the project in a separate folder. It is nothing like that.
In Git, every commit points back at the commit before it, its parent. That makes a chain. A branch is a label stuck on one commit. Making a commit on a branch moves the label forward to the new commit.
One more label, HEAD, marks which branch you are on.
That is all. A branch is a file containing one commit id. This is why making one is instant, and why having hundreds costs nothing. See What git commit Writes for what is underneath.
Sooner or later the work on a branch has to come back into main. There are three ways it can happen, and the differences are easiest to see as pictures.
1. Fast-forward
You branch, you commit twice, and meanwhile nobody touches main.
$ git log
Start. Two commits on main. Each commit points back at the one before it. A branch is nothing more than a label stuck on one commit.
- Commits in the history of main
- 2
- Commits with two parents
- 0
- You are on
- main
main has nothing of its own to combine. Git moves the label forward and is done. No new commit, no chance of a conflict.
2. A merge commit
More often, main has moved on while you worked. Each branch has commits the other lacks.
$ git log
Start. Two commits on main. Each commit points back at the one before it. A branch is nothing more than a label stuck on one commit.
- Commits in the history of main
- 2
- Commits with two parents
- 0
- You are on
- main
Git works out the combined result and saves it as a merge commit: a commit with two parents.
git switch main
git merge featureNothing that existed before is changed. The history records what really happened, including that two lines of work ran side by side.
3. Rebase
Rebase takes a different view: rewrite your branch so that it looks as if you had started from the latest main.
$ git log
Start. Two commits on main. Each commit points back at the one before it. A branch is nothing more than a label stuck on one commit.
- Commits in the history of main
- 2
- Commits with two parents
- 0
- You are on
- main
git switch feature
git rebase main
git switch main
git merge feature # a fast-forward nowGit takes each of your commits in turn, works out what it changed, and applies that change on top of main. The results are new commits with new ids. They hold the same changes, but they are different objects. The old ones are left behind.
Same files, different history
$ git log
Start. Two commits on main. Each commit points back at the one before it. A branch is nothing more than a label stuck on one commit.
- Commits in the history of main
- 2
- Commits with two parents
- 0
- You are on
- main
All three end with the same files in main. What differs is the story the history tells.
| Fast-forward | Merge commit | Rebase | |
|---|---|---|---|
| Possible when | main has not moved | Always | Always |
| New commits made | None | One, with two parents | A new copy of each of your commits |
| Shape of history | A straight line | A fork and a join | A straight line |
| Existing commits changed | No | No | Yes, yours are replaced |
| Shows the work happened in parallel | Not applicable | Yes | No |
Good at
- Merge: never rewrites anything, so it is always safe
- Merge: keeps the true record, and one revert of the merge commit undoes the whole feature
- Rebase: a straight history that is easy to read and to search with git bisect
- Rebase: conflicts are dealt with one small commit at a time
Where it bites
- Merge: a busy project ends up with a tangled graph and many merge commits
- Rebase: replaces commits, which causes trouble if anyone else already has the old ones
- Rebase: the same conflict can come up again for several commits in a row
- Rebase: the rewritten commits were never tested in the form they now have
The one rule of rebase
Do not rebase commits that other people have already pulled.
Rebase makes new commits and abandons the old ones. If a teammate has built on your old commits, their work now hangs off commits that are no longer in your branch. Sorting that out is painful.
Rebasing your own branch that nobody else uses is fine, and common. A shared branch such as main is never rebased.
Conflicts
Git combines changes by itself when they touch different lines. A conflict is when both sides changed the same lines, and Git will not guess who is right.
It stops and marks the place in the file:
<<<<<<< HEAD
timeout = 30
=======
timeout = 60
>>>>>>> featureThe part above ======= is your current branch. The part below is what is coming in.
Open the file and decide
Keep one side, the other, or write something that combines both. Delete the three marker lines.
Mark it as resolved
git addthe file.Continue
git commitfor a merge, orgit rebase --continuefor a rebase.
If it is going badly, git merge --abort or git rebase --abort puts everything back as it was before you started. See also Undoing Things in Git.
What teams usually do
- Rebase your own branch onto
mainto pick up other people's work and keep your commits together. - Merge into
mainthrough a pull request, so the shared branch is never rewritten. - Many teams squash: the whole branch is combined into a single commit on
main. The history is one commit per feature, and the small work-in-progress commits are dropped.
There is no single right answer. What matters is that a team picks one way and everyone follows it.
Key takeaways
- A branch is a label pointing at one commit. Creating one copies nothing.
- If main has not moved, bringing a branch in is a fast-forward: the label slides along.
- A merge commit has two parents and joins two lines of work without changing either.
- Rebase replays your commits on top of another branch, giving a straight history made of new commits.
- Never rebase commits that others have already pulled.