Skip to content

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

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 Cheatsheets

Practice git merge

10 exercises

Practice git merge

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors