git merge
Combining branches with git merge — fast-forward merges, three-way merges, and merge commits.
What you'll learn
- How to merge a feature branch into main
- The difference between fast-forward and three-way merges
- What a merge commit is and when it is created
- How to abort a merge that goes wrong
Concept
What git merge Does
git merge combines the changes from one branch into another. This is how you integrate a completed feature back into the main branch.
git checkout main
git merge feature-login
You always switch to the branch you want to merge into (the target), then merge the branch you want to merge from (the source).
Fast-Forward Merges
If the target branch has not changed since the source branch was created, Git simply moves the target pointer forward. This is a fast-forward merge — no new commit is created.
Before: A---B---C (main)
\
D---E (feature)
After: A---B---C---D---E (main, feature)
Fast-forward merges keep the history linear and clean. Git does this automatically when possible.
Three-Way Merges
If both branches have new commits, Git must create a merge commit that combines both lines of development. This is a three-way merge — it uses the two branch tips and their common ancestor.
Before: A---B---C (main)
\
D---E (feature)
\
F---G (main moved on)
After: A---B---C---F---G---M (main)
\ /
D---E--- (feature)
M is the merge commit with two parents. This preserves the history of both branches.
Forcing a Merge Commit
Even when a fast-forward is possible, you might want a merge commit to record that a feature was merged:
git merge --no-ff feature-login
--no-ff (no fast-forward) always creates a merge commit. This is useful for feature branch workflows where you want a record of each merged feature.
Resolving Conflicts
If both branches changed the same lines, Git cannot merge automatically and reports a conflict. You must resolve it manually:
git merge feature-login
# CONFLICT (content): Merge conflict in login.js
# Edit the file to resolve conflict markers
# Then:
git add login.js
git commit
Conflict resolution is covered in detail in the merge-conflicts lesson.
Aborting a Merge
If a merge goes wrong or you are not ready to resolve conflicts:
git merge --abort
This cancels the merge and returns your working directory to its pre-merge state. Use this whenever you feel overwhelmed by a conflict — you can always try again.
Merge Strategies
- Merge commit (default) — preserves both histories with a merge commit
- Rebase — replays your commits on top of the target, keeping linear history
- Squash — combines all feature commits into a single commit on the target
Each has trade-offs. The merge-conflicts and git-rebase lessons cover these in depth.
Example
# Create and work on a feature branch
git checkout -b feature-user-profile
echo "profile logic" > profile.js
git add profile.js
git commit -m "feat: add user profile page"
# Switch to main and merge the feature
git checkout main
git merge feature-user-profile
# If main also moved forward, you get a three-way merge
# Let's simulate that:
git checkout -b another-feature
echo "more" > more.js
git commit -am "feat: add more"
git checkout main
echo "main change" >> README.md
git commit -am "docs: update README"
git merge another-feature # creates a merge commit
# Force a merge commit even when fast-forward is possible
git merge --no-ff feature-user-profile
# If a conflict occurs, abort and try again later
git merge conflicting-branch
git merge --abort
# After resolving a conflict manually:
git add resolved-file.js
git commit # completes the merge
# Delete the merged branch (safe now)
git branch -d feature-user-profile
Shows a basic merge, a three-way merge when both branches moved, forcing a merge commit with --no-ff, aborting a problematic merge, completing a merge after resolving conflicts, and cleaning up the merged branch. The merge --abort command is your safety net.
Try it
- Code Diff
Compare branches before merging to preview what will change.
- CI/CD YAML Generator
Merges to main often trigger deployment pipelines.
Common mistakes
The mistake
Merging in the wrong direction — merging main into the feature branch
The fix
Always switch to the target branch (e.g., main) first, then merge the source branch (e.g., feature). The command is: git checkout main && git merge feature. Merging main into feature updates the feature branch, which is usually not what you want.
The mistake
Panicking when a merge conflict appears and closing the terminal
The fix
Conflicts are normal. If you are not ready to resolve them, run git merge --abort to cancel and return to the pre-merge state. Take your time, read the conflict markers, resolve them in your editor, then git add and git commit.
Related Resources
Related Cheatsheets
- Git Cheatsheet
merge, merge --no-ff, and merge --abort commands.
Practice git merge
10 exercises
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.