Squash Commits: When They Make Sense and When They Don't

1. What squashing actually does under the hood

Squashing commits means collapsing several consecutive commits into a single new commit. The resulting file tree matches exactly the last commit in the sequence, but the intermediate steps, their messages, and their timestamps disappear from the visible history. Git offers two fundamentally different ways to do this: git merge --squash applies all changes from a branch into the working directory and the staging area, but deliberately creates no merge commit and no merge reference back to the source branch. The developer then commits the changes themselves, with a freely chosen message. The second path is git rebase -i with the squash or fixup commands, which combines already existing commits within a rebase sequence before they are even merged.

The difference between squash and fixup in an interactive rebase is subtle but practically relevant: squash opens an editor and lets you merge the commit messages of all marked commits into one new, combined message. fixup discards the message of the commit being squashed entirely and silently keeps only the message of the preceding commit. For small correction commits like "typo fix" or "address review comment", fixup is the right tool, because those messages add no value to the final history anyway.

A third, less commonly used path is git reset --soft HEAD~n followed by a fresh git commit. This approach resets the branch pointer without touching the staging area or the working directory, and then allows a completely new commit over the accumulated changes. It is especially useful when you already plan to write a brand new commit message and don't want to interact with the rebase editor at all.

# Feature branch changes are staged for a single commit, no merge commit created
git checkout main
git pull origin main
git merge --squash feature/checkout-refactor
# Staged changes now reflect the entire feature branch diff
git status
git commit -m "feat(checkout): simplify payment step validation"

# Note: the feature branch history is NOT recorded as an ancestor
git log --oneline -1
# a1b2c3d feat(checkout): simplify payment step validation

2. Squash-on-merge as a team policy for a clean main history

GitHub, GitLab, and Bitbucket typically offer three merge strategies when closing a pull request: the classic merge commit, squash merge, and rebase merge. Many teams configure squash merge as the only allowed option, often directly through branch protection rules or repository settings. The result: every pull request lands on the main branch as exactly one commit, regardless of whether the branch behind it contained two commits or two hundred. The main history stays linear and readable at feature level, without "wip", "fix", "one more attempt", or similar intermediate commits.

The practical benefit shows up mainly in code archaeology and rollbacks: a git log --oneline on main shows one line per completed feature or bug fix, directly linked to the pull request number in the subject if the platform inserts it automatically. Reverting an entire feature is reduced to a single git revert call against exactly one commit, instead of having to undo an entire chain of intermediate commits one by one. For teams with many small, frequently merged pull requests, this is a noticeable productivity gain when reading the history.

# .github/settings.yml: enforce squash-only merges via repository settings
repository:
  allow_merge_commit: false
  allow_rebase_merge: false
  allow_squash_merge: true
  squash_merge_commit_title: "PR_TITLE"
  squash_merge_commit_message: "PR_BODY"

branches:
  - name: main
    protection:
      required_status_checks:
        strict: true
        contexts: ["ci/tests", "ci/phpstan"]
      enforce_admins: true
      required_pull_request_reviews:
        required_approving_review_count: 1

3. The price of squashing: lost granularity and authorship

Every squash discards information that cannot be recovered later once the source branch is deleted. Individual commit messages that document why a particular intermediate step was necessary merge into a single, necessarily coarser message. Timestamps of individual changes are lost, which can matter for analyzing development velocity or for forensic investigation after an incident. On feature branches with multiple authors, for example through pair programming or co-reviews with direct commits, only a single author identity remains visible in the final commit, unless Co-authored-by trailers are explicitly added to the final commit message.

The loss shows up most clearly in a direct before-and-after comparison of the history. A traceable chain of five clearly named steps becomes a single, often several-hundred-line diff with one summarizing message. For quick code review within the pull request itself, this doesn't matter much, since the platform's diff view is usually inspected as a whole anyway. It becomes a problem only later, when someone months down the line wants to understand exactly in what order and for what reason the individual sub-steps were created.

# Before squash: five atomic, individually reviewable commits
git log --oneline feature/checkout-refactor
f4e5d6a fix(checkout): correct rounding in tax calculation
c3b2a1f test(checkout): add coverage for split payments
b2a1f0e refactor(checkout): extract PaymentValidator service
a1f0e9d fix(checkout): handle missing shipping address
9e8d7c6 feat(checkout): add express checkout button

