Introduction

If you want all the changes from a branch to land as one commit, what you usually want is a squash merge. That keeps the final branch history compact by combining the net effect of many feature-branch commits into one new commit on the target branch.

What a Squash Merge Does

A regular merge preserves the original branch history. A squash merge takes all the changes introduced by the feature branch and stages them as one combined change on the current branch.

git checkout main
git merge --squash feature-branch
git commit -m "Add feature X"

After this, main gets one new commit containing the combined result of feature-branch, but it does not get the original feature-branch commit structure.

Why It Is Not the Same as a Normal Merge

With a normal merge commit, Git records both parent histories. With --squash, Git applies the diff but does not create a real merge commit connecting the histories.

That means:

• the target branch history stays compact
• the individual branch commits are not preserved there
• future merges may not see the squash commit as an actual merge relationship

This last point matters if the same branch will continue evolving after the squash merge.

When Squash Merge Is a Good Fit

Squash merging is useful when a feature branch contains many small commits such as:

• fix typo
• address review comment
• try approach B
• remove debug output

Those commits may have been useful during development, but not valuable in the permanent history of main.

Interactive Rebase Is a Different Tool

Sometimes you do want a cleaner branch history, but you still want to preserve meaningful intermediate commits. In that case, use interactive rebase before merging:

git checkout feature-branch
git rebase -i main

That lets you combine messy commits into a few meaningful ones. After that, you can do a normal merge or fast-forward merge depending on your team's workflow.

So the choice is:

• 'git merge --squash for one final commit'
• 'git rebase -i for a cleaned-up but still multi-commit history'

Pull Requests and Hosting Platforms

Most Git hosting platforms expose this as "Squash and merge" in the pull request UI. That produces the same general outcome as git merge --squash locally: one commit lands on the target branch, usually with a message derived from the PR title or combined commit messages.

The UI option is often safer for teams because it keeps the decision visible in the review workflow instead of depending on local command usage.

Be Aware of the Tradeoff

A squash merge creates cleaner target-branch history, but it also hides the intermediate reasoning captured by individual commits. That is not always bad, but it is a tradeoff.

If those intermediate commits matter for debugging, auditing, or understanding the evolution of a complex feature, preserving them may be more valuable than a single tidy commit.

Common Pitfalls

• Expecting --squash to create a real merge commit in the graph.
• Squash merging and then continuing work on the same branch without understanding the future merge implications.
• Using squash merge when the individual commits are already clean and meaningful.
• Confusing interactive rebase with squash merge even though they solve different history problems.
• Treating "clean history" as automatically better than traceable history.

Summary

• To land a branch as one commit, use a squash merge.
• 'git merge --squash stages the combined changes, then you create one commit.'
• Squash merging keeps history compact but does not record a real merge relationship.
• Use interactive rebase instead if you want a cleaner multi-commit branch history.
• Choose based on whether readability or commit-by-commit traceability matters more.