Branches, merging and conflicts
A branch lets you try an idea without touching the stable version of the project. When the idea works, you integrate it with git merge. If both branches changed the same lines, Git asks you to decide: that is a conflict.
In this lesson you will learn:
- What a branch is and what
HEADis. - How to create, list, switch and delete branches with
git branchandgit switch. - How to view history as a graph with
git log --oneline --graph --all. - The difference between a fast-forward merge and a merge commit.
- How to read conflict markers, resolve a conflict or cancel the merge.
Everything happens on your computer: no server is needed.
What a branch is
A branch is a movable pointer to a commit. It is not a copy of the files: it is just a name (for example main) that points to the latest commit of a line of work. Every time you commit on that branch, the pointer moves forward to the new commit.
HEAD tells you where you are. It normally points to a branch (HEAD -> main), which is why your new commits move that branch forward.
In the Undoing changes lesson you used git switch --detach <hash>: there HEAD pointed directly at a commit, with no branch. That is detached HEAD. With branches, HEAD points to a name again, one that moves with you.
Setting up the practice repository
Every example in this lesson continues from the previous one in the same repository. Create it in an empty folder:
mkdir project
cd project
git init
Create greeting.txt with this content:
Hello world
git add greeting.txt
git commit -m "Add initial greeting"
[main (root-commit) 84e98ce] Add initial greeting
1 file changed, 1 insertion(+)
create mode 100644 greeting.txt
The hashes in your terminal will be different: every commit has its own.
Listing, creating and switching branches
Listing branches
git branch
* main
The asterisk marks the current branch, the one HEAD points to.
Creating a branch and switching to it
git switch -c farewell
Switched to a new branch 'farewell'
git switch -c <name> creates the branch at the current commit and switches to it. Now git branch shows:
* farewell
main
If the branch already exists, you switch to it without -c:
git switch main
When you switch branches, Git replaces the files in your folder with those of the commit the new branch points to. Commit your changes before switching: if you have uncommitted changes that clash with the other branch, Git refuses to switch so you do not lose them.
Viewing history as a graph
git log --oneline only shows the current branch. To see every branch and how they split and join:
git log --oneline --graph --all
--graphdraws the lines of each branch on the left.--allincludes every branch, not just the current one.- The parentheses show which commit each branch and
HEADpoint to.
You will use it after every step in this lesson.
Fast-forward merge
Stay on the farewell branch (go back with git switch farewell if you switched to main). Create farewell.txt:
See you later
git add farewell.txt
git commit -m "Add farewell"
git switch main
On main the file farewell.txt does not exist: that branch still points to the previous commit. The graph shows it:
git log --oneline --graph --all
* 1c21b09 (farewell) Add farewell
* 84e98ce (HEAD -> main) Add initial greeting
main has not moved since you created farewell. To integrate, you stand on the branch that receives the changes and merge the other one:
git merge farewell
Updating 84e98ce..1c21b09
Fast-forward
farewell.txt | 1 +
1 file changed, 1 insertion(+)
create mode 100644 farewell.txt
Since main had no commits of its own, Git does not need to combine anything: it just moves the main pointer forward to the commit of farewell. That is a fast-forward, and it creates no new commit.
* 1c21b09 (HEAD -> main, farewell) Add farewell
* 84e98ce Add initial greeting
main did not move, git merge farewell only moves the main pointer from A to B.Merge with a merge commit
Now make both branches move forward, each in a different file. Create the author branch and add author.txt:
git switch -c author
Author: Ana
git add author.txt
git commit -m "Add author"
git switch main
On main, change farewell.txt so it reads:
See you later, see you soon
git add farewell.txt
git commit -m "Improve the farewell"
git log --oneline --graph --all
* c236346 (author) Add author
| * e4fe6bd (HEAD -> main) Improve the farewell
|/
* 1c21b09 Add farewell
* 84e98ce Add initial greeting
The branches have diverged: each one has a commit the other does not. Moving a pointer is no longer enough. Merge:
git merge author
Git opens your editor with the message Merge branch 'author'. Accept it: save and close the editor. Git replies:
Merge made by the 'ort' strategy.
author.txt | 1 +
1 file changed, 1 insertion(+)
create mode 100644 author.txt
Git compares both tips with their common ancestor (1c21b09), combines the changes and creates a merge commit: a commit with two parents. That is why it is called a three-way merge.
* a73905e (HEAD -> main) Merge branch 'author'
|\
| * c236346 (author) Add author
* | e4fe6bd Improve the farewell
|/
* 1c21b09 Add farewell
* 84e98ce Add initial greeting
main and D “Add author” on author. Both branches moved forward in different files, so git merge author creates M with no conflicts.Deleting a merged branch
Once a branch is integrated, its name is no longer needed: the commits stay in main.
git branch -d farewell
git branch -d author
Deleted branch farewell (was 1c21b09).
Deleted branch author (was c236346).
git branch -d refuses to delete a branch that has unmerged commits:
error: the branch 'test' is not fully merged
Git suggests git branch -D to force it. Use it only if you really want to discard those commits.
Conflicts
When a conflict happens
Git only combines changes that do not overlap: different files, or different parts of the same file. There is a conflict when both branches changed the same lines differently since the common ancestor. Git does not guess which version is right: it stops the merge and asks you.
Causing a conflict
Stay in the same repository, on main. Right now greeting.txt reads Hello world. Create a new branch and change that line:
git switch -c formal-greeting
Edit greeting.txt so it reads:
Good morning, world
git add greeting.txt
git commit -m "Use a formal greeting"
git switch main
On main, greeting.txt reads Hello world again. Change the same line in a different way:
Hello, whole world
git add greeting.txt
git commit -m "Expand the greeting"
git merge formal-greeting
Auto-merging greeting.txt
CONFLICT (content): Merge conflict in greeting.txt
Automatic merge failed; fix conflicts and then commit the result.
The merge is halfway done. git status tells you which files are waiting for a decision:
On branch main
You have unmerged paths.
(fix conflicts and run "git commit")
(use "git merge --abort" to abort the merge)
Unmerged paths:
(use "git add <file>..." to mark resolution)
both modified: greeting.txt
Reading the markers
Open greeting.txt:
<<<<<<< HEAD
Hello, whole world
=======
Good morning, world
>>>>>>> formal-greeting
<<<<<<< HEADopens the version of your current branch (main).=======separates the two versions.>>>>>>> formal-greetingcloses the version of the branch you are merging.
greeting.txt since the common ancestor, so Git writes both versions between markers and waits for your decision.Cancelling the merge: git merge --abort
If you do not want to resolve it now, go back to the state before git merge:
git merge --abort
git status
On branch main
nothing to commit, working tree clean
greeting.txt reads Hello, whole world again. To continue the example, try the merge again:
git merge formal-greeting
You get the same CONFLICT (content) as before.
Resolving the conflict
- Decide the final content. It can be one version, the other or a combination.
- Delete the three marker lines (
<<<<<<<,=======,>>>>>>>). - Save the file.
In this example we combine both ideas. greeting.txt ends up like this:
Good morning, whole world
Mark the file as resolved with git add:
git add greeting.txt
git status
On branch main
All conflicts fixed but you are still merging.
(use "git commit" to conclude merge)
Finishing the merge
git commit
Git opens the editor with the message Merge branch 'formal-greeting'. Accept it: save and close.
[main 5f1ebe6] Merge branch 'formal-greeting'
At this point git merge --continue does the same as git commit: it also opens the editor with the default message. Use whichever you prefer.
git log --oneline --graph --all
git branch -d formal-greeting
* 5f1ebe6 (HEAD -> main) Merge branch 'formal-greeting'
|\
| * c93e3d6 (formal-greeting) Use a formal greeting
* | 1007196 Expand the greeting
|/
* a73905e Merge branch 'author'
...
What Git can and cannot recover
- Anything already in a commit can almost always be recovered. Even if you delete a branch or get a merge wrong, the commits still exist for a while and
git reflogshows their hashes (you saw it in Undoing changes). - Anything you never committed cannot be recovered.
git restoreandgit reset --harddiscard uncommitted changes, and Git keeps no copy of them.
So: commit before switching branches or merging.
Tips
- Create one branch per idea or task, with a name that describes it.
- Make small commits: conflicts are shorter and easier to read.
- Merge often: the more two branches diverge, the more conflicts they pile up.
- Read the whole conflict before editing, and check the result with
git diff --stagedbefore committing. - Common mistakes: committing with markers still in the file, or deleting the whole file instead of the conflicting lines.
Summary
| I want to… | Command |
|---|---|
| See the branches | git branch |
| Create a branch and switch to it | git switch -c <branch> |
| Switch to an existing branch | git switch <branch> |
| See every branch as a graph | git log --oneline --graph --all |
| Integrate another branch into the current one | git merge <branch> |
| Mark a conflict as resolved | git add <file> |
| Finish the merge | git commit or git merge --continue |
| Cancel a merge with conflicts | git merge --abort |
| Delete an already merged branch | git branch -d <branch> |
Practice exercises
Exercise 1: a fast-forward merge
In a new repository with one commit on main, create the contact branch, add contact.txt in a commit and merge it into main. Check that Git replies Fast-forward and delete the branch.
Show solution
git switch -c contact
# Create contact.txt with any text
git add contact.txt
git commit -m "Add contact"
git switch main
git merge contact
git log --oneline --graph --all
git branch -d contact
git merge shows Fast-forward because main had no new commits: only the pointer moved.
Exercise 2: a merge commit without conflicts
Create the colors branch and add colors.txt in a commit. Go back to main and, before merging, make a commit that changes another file. Merge colors and look at the graph.
Show solution
git switch -c colors
# Create colors.txt
git add colors.txt
git commit -m "Add colors"
git switch main
# Change greeting.txt
git add greeting.txt
git commit -m "Update the greeting"
git merge colors
# Accept the "Merge branch 'colors'" message in the editor
git log --oneline --graph --all
Git replies Merge made by the 'ort' strategy. and the graph shows a commit with two lines reaching it: the merge commit.
Exercise 3: cancelling and resolving a conflict
Create the title branch and change the first line of greeting.txt. On main, change that same line in a different way. Merge, cancel with git merge --abort, merge again and this time resolve the conflict, finishing with git merge --continue.
Show solution
git switch -c title
# Change the first line of greeting.txt
git add greeting.txt
git commit -m "Change the greeting on title"
git switch main
# Change the same line with different text
git add greeting.txt
git commit -m "Change the greeting on main"
git merge title
# CONFLICT (content): Merge conflict in greeting.txt
git merge --abort
git status
# nothing to commit, working tree clean
git merge title
# Keep the final content and delete the markers
git add greeting.txt
git merge --continue
git branch -d title
Exercise 4: an unmerged branch
Create the draft branch, make a commit on it, go back to main and try to delete it with git branch -d. What does Git reply and why? How would you delete it without losing that commit?
Show solution
Git replies error: the branch 'draft' is not fully merged, because the commit on draft is not in main: if you delete the branch, no name points to that commit. To keep it, merge first and then delete:
git merge draft
git branch -d draft
If you really want to discard the work, git branch -D draft deletes it anyway.