git merge Tutorial

The short version

git merge integrates another branch into the current branch without requiring you to rewrite existing commits.

When it is a good fit

• merging a feature branch back into main
• preserving the real branch integration history
• integrating shared branches without rewriting history

Two common outcomes

Fast-forward

If the current branch has not diverged, Git can simply move the branch pointer forward.

Merge commit

If both branches moved forward independently, Git creates a merge commit that records where the histories joined.

If you compare this picture with the rebase diagram, the key difference is that merge preserves the branch shape and adds a new integration point instead of replaying commits into a new linear sequence.

Basic workflow

git checkout main
git fetch origin
git merge feature/login

Common flags and strategies

--ff-only

Only allow fast-forward merges. If the histories diverged, the merge fails instead of creating a merge commit.

git merge --ff-only origin/main

--no-ff

Create a merge commit even when a fast-forward would be possible. Teams sometimes use this to preserve the explicit branch boundary.

git merge --no-ff feature/login

Handling conflicts

git status
# resolve conflicts
git add <resolved-files>
git merge --continue

Abort if needed:

git merge --abort

When merge is a better choice than rebase

• the branch is already shared
• you want to preserve the integration graph
• your team values non-rewritten collaboration history

A practical decision rule

If your question is “Should I integrate this whole branch history here?”, merge is usually the more natural tool.

If your question is “Should I rewrite how my branch history is expressed?”, that usually points more toward rebase.

What problem this command solves in a workflow

git merge directly affects history shape, ref position, or relationships between commits. The first decision is whether you are organizing private local history or touching history that is already shared with others.

Typical use cases

• Use git merge when integrating branches, undoing changes, selecting commits, or reshaping a sequence of commits.
• Put git merge inside a “backup first, mutate second, verify last” flow so higher-risk history operations stay recoverable.
• Use git merge to understand ancestry, recovery paths, and commit causality during conflict resolution or post-incident analysis.

Diagram view

Special cases and boundaries

• The most expensive failure mode in history commands is rewriting or moving commits that other people already depend on.
• If the operation might affect team flow, run git status, git log --oneline --graph, and git reflog first so the recovery path is visible.
• When in doubt, create a backup branch before continuing so you preserve an obvious way back.
• During conflicts, do not only inspect files. Reconfirm which side of history the merge is supposed to preserve.

Try it yourself

git switch -c lab/merge-demo
# create a feature branch and make one commit on each side