# After squash merge into main: one commit, one combined diff
git log --oneline main -1
7c6b5a4 feat(checkout): express checkout with validated payment flow (#482)

4. Bisectability: why granular history matters for debugging

git bisect performs a binary search over the commit history to find exactly the commit that introduced a regression. The algorithm halves the search space at each step, marks a commit as "good" or "bad", and needs only log2(n) test runs across n commits to isolate the culprit. This efficiency only works if every single commit is individually buildable and testable and represents a small, self-contained change.

A squashed "monster commit" that combines five or ten logically independent changes into a single diff destroys exactly that granularity. git bisect will then reliably show that the bug was introduced somewhere in that one pull request, but no longer which of the originally five sub-changes is the actual root cause. For complex refactors with a hundred or more changed lines, this often means additional manual debugging work that would have been fully automatable if the atomic commits had been preserved.

5. When NOT to squash: large refactors and documented intent

For extensive refactors that unfold over several days or weeks, each individual commit documents a deliberate intermediate step: extracting a method, renaming a class, swapping a dependency, adding tests for the new state. This sequence is valuable documentation in its own right, one that later developers can trace via git log and git blame without having to ask the original author. If such a refactor gets squashed, exactly this narrative of the codebase is lost, and a future viewer only sees the end result, not the path that led there.

A practical middle ground for exactly this case is rebase merge instead of squash merge: the individual, already cleanly structured commits are replayed linearly onto the current main branch, but remain as separate, individually bisectable commits. The prerequisite is discipline during development, since rebase merge only pays off if the commits on the feature branch are already meaningfully structured before the merge, rather than needing to be cleaned up afterward.

6. Long-lived feature branches with atomic commits

Long-lived feature branches developed alongside main for weeks benefit especially from preserved commit granularity, when every commit individually compiles, passes the test suite, and represents a self-contained change. Such a branch then reads almost like a development diary: every step is individually traceable, individually revertible, and individually bisectable, without needing a squash at the end to make the history readable.

The decisive difference from chaotically grown branches lies in discipline during development, not in cleanup afterward. Teams that consistently write small, atomic commits with meaningful messages need squash merge less often as a pure safety net for messy history. Squash merge as a team policy often works well in practice precisely because it doesn't require that discipline: a chaotic intermediate state during development gets automatically smoothed over at merge time, without requiring every developer to commit cleanly on their own.

7. Interactive rebase: manual squashing step by step

git rebase -i HEAD~5 opens the configured editor with a list of the last five commits, each prefixed with pick. Changing the prefix to squash or s merges that commit with the one directly above it, and Git then opens another editor pass to combine the commit messages. fixup or f does the same thing, but silently discards the message of the commit being squashed. The order of the lines in the rebase list also determines the new commit order, which is why lines can be moved around to reorder commits before they're combined.

If conflicts occur during the rebase, Git pauses at the affected commit, the conflict is resolved as usual in the working directory, marked with git add, and the process continues with git rebase --continue. For recurring correction commits, git commit --fixup=<commit> followed by git rebase -i --autosquash is a good fit: Git automatically places commits marked as fixup! at the right spot in the rebase list and already marks them correctly, with no manual line-shuffling needed.

# Interactive rebase over the last 5 commits
git rebase -i HEAD~5

# Editor content: reorder and mark commits for squashing
pick a1f0e9d fix(checkout): handle missing shipping address
pick 9e8d7c6 feat(checkout): add express checkout button
squash b2a1f0e refactor(checkout): extract PaymentValidator service
fixup c3b2a1f test(checkout): add coverage for split payments
fixup f4e5d6a fix(checkout): correct rounding in tax calculation

# After resolving the combined commit message editor:
git log --oneline -1
9f8e7d6 feat(checkout): add express checkout with validated payments

# Autosquash workflow for later fixups
git commit --fixup=b2a1f0e
git rebase -i --autosquash main

8. Commit message conventions after squashing

After squashing, the responsibility falls to writing a single commit message that summarizes the entire scope of the pull request, rather than just describing the last intermediate step. The Conventional Commits format has proven effective: a type prefix like feat, fix, or refactor, a short, imperative-mood subject line, and, where needed, a body with rationale plus a reference to the ticket or issue number. GitHub defaults to using the pull request title as the commit subject on squash merge and lists the titles of the original commits in the body, which rarely results in a good final message without manual cleanup.

The more reliable practice is to treat the pull request title itself as a complete, meaningful commit message from the start, reviewing and overriding it before the merge if necessary, rather than relying on the automatically assembled preview. Tools like commitlint can be applied to pull request titles in the CI pipeline to enforce the Conventional Commits format before the merge happens. This keeps the main history consistently machine-readable despite squash merge, and usable for automated changelog generation.

9. Team policy, branch protection, and merge strategies compared

Branch protection rules on GitHub and GitLab let you set the allowed merge strategy centrally per repository, instead of leaving it up to every developer's free choice on every pull request. This prevents inconsistencies where one feature lands on main as a merge commit, the next as a squash merge, and a third as a rebase merge, which makes reading the overall history considerably harder. Configuration happens either through the web interface under repository settings or declaratively through configuration files that can be versioned and integrated into infrastructure-as-code workflows.

# ~/.gitconfig: sensible defaults for a team favoring linear history
[pull]
    rebase = true

[merge]
    ff = false

[rebase]
    autosquash = true
    autostash = true

[branch]
    autosetuprebase = always

The table shows that no strategy wins on every dimension. Squash merge consistently optimizes for a clean, linear main history and simple reverts, but sacrifices granularity and bisect precision to do so. Rebase merge preserves both, but demands discipline in commit structure on the feature branch and potentially repeated conflict resolution during the rebase. Merge commits are the most conservative compromise: nothing gets lost, but the main history becomes harder to scan due to merge nodes. The right choice depends less on a blanket best practice than on the nature of the repository itself: a microservice with many small, independent pull requests usually benefits from squash merge, while a core library with complex, bisect-critical changes tends to benefit more from rebase merge or carefully curated merge commits.

10. Summary

Squash commits solve one concrete problem: messy feature branches full of "wip" and "fix" commits end up as a single, clearly named commit on main. git merge --squash and git rebase -i with squash/fixup are the technical tools for this, and branch protection rules turn squash merge into a binding team policy. The gain is a linear, easily readable main history with simple reverts. The price is losing granularity, individual authorship in intermediate commits, and bisect precision as soon as a bug hides inside a squashed monster commit.

The right decision is rarely universal. Small, frequently merged pull requests in microservices almost always benefit from squash merge. Large refactors, core libraries with high bisect relevance, and long-lived feature branches with already disciplined, structured commits deserve rebase merge or carefully curated merge commits instead, so the code's origin story is preserved.

11. FAQ: Squash Commits