Git Squash — Prevent Commit Loss with --force-with-lease

Squashing combines multiple commits into one clean commit. It is the standard pre-PR operation that transforms messy development history (WIP commits, typo fixes, debug logging) into a single meaningful commit that answers 'what changed and why'.

Three methods serve different use cases: interactive rebase for surgical control, merge --squash for branch-level squashing, and reset --soft for the fastest simple squash. The choice depends on how much control you need over which commits are combined and whether intermediate messages should be preserved.

Common misconceptions: that squashing is always required before merging (it is a team convention), that squashing loses code (it combines commits, the code stays), and that squashing is safe on shared branches (it rewrites SHAs, which breaks teammates).

What Git Squash Actually Does to Your Commit History

Git squash is a rebase operation that combines multiple commits into a single commit. The core mechanic: during an interactive rebase (git rebase -i), you mark commits with 'squash' or 'fixup' to fold their changes into the preceding commit. Squash preserves the commit message for editing; fixup discards it entirely. This rewrites history by creating new commit objects with combined diffs and timestamps.

Squashing does not merge changes — it replays them. Git takes the diff from each squashed commit and applies it sequentially, then creates one new commit with the accumulated changes. The original commits become unreachable from any branch reference, though they remain in the object store until garbage collection. This means squashing is a destructive rewrite: any other branch or collaborator referencing the original commits will diverge.

Use squash to clean up a feature branch before merging into main — turning a dozen 'fix typo' and 'WIP' commits into one logical change. It's essential for maintaining a readable, bisectable history. In CI/CD systems, squashing prevents noisy commit logs from triggering unnecessary build steps and makes rollbacks atomic. Never squash commits that have already been pushed to a shared branch unless you coordinate with the entire team.

Squash with Interactive Rebase

Interactive rebase is the surgical tool. git rebase -i HEAD~N opens an editor showing the last N commits. Change pick to squash (or s) on any commit to fold it into the one above it. fixup (or f) squashes without keeping the commit message — useful for minor fixes.

The mental model: the topmost commit in the editor is the oldest. Commits marked squash get folded into the commit immediately above them in the list.

# io.thecodeforge — Squash with Interactive Rebase

# ─────────────────────────────────────────────────────────────
# Squash last 4 commits
# ─────────────────────────────────────────────────────────────
git rebase -i HEAD~4

# Editor opens:
# pick a3f9c2e Add PaymentRetryService skeleton
# pick 7b2d4f1 Add exponential backoff logic
# pick 9c3e8a2 Fix null check in retry handler
# pick d4f8b3c Add unit tests for retry logic

# Change to:
# pick a3f9c2e Add PaymentRetryService skeleton
# squash 7b2d4f1 Add exponential backoff logic
# squash 9c3e8a2 Fix null check in retry handler
# squash d4f8b3c Add unit tests for retry logic

# Save and close. Git opens another editor to combine commit messages.
# Write the final message:
# feat(payment): Add PaymentRetryService with exponential backoff
#
# Implements retry logic for failed payment API calls.
# Uses exponential backoff with jitter to avoid thundering herd.
# Covers null payment reference edge case.

# ─────────────────────────────────────────────────────────────
# Use fixup instead of squash for commits whose messages you want to discard
# ─────────────────────────────────────────────────────────────
# pick a3f9c2e Add PaymentRetryService skeleton
# fixup 7b2d4f1 WIP: saving progress
# fixup 9c3e8a2 Fix typo
# fixup d4f8b3c Add debug logging (remove before merge)
# fixup does NOT open a message editor — the intermediate messages are discarded.

# ─────────────────────────────────────────────────────────────
# Force push to update remote (only on your own feature branch)
# ─────────────────────────────────────────────────────────────
git push origin feature/payment-retry --force-with-lease
# --force-with-lease fails if the remote has commits you do not know about.
# --force blindly overwrites — never use it.

Squash with git merge --squash

When merging a feature branch, git merge --squash feature/branch takes all commits from the branch and stages them as a single set of changes without creating a merge commit. You then write one commit message for the whole thing.

This is what GitHub does when you press 'Squash and merge'. The difference: GitHub creates the squashed commit for you; git merge --squash stages the changes and makes you commit manually.

# io.thecodeforge — Squash with git merge --squash

# ─────────────────────────────────────────────────────────────
# On main, squash-merge a feature branch
# ─────────────────────────────────────────────────────────────
git checkout main
git merge --squash feature/payment-retry

# All changes are now staged but not committed
git status
# Changes to be committed:
#   modified: src/main/java/io/thecodeforge/payment/PaymentRetryService.java
#   new file:   src/test/java/io/thecodeforge/payment/PaymentRetryServiceTest.java

# Write the single commit message
git commit -m "feat(payment): Add PaymentRetryService with exponential backoff

Implements retry logic for failed payment API calls.
Uses exponential backoff with jitter to avoid thundering herd.
Covers null payment reference edge case."

# ─────────────────────────────────────────────────────────────
# Clean up — feature branch is no longer needed
# ─────────────────────────────────────────────────────────────
git branch -D feature/payment-retry
git push origin --delete feature/payment-retry

Squash with git reset (Simplest for Small Cases)

For squashing a small number of commits on your current branch without opening an editor, git reset is the fastest path. Move HEAD back N commits while keeping the working directory changes staged.

# io.thecodeforge — Squash with git reset --soft

# ─────────────────────────────────────────────────────────────
# You have 3 commits to squash on feature/payment-retry
# ─────────────────────────────────────────────────────────────
git log --oneline -3
# d4f8b3c Add unit tests
# 9c3e8a2 Fix null check
# 7b2d4f1 Add backoff logic

