Skip to main content

​
Synopsis

git merge [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
          [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]
          [--[no-]allow-unrelated-histories]
          [--[no-]rerere-autoupdate] [-m <msg>] [<commit>...]
git merge (--continue | --abort | --quit)

​
Description

Incorporates changes from the named commits (since the time their histories diverged from the current branch) into the current branch. This command is used by git pull to incorporate changes from another repository and can be used by hand to merge changes from one branch into another. For example, assume the following history exists with the current branch being master: 
          A---B---C topic
         /
    D---E---F---G master
Then git merge topic will replay the changes made on the topic branch since it diverged from master (at E) and record the result in a new merge commit: 
          A---B---C topic
         /         \
    D---E---F---G---H master

​
Common Usage

1

Merge a feature branch

First, switch to the branch you want to merge into:
git checkout main
Then merge the feature branch:
git merge feature-branch
2

Handle merge conflicts (if any)

If conflicts occur, Git will mark them in the affected files:
# View conflicted files
git status

# Edit files to resolve conflicts
# Then mark them as resolved
git add resolved-file.txt
3

Complete the merge

After resolving all conflicts:
git merge --continue
Or if you used manual commits:
git commit

​
Options

Perform the merge but don’t create a merge commit automatically. This allows you to inspect and further tweak the merge result before committing.
git merge --no-commit feature-branch
Produce the working tree and index state as if a real merge happened, but do not actually make a commit or move the HEAD. This allows you to create a single commit on top of the current branch.
git merge --squash feature-branch
git commit -m "Squashed feature-branch"
Create a merge commit even when the merge resolves as a fast-forward. This is useful to maintain a clear history of feature branch merges.
git merge --no-ff feature-branch
Refuse to merge unless the current HEAD is already up to date or the merge can be resolved as a fast-forward.
git merge --ff-only upstream/main
Set the commit message for the merge commit.
git merge -m "Merge feature: Add user authentication" feature-auth
Use the given merge strategy. Common strategies include:
  • ort (default) - Three-way merge algorithm
  • recursive - Three-way merge (legacy)
  • resolve - Three-way merge using 3-way merge algorithm
  • octopus - For merging more than two branches
  • ours - Merge but discard changes from other branch
  • subtree - Modified recursive strategy
git merge -s ours obsolete-branch
Pass merge strategy-specific option. Common options:
  • ours - Auto-resolve conflicts by favoring our version
  • theirs - Auto-resolve conflicts by favoring their version
  • ignore-space-change - Ignore whitespace changes
git merge -X theirs feature-branch
Abort the current merge and try to reconstruct the pre-merge state.
git merge --abort
If there were uncommitted changes when the merge started, git merge --abort may not be able to reconstruct all of them.
After resolving conflicts, continue the merge process.
git merge --continue
Forget about the current merge in progress, leaving the index and working tree as-is.
git merge --quit
Allow merging histories that have no common ancestor. This is useful when merging two independent projects.
git merge --allow-unrelated-histories other-project/main

​
Examples

​
Basic merge

# Merge fixes and enhancements branches (octopus merge)
git merge fixes enhancements

​
Using merge strategies

# Merge but keep our version in case of conflicts
git merge -s ours obsolete

# Merge and auto-resolve conflicts by preferring their changes
git merge -X theirs feature-branch

​
Merge without auto-commit

# Merge but don't commit yet
git merge --no-commit maint

# Make additional changes
edit version.txt
git add version.txt

# Now commit
git commit
You should refrain from abusing the --no-commit option to sneak substantial changes into a merge commit. Small fixups like bumping release/version name would be acceptable.

​
Squash merge

# Squash all commits from feature branch into one
git merge --squash feature-branch
git commit -m "Add complete authentication feature"

​
Fast-Forward Merge

Often the current branch head is an ancestor of the named commit. This is the most common case when you haven’t made any local changes: 
Before:           After (fast-forward):
                  
A---B---C main    A---B---C---D main
         \                     
          D feature
In this case, Git simply moves the pointer forward. No merge commit is created. To force creation of a merge commit even in fast-forward case: 
git merge --no-ff feature-branch

​
How Conflicts Are Presented

When both sides change the same area of a file, Git cannot automatically resolve the conflict: 
Here are lines that are either unchanged or cleanly resolved.
<<<<<<< yours:sample.txt
Conflict resolution is hard;
let's go shopping.
=======
Git makes conflict resolution easy.
>>>>>>> theirs:sample.txt
And here is another line that is cleanly resolved.
You can configure the conflict style: 
# Use diff3 style to also show the original
git config merge.conflictStyle diff3

# Or use zdiff3 (more concise)
git config merge.conflictStyle zdiff3

​
How to Resolve Conflicts

1

Identify conflicted files

git status
2

View the conflicts

# See three-way diff
git diff

# See changes made so far
git diff AUTO_MERGE

# Use a merge tool
git mergetool
3

Edit and resolve

Open conflicted files in your editor and resolve the conflicts by:
  • Choosing one version
  • Combining both versions
  • Writing something completely different
Remove the conflict markers (<<<<<<<, =======, >>>>>>>)
4

Mark as resolved

git add resolved-file.txt
5

Complete the merge

git merge --continue
Or simply:
git commit

​
Tools for resolving conflicts

# Launch graphical merge tool
git mergetool

# View three-way diff
git diff

# Show changes from both branches
git log --merge -p <path>

# View versions from each side
git show :1:filename  # common ancestor
git show :2:filename  # HEAD version
git show :3:filename  # MERGE_HEAD version

​
Pre-Merge Checks

Before merging, you should:
  • Commit or stash your local changes
  • Ensure your working tree is clean
  • Avoid having uncommitted changes that overlap with files being merged
git merge will refuse to proceed if:
  • Local uncommitted changes overlap with files being updated
  • The index differs from HEAD (unless specific merge strategies allow it)

Build docs developers (and LLMs) love

Get started for freeTalk to us