Appearance
Merging Branches
You have two branches and you want to combine their work. Merging is how Git brings changes from one branch into another.
Scenario
You have a main branch with your stable code. You created a feature branch to add a search bar. The feature is done. Now you want to pull it into main.
main: A---B---C
\
feature: D---EWhat is a merge?
A merge combines the histories of two branches. Git finds the point where the branches diverged (the "merge base"), then applies the changes from the source branch on top of the target branch. The result is a new "merge commit" that has two parents.
main: A---B---C---F
\ /
feature: D---EF is the merge commit. Its parents are C and E. The work from both branches now lives together.
Step by step
1. Switch to the branch you want to merge INTO
This is always the target. If you want feature merged into main, you stand on main:
bash
git checkout main
# or
git switch main2. Run the merge
bash
git merge feature3. Git reports what happened
If there are no conflicts, you see:
Updating a1b2c3d..e4f5g6h
Fast-forward
search.html | 25 +++++++++++++++++++++++++
1 file changed, 25 insertions(+)Or, for a 3-way merge:
Merge made by the 'ort' strategy.
search.html | 25 +++++++++++++++++++++++++
1 file changed, 25 insertions(+)4. Verify the result
bash
git log --oneline --graph --allYou see both parent branches and the merge commit connecting them.
Fast-forward vs 3-way merge
When the target branch has not moved since you created the feature branch, Git can do a fast-forward: it just moves the branch pointer forward. No merge commit needed.
Before: main -> B
feature -> D -> C -> B
After: main -> D -> C -> B
feature -> D -> C -> BWhen the target has moved (other commits happened on main), Git does a 3-way merge and creates a merge commit.
You can force a merge commit even on a fast-forward:
bash
git merge --no-ff featureUse --no-ff when you want to preserve the branch history, even if a fast-forward is possible.
Resolving a conflict
Conflicts happen when both branches changed the same line of the same file in different ways. Git cannot decide which version is correct.
When a conflict occurs, the merge pauses:
Auto-merging index.html
CONFLICT (content): Merge conflict in index.html
Automatic merge failed; fix conflicts and then commit the result.What you see in the conflicted file
html
<<<<<<< HEAD
<title>My Site v2</title>
=======
<title>My Site with Search</title>
>>>>>>> feature<<<<<<< HEAD— your changes (onmain)=======— divider>>>>>>> feature— their changes (on thefeaturebranch)
How to resolve
- Open the file in your editor.
- Delete the conflict markers (
<<<<<<<,=======,>>>>>>>). - Keep the correct version. You might combine both, or pick one, or write something new.
- Save the file.
- Mark it as resolved:
bash
git add index.html- Complete the merge:
bash
git commitGit opens your editor with a pre-filled merge commit message. Save and close.
Verify the conflict was resolved
bash
git log --oneline --graph --allThe merge commit now exists in the history.
Aborting a merge
If a merge goes wrong and you want to start over:
bash
git merge --abortThis undoes the merge and returns your branch to its previous state.
What's happening here
| Step | What Git does |
|---|---|
git merge feature | Git finds the merge base (common ancestor), computes the diff from base to HEAD and from base to feature, then combines them |
| Conflict markers | Git cannot resolve the conflict, so it marks both versions in the file for you |
git add after conflict | You tell Git the file is resolved. Git stages the fixed version |
git commit after conflict | Git creates the merge commit with two parents |
git merge --abort | Git restores the index and working tree to their pre-merge state |
Common mistakes
| Mistake | What happens | How to fix |
|---|---|---|
| Merging while you have uncommitted changes | Git refuses (stash first) | git stash then merge, then git stash pop |
| Editing conflict markers into the file | Syntax errors | Remove all <<<<<<<, =======, >>>>>>> lines before saving |
Forgetting git add after resolving | Git thinks the conflict is still active | Run git status to see what's staged |
| Committing without resolving all conflicts | Git blocks the commit | Run git status and look for "both modified" |
| Merging the wrong way (feature into main from feature branch) | Same outcome, but confusing | Always merge INTO the target branch |
Quick reference
bash
# Merge a branch into the current branch
git merge <branch-name>
# Merge with a merge commit (no fast-forward)
git merge --no-ff <branch-name>
# Abort a conflicted merge
git merge --abort
# After resolving conflicts, mark as done
git add <resolved-file>
git commit
# See what files have conflicts
git statusNext steps
- Understanding Branches — how branches work in more detail
- Viewing History (git log) — reading the commit graph
- Working with Remotes — pushing and pulling from shared repos