What you can do after this lesson
You will combine the work of two branches, recognise the two kinds of merge Git can make, and read the history afterwards. Conflicts, the thing everyone worries about, get their own lesson next. Here we cover the clean cases first.
The direction of a merge
git merge takes another branch and brings its commits into the branch you are currently on. So the order is always: switch to the branch that should receive the work, then merge the other one in.
git switch main
git merge hours-updateMixing this up is a classic beginner slip. If you merge main into your feature branch by accident, you are not harming anything, but you are updating the feature branch rather than delivering it. Check git branch before merging.
Fast-forward: the simple case
Suppose hours-update branched from main and main has not changed since. History is a straight line, with main just behind the tip of hours-update. Git does not need to combine anything. It slides the main label forward:
git merge hours-updateUpdating 594fee7..788946b
Fast-forward
hours.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)git log --oneline --graph --decorate* 788946b (HEAD -> main, hours-update) Extend hours to 6
* 594fee7 Add opening hours
* e6583be Add home pageNo new commit was created. Both labels now point at the same commit, and the history is one clean line. Hashes in your repository differ.
Once a branch is merged, remove its label. -d succeeds because nothing is lost:
git branch -d hours-updateDeleted branch hours-update (was 788946b).A true merge: both sides have moved
Now the realistic case. You create a contact branch and commit a new page there. Meanwhile someone commits a change to main:
git switch -c contact
echo "Call us." > contact.txt
git add . && git commit -m "Add contact page"
git switch main
echo "Closed on public holidays." >> home.txt
git commit -am "Note holiday closures"
git merge contact -m "Merge branch contact"Merge made by the 'ort' strategy.
contact.txt | 1 +
1 file changed, 1 insertion(+)
create mode 100644 contact.txtThe two branches changed different files, so Git combined them automatically. ('ort' is the name of Git's default merge algorithm; you do not need to do anything with it.) Look at the history:
git log --oneline --graph --decorate* dad2dd1 (HEAD -> main) Merge branch contact
|\
| * 74d0a6a (contact) Add contact page
* | 35fdfdf Note holiday closures
|/
* 788946b Extend hours to 6
* 594fee7 Add opening hours
* e6583be Add home pageThe graph forks and rejoins. The new commit dad2dd1 is a merge commit with two parents: the previous tip of main and the tip of contact. It is a snapshot of everything combined. Merges are a normal, honest record that two lines of work came together.
Forcing a merge commit with --no-ff
Even when a fast-forward is possible, --no-ff creates a merge commit anyway:
git merge --no-ff contactSome teams do this on purpose. The merge commit marks where a feature branch started and ended, so a reviewer can look at a group of commits as a unit, and a whole feature can be undone by reverting a single merge commit. Others prefer a straight line. Both are valid; agree on one as a team. You can make --no-ff the default for a repository by setting merge.ff to false.
Checking before you merge
A few habits prevent surprises:
- Commit or stash your work first. Run
git status; it should be clean. - See what you are about to bring in:
git log --oneline main..contactlists commits oncontactthatmainlacks. - Review the difference:
git diff main...contactshows the changescontactintroduced since the branches diverged.
If a merge goes wrong before you commit it, git merge --abort returns you to where you were. If it has been committed and you regret it, and you have not shared it, git reset --hard ORIG_HEAD rewinds to before the merge, as the recovery lesson shows.
Reading the result
After any merge, spend a moment confirming it did what you expected. Run git log --oneline --graph -5 to see the shape, and open the files that both sides touched. A merge that Git completes without complaint is textually clean, but that does not prove the program still works: two changes that are fine alone can still clash in meaning, for example when one branch renames a function that the other branch starts calling. Running the project's tests or opening the page after a merge is the real check.
Common mistakes
- Merging in the wrong direction. Switch to the receiver first.
- Merging with a dirty working tree. Commit or stash first so any problem is easy to untangle.
- Not deleting merged branches. They clutter the list and confuse newcomers.
- Assuming merge commits are mistakes. They are normal. A history with merges is not wrong; it records what happened.
- Merging before pulling. Update the receiving branch from the remote before merging into it, to avoid avoidable conflicts later.
Exercise
- Create
feature-afrommain, add a file, and commit. Merge it intomain. Was it a fast-forward? - Create
feature-b, commit on it, then return tomainand make a different commit before mergingfeature-b. What kind of merge is it now? - View the graph and find the merge commit's two parents.
Show one possible answer
git switch -c feature-a
echo a > a.txt && git add a.txt && git commit -m "Add a"
git switch main && git merge feature-a
git switch -c feature-b
echo b > b.txt && git add b.txt && git commit -m "Add b"
git switch main
echo m > m.txt && git add m.txt && git commit -m "Add m on main"
git merge feature-b -m "Merge feature-b"
git log --oneline --graphThe first merge is a fast-forward. The second creates a merge commit because main moved on. git show --format=%p HEAD prints both parent hashes.
Key points
- git merge <branch> brings the commits of that branch into the branch you are on.
- If the current branch has not moved since the other branch split off, Git simply slides the label forward, a fast-forward with no new commit.
- If both branches have new commits, Git creates a merge commit with two parents.
- git merge --no-ff forces a merge commit even when a fast-forward is possible, which records that a branch existed.
- Always switch to the receiving branch first, then merge; afterwards delete the merged branch.