Synopsis
git merge [--no-ff] [--squash] [--abort] [-s <strategy>] [<branch>]Description
The git merge command integrates changes from one branch into another. By default it produces a "true merge" commit with two parents, preserving the topology of both histories. If the target branch is a strict ancestor of the source, Git fast-forwards by simply moving the branch pointer; pass --no-ff to always record a merge commit.
When the same lines are changed on both sides, Git pauses with a conflict marker. You resolve manually, then git add the files and run git commit (or git merge --continue). To bail out of an in-progress merge, use git merge --abort.
In day-to-day use, git merge integrates closely with shell aliases, editor plugins, and continuous integration. Power users often add aliases that combine flags they always pass, or wrap the command in scripts that enforce team conventions. Output formatting can be customized via Git config — pretty formats, color schemes, and pager behavior are all tunable. When something goes wrong, the first diagnostic step is usually to re-run the command with GIT_TRACE=1 in the environment, which reveals the underlying plumbing calls. For unusual situations, the --help output (git merge --help) opens the full manual page with details on every option, including those rarely used in casual workflows but essential for debugging or scripting at scale.
Understanding how git merge interacts with the rest of Git's data model — the object database, the index, refs, and the working tree — pays dividends. Each command operates on some subset of these pieces, and knowing which it touches helps predict outcomes and recover from mistakes. Reading the official Git documentation alongside hands-on practice in a throwaway repository is the fastest way to internalize the nuances. Most production issues with Git stem from one of three causes: surprising default behavior, partial network operations, or rewriting history that was already shared. A working mental model of git merge's side effects helps avoid all three.
Common Options
| Option | Description |
|---|---|
--no-ff | Always create a merge commit, even when fast-forward is possible. |
--ff-only | Refuse to merge unless fast-forward is possible. |
--squash | Combine the merged history into a single commit on the target branch. |
--abort | Abandon a merge in progress. |
--continue | Resume a merge after resolving conflicts. |
-s <strategy> | Choose merge strategy (ort, recursive, resolve, octopus). |
-X <option> | Pass strategy-specific option (e.g. ours, theirs). |
--no-commit | Stage the merge result but don't commit. |
Examples
git merge feature/login
# Merge feature branch into current branch
git merge --no-ff release/1.2
# Always make a merge commit (preserves topology)
git merge --abort
# Cancel a merge after conflicts arise
git merge -X theirs hotfix
# Auto-resolve conflicts by preferring "their" sideCommon Mistakes
Resolving conflicts in a hurry and forgetting to remove conflict markers (<<<<<<<) leaves broken code committed. Always run a build or tests after resolving. Another pitfall is fast-forwarding silently when you wanted a merge commit for traceability — use --no-ff. Finally, --squash does NOT create a merge commit, so the source branch isn't recorded as a parent.
Related Commands
git rebase, git mergetool, git pull, git cherry-pick