Branches are only useful if their work comes back together. Merging takes the commits of one branch and integrates them into another. Most merges are automatic; the interesting part is understanding what Git does, and staying calm when it asks you to resolve a conflict.
Merging a branch
You always merge into the branch you are on. To bring feature/search into main:
$ git switch main
$ git merge feature/search
What happens next depends on the shape of the history.
Fast-forward merge
If main has not moved since the feature branch was created, there is nothing to combine. Git simply moves the main pointer forward to the tip of the feature branch:
before: a1f3 <- 5d1e (main)
\
c42d <- e71b (feature/search)
after: a1f3 <- 5d1e <- c42d <- e71b (main, feature/search)
$ git merge feature/search
Updating 5d1e0a2..e71b3a0
Fast-forward
search.js | 12 ++++++++++++
1 file changed, 12 insertions(+)
No new commit is created and history stays a straight line.
Three-way merge
If both branches got new commits, Git finds their merge base (the last commit they share), compares each branch with it and combines both sets of changes into a new merge commit with two parents:
c42d <- e71b (feature/search)
/ \
5d1e <- 7aa0 <- 90bd <- m3f1 (main, merge commit)
$ git merge feature/search
Merge made by the 'ort' strategy.
search.js | 12 ++++++++++++
1 file changed, 12 insertions(+)
$ git log --oneline --graph -5
* m3f1c20 (HEAD -> main) Merge branch 'feature/search'
|\
| * e71b3a0 Rank search results by date
| * c42d9e1 Add search stub
* | 90bd114 Bump Node.js to 24
|/
* 5d1e0a2 Add README and API entry point
ort is Git’s default merge strategy since version 2.34. Git 2.56 also made finding the merge base much faster in large repositories with many branches.
You can control the shape:
| Option | Effect |
|---|---|
--ff-only | Merge only if a fast-forward is possible, otherwise fail |
--no-ff | Always create a merge commit, even when fast-forward is possible |
--squash | Stage the combined changes without committing or recording a merge |
--no-ff keeps a visible “this feature was merged here” commit, which some teams like for reading history. --ff-only is a good setting for git pull when you never commit directly to main.
Why conflicts happen
A conflict happens when both branches changed the same lines of the same file differently, or one branch edited a file the other deleted. Git cannot know which version is right, so it stops and asks you.
Imagine main changed the port to 8081 while feature/search changed it to 9090:
$ git merge feature/search
Auto-merging server.js
CONFLICT (content): Merge conflict in server.js
Automatic merge failed; fix conflicts and then commit the result.
$ git status -s
UU server.js
UU means “unmerged, changed on both sides”. Every other file was merged and staged automatically.
Reading conflict markers
Open the file and you find the conflicting part wrapped in markers. With merge.conflictStyle set to zdiff3 (lesson 2), Git also shows what the line looked like before either change, which makes the right answer much easier to see:
<<<<<<< HEAD
const port = 8081;
||||||| merge base
const port = 8080;
=======
const port = 9090;
>>>>>>> feature/search
- From
<<<<<<< HEADto the line of pipes: your branch (main). - From the line of pipes to
=======: the common ancestor, how the lines looked before either change. - From
=======to>>>>>>>: the branch being merged.
Here the ancestor shows that both sides changed 8080. Talk to the author of the feature if needed, decide on the correct value, and edit the file so it contains only the final code, with every marker removed:
const port = 9090;
Finishing the merge
Mark the file as resolved by staging it, then commit:
$ git add server.js
$ git commit # Git prepares a "Merge branch ..." message
Git 2.56 added a safer way to do the staging step. git add --resolved stages only the files that were in conflict, and first checks them for leftover conflict markers. If it finds any, it stages nothing and tells you which files still need work:
$ git add --resolved
$ git commit
This prevents a classic accident: git add . happily stages a file that still contains <<<<<<< lines, and broken code gets committed. --resolved ignores files that were never in conflict and cannot be combined with -u or -A.
Tip: git diff during a conflict shows only the unresolved parts. git diff --name-only --diff-filter=U lists the files still in conflict.
Getting out of a merge
If the conflict is bigger than expected or you merged the wrong branch, go back to exactly where you were before:
$ git merge --abort
You can also take one whole side of a file without editing it:
$ git checkout --ours server.js # keep main's version
$ git checkout --theirs server.js # keep the incoming branch's version
Remembering resolutions with rerere
If you set rerere.enabled true (lesson 2), Git records how you resolved each conflict. When the same conflict appears again, for example while re-merging or rebasing, Git resolves it for you the same way. You still review and stage the result.
Squash merges
git merge --squash feature/search stages all the changes of the branch as one set, without a merge commit, and you commit them yourself as a single commit. Hosting services offer the same as “Squash and merge” on pull requests. It keeps main tidy, one commit per feature, at the cost of losing the individual commits of the branch. After a squash merge, git branch -d reports the branch as unmerged, because its commits are not in main; delete it with -D.
Quick reference
| Task | Command |
|---|---|
| Merge a branch into the current one | git merge <branch> |
| Only if fast-forward | git merge --ff-only <branch> |
| Always create a merge commit | git merge --no-ff <branch> |
| Combine into one staged change | git merge --squash <branch> |
| List files in conflict | git diff --name-only --diff-filter=U |
| Stage resolved files safely (2.56) | git add --resolved |
| Cancel the merge | git merge --abort |
| Take one side of a file | git checkout --ours / --theirs <file> |
Exercise
main has not received any commits since you created feature/search. What does git merge feature/search on main do?
Show answer
Answer: A. When the target branch is an ancestor of the incoming branch, Git fast-forwards: it only moves the pointer. A merge commit is created only for diverged histories or with –no-ff.
Exercise
You fixed two of the three conflicted files and run git add –resolved. One file still contains a <<<<<<< marker. What happens?
Show answer
Answer: D. git add –resolved (Git 2.56) is all or nothing: it checks every conflicted file for markers before staging, and if any remain it leaves the index unchanged so you cannot commit a half-resolved merge.
Exercise
Halfway through a large conflict you realise you merged the wrong branch. How do you return to the state before the merge?
Show answer
Answer: B. git merge –abort throws away the merge in progress and restores the branch and working tree to how they were before you ran git merge. git revert works on finished commits, not on a merge in progress.
Key takeaways
- You merge into the current branch; Git fast-forwards when possible and creates a merge commit when histories diverged.
- Conflicts mean both sides changed the same lines; Git merges everything else automatically.
zdiff3conflict style shows the original lines between the two versions, which makes decisions easier.- Remove every marker, stage the file (or use
git add --resolvedfrom Git 2.56) and commit. git merge --abortis the emergency exit;--squashturns a branch into one commit.
FAQ
Are merge conflicts a sign that something went wrong?
No. They are normal when two people work on the same area. Small, short-lived branches and frequent merges from main keep them small and rare.
What is the difference between merge and rebase?
Both integrate changes. Merge keeps history as it happened and adds a merge commit. Rebase rewrites your branch’s commits on top of the other branch for a straight history. Lesson 6 compares them in detail.
Can I use a graphical tool to resolve conflicts?
Yes. VS Code, JetBrains IDEs and many others show both sides with buttons to accept either. Run git mergetool to open the one configured in merge.tool. The result is the same: a file without markers that you stage.
Why does Git say “refusing to merge unrelated histories”?
The two branches share no common commit, often because a repository was created on the server with a README and locally with git init. If you really want to join them, add --allow-unrelated-histories once.
Should my team use squash merges?
It depends on taste. Squash keeps main to one commit per pull request, which is easy to read and revert. Regular merges keep every commit, which helps git bisect and tells the detailed story. Pick one rule and enforce it in the repository settings.