# Soft reset: moves HEAD back 3 commits, keeps changes staged
git reset --soft HEAD~3

# All 3 commits' changes are now staged
git status

# Write one clean commit
git commit -m "feat(payment): Add retry logic with exponential backoff and tests"

# Force push with --force-with-lease (never --force)
git push origin feature/payment-retry --force-with-lease

When NOT to Squash

Squashing is not always the right choice. There are specific scenarios where preserving the commit history is more valuable than a clean linear log.

Large features with meaningful intermediate commits: If your feature has 15 commits but each one represents a logical, testable unit (e.g., 'add database migration', 'add API endpoint', 'add frontend component'), squashing them into one commit loses the ability to bisect within the feature. A reviewer who wants to understand the feature's evolution benefits from seeing the individual commits.

Shared branches where others have pulled your commits: Squashing rewrites SHAs. If teammates have branched off your commits, their branches diverge after you squash and force-push. Never squash on branches that others have pulled.

Release branches with audit requirements: In regulated industries, the commit history on release branches may be part of the audit trail. Squashing removes the individual commits that show when each change was made and by whom. Check your compliance requirements before squashing on release branches.

Commits that will be cherry-picked: If a commit needs to be cherry-picked to another branch (e.g., a hotfix), it must exist as a standalone commit. Squashing it into a larger commit makes cherry-picking impossible.

The Squash-Merge Trap: What the Docs Don't Tell You

Every new dev discovers git merge --squash and thinks they've found a cheat code. They haven't. They've found a landmine wrapped in convenience.

Here's what happens: git merge --squash feature-branch takes all commits from your feature branch, smashes them into your working directory as uncommitted changes, and leaves you hanging. No commit. No merge. No branch history link. You're holding a grenade with the pin pulled.

The docs call this "clean history." I call it losing the ability to trace which commits actually broke production. When your deployment fails at 3 AM, you want git bisect, not a single monolithic commit that says "Add billing system."

Use --squash only when the feature branch is truly atomic — one logical change, one commit worth of work. If you can't describe the entire branch's purpose in a single tweet, you're not squashing. You're bulldozing evidence.

// io.thecodeforge — devops tutorial

# Step 1: Checkout target branch
git checkout main
# Output: Switched to branch 'main'

# Step 2: Squash-merge feature branch
git merge --squash payment-gateway-v2
# Output: Automatic merge went well; stopped before committing as requested
# Notice: no commit created, no merge link preserved

# Step 3: Commit the squashed changes
git commit -m "feat: integrate Stripe payment gateway v2"
# Output: [main 7a9d4c3] feat: integrate Stripe payment gateway v2
#  1 file changed, 342 insertions(+)

Squashing the Last Two Commits: The Incantation You'll Use Daily

You've shipped a hotfix. Then you realized you forgot to bump the version. Then you noticed a typo in the README. Now you have three commits that should be one.

Here's the command you'll have muscle memory for by next week:

git rebase -i HEAD~2

That -i flag opens your default editor with a list of the last two commits. Change pick to squash (or just s) on the second commit. Save. Exit. Done.

What happened under the hood? Git took your commit messages, combined the diffs, and opened a new editor to merge the messages. Write something descriptive like "fix: resolve race condition in auth module" — not "fix bug #4812 fix bug #4813."

One warning: if you've already pushed those commits, force-pushing a squashed history will make your teammates want to strangle you. Only squash local commits or commits on branches you own exclusively.

// io.thecodeforge — devops tutorial

# Starting state — two commits that should be one
git log --oneline -3
# Output:
# e7b9f31 (HEAD) fix typo in auth error message
# 4c2a9fb fix: resolve race condition in auth module
# 1d3e8b5 feat: implement JWT authentication

# Squash tip commit into the previous one
git rebase -i HEAD~2

# In the editor, change:
# pick 4c2a9fb fix: resolve race condition in auth module
# squash e7b9f31 fix typo in auth error message

# Save & exit, then in the commit message editor:
# Keep: "fix: resolve race condition in auth module"
# Save & exit again

# Result:
git log --oneline -3
# Output:
# 8f1b2c3 (HEAD) fix: resolve race condition in auth module
# 1d3e8b5 feat: implement JWT authentication

Tips for a Smooth Squash

Most devs butcher a squash because they don't prep the battlefield. You're rewriting history — one misstep and you've nuked a coworker's branch. The rule: squash only commits that have never been pushed to a shared remote. If they have, you're asking for merge-conflict hell.

Before you rebase, run git log --oneline and count your commits. Know exactly how many you're squashing. Then git rebase -i HEAD~N where N is that count. In the editor, change every line after the first from 'pick' to 'squash' (or 's'). Save and exit — Git will prompt you for a new combined message. Write something meaningful, not 'fix stuff'.

Pro tip: if your branch is behind main after the squash, force-push is inevitable. Use git push --force-with-lease instead of --force. It checks if your remote branch has moved since you last fetched. If it has, Git aborts. That safety net has saved my ass more times than I'll admit.

// io.thecodeforge — devops tutorial

# Step 1: Count your commits
git log --oneline HEAD~5..HEAD
# Output:
# a1b2c3d fix: typo in login
# e4f5g6h feat: add rate limiter
# i7j8k9l chore: bump deps
# m0n1o2p fix: lint errors
# q3r4s5t feat: wire up API

# Step 2: Interactive rebase last 5 commits
git rebase -i HEAD~5
# In editor: change picks 2-5 to 's'

# Step 3: Force push with safety net
git push --force-with-lease origin my-branch