Simplify Git History: Squashing Your Last N Commits Effectively

This is the article you requested:

A clean and coherent Git history is invaluable for any development team. It acts as a project’s narrative, documenting changes, simplifying debugging, and fostering better collaboration. However, the natural development process often leads to numerous small, incremental commits—typo fixes, “work in progress” saves, or minor adjustments—that can clutter the history and obscure the true progression of features. This is where Git commit squashing comes in.

Squashing commits is the process of combining multiple sequential commits into a single, more meaningful commit. This powerful technique allows developers to present a streamlined, logical history, making it easier for everyone involved to understand the project’s evolution.

This article will delve into why and when to squash commits, provide a detailed step-by-step guide on how to effectively squash your last N commits using Git’s interactive rebase, and share essential best practices to ensure a smooth workflow.

Why Squash Commits? The Benefits

The advantages of a well-squashed commit history extend beyond mere aesthetics:

Clean and Concise History:
- Eliminate Noise: Gets rid of superficial commits like “fix typo,” “WIP,” or “oops, forgot a file.” These micro-commits, while useful during active development, add little value to the long-term history.
- Present Logical Units: Transforms a series of small, related changes into a single commit that represents a complete feature, bug fix, or logical unit of work. This makes the commit log far more readable and digestible.
Simplified Code Reviews:
- Focus on Features: Reviewers can concentrate on the substantive changes of a feature rather than sifting through a myriad of intermediate steps. This reduces cognitive load and speeds up the review process.
- Reduced Noise: A consolidated commit message provides a clear summary of the changes, improving communication and understanding within the team.
Easier Reverts and Debugging:
- Streamlined Reverts: If a feature or a bug fix introduced issues, reverting a single, squashed commit is far simpler and less error-prone than attempting to revert multiple scattered commits.
- Effective git bisect: When using git bisect to pinpoint the commit that introduced a bug, a squashed history with meaningful commits allows for more efficient narrowing down of the problematic change, as each commit is a complete, testable state.
Enhanced Collaboration:
- Clearer Understanding: Team members gain a better overview of how and why changes were made, fostering a shared understanding of the codebase.
- Better Documentation: Well-crafted commit messages for squashed commits serve as concise, high-level documentation of the project’s evolution.

When to Squash (and When Not To)

While beneficial, squashing should be applied judiciously.

Good Scenarios for Squashing:

Before Merging to main or develop: This is perhaps the most common use case. Before integrating a feature branch into a main integration branch, squash its commits into one or a few logical units.
Cleaning Up Local WIP Commits: On your personal feature branch, before pushing for review, squashing your “work in progress” or “testing” commits makes your development story coherent.
Preparing a Pull Request: A clean, squashed set of commits significantly improves the experience for maintainers reviewing your pull request.
Combining Related Bug Fixes: If you have a series of minor commits addressing a single bug, squashing them into one commit clearly explains the bug and its resolution.

When to Exercise Caution or Avoid:

Never squash commits that have already been pushed to a shared remote repository and pulled by others. This is a critical rule. Squashing rewrites history, and doing so on shared branches will lead to conflicts and confusion for anyone who has based their work on the original, un-squashed history. Only squash commits that exist solely in your local repository or on a feature branch that no one else has pulled from.
When Individual Commits Represent Meaningful, Distinct Steps: If each commit in a series adds significant, independent value and you wish to preserve that granular history (e.g., for auditing, specific historical context), then squashing might not be appropriate.
If Detailed Historical Granularity is Crucial: Some workflows or projects might prioritize a very detailed, unadulterated history. In such cases, squashing should be minimized.

How to Squash Your Last N Commits: A Step-by-Step Guide

The most powerful and flexible method for squashing commits is using git rebase -i (interactive rebase).

Method 1: Using `git rebase -i` (Interactive Rebase) – The Recommended Approach

This method allows you fine-grained control over which commits to squash, combine their messages, and even reorder them.

Understand git rebase -i HEAD~N:
- HEAD refers to your current commit.
- ~N means “the N commits directly before HEAD.”
- So, git rebase -i HEAD~3 will include your last three commits (plus the commit before those three, which serves as the base for the rebase).
- Important: N is the number of commits you want to affect, not the total number of commits from HEAD. If you want to squash your last 3 commits, you’ll specify HEAD~3. The rebase will show these 3 commits, plus the commit just before them.
Initiate the Interactive Rebase:
Open your terminal and run the command:
bash git rebase -i HEAD~N
Replace N with the number of commits you wish to squash. For example, to squash your last 3 commits:
bash git rebase -i HEAD~3
Git will open a text editor (your default Git editor, e.g., Vim, Nano, VS Code) displaying a list of the commits you selected, in reverse chronological order (the oldest commit you’re rebasing will be at the top).

Example editor content:
“`
pick e3a1b35 Commit message for oldest commit (e.g., initial feature work)
pick f7c2d89 Commit message for middle commit (e.g., added a helper function)
pick 8c4d2a1 Commit message for newest commit (e.g., fixed a bug in helper)

Rebase 8c4d2a1..e3a1b35 onto e3a1b35 (3 commands)

Commands:

p, pick = use commit

r, reword = use commit, but edit the commit message

e, edit = use commit, but stop for amending

s, squash = use commit, but meld into previous commit

f, fixup = like “squash”, but discard this commit’s log message

x, exec = run command (e.g. git commit --amend)

b, break = stop here (continue rebase later with ‘git rebase –continue’)

d, drop = remove commit

l, label = label current HEAD with a name

t, reset = reset HEAD to a label

m, merge [-C | -c ] [# ]

. create a merge commit at the current HEAD

These lines can be re-ordered; they are executed from top to bottom.

If you remove a line here, that commit will be removed from the history.

However, if you remove everything, the rebase will be aborted.

“`
Modify the To-Do List:
This is where you tell Git how to treat each commit.
- pick (p): Keep the commit as is. The first commit in your list (the oldest one you’re affecting) should usually be pick as it will be the base for squashing.
- squash (s): Use this for commits you want to combine with the immediately preceding pick or reword commit. Git will combine its changes and then open another editor for you to combine its commit message with the previous one.
- fixup (f): Similar to squash, but it discards the commit message of the fixup commit. Only the message of the preceding commit will be used. This is great for trivial commits where the message isn’t important.
To squash the last two commits into the oldest one, your editor might look like this:
pick e3a1b35 Commit message for oldest commit squash f7c2d89 Commit message for middle commit squash 8c4d2a1 Commit message for newest commit
Or, if you only care about the changes and want to discard the messages of the newer commits:
pick e3a1b35 Commit message for oldest commit fixup f7c2d89 Commit message for middle commit fixup 8c4d2a1 Commit message for newest commit
Save and Close the Editor:
After making your selections, save the file and close the editor.
Edit Commit Messages:
If you used squash (not fixup), Git will open another editor. This editor will contain the commit messages of all the commits you marked for squashing. Your task is to combine these into a single, cohesive, and descriptive commit message for the new, consolidated commit. Delete unnecessary lines, refine the summary, and provide a clear explanation of all the changes being introduced.

Example of what you might see:
“`

This is a combination of 3 commits.

This is the 1st commit message:

Commit message for oldest commit (e.g., initial feature work)

This is the 2nd commit message:

Added a helper function

This is the 3rd commit message:

Fixed a bug in helper

Please enter the commit message for your changes. Lines starting

with ‘#’ will be ignored, and an empty message aborts the commit.

… (other Git comments)

You would then edit it to something like:
feat: Implement User Authentication

This commit introduces user authentication features, including:
– User registration endpoint
– Login and session management
– Helper functions for password hashing and token generation
– Bug fix for helper function initialization.
“`
Save and close this editor.
Resolve Conflicts (if any):
Occasionally, if the commits you’re squashing modify the same lines of code in conflicting ways, Git will pause the rebase and ask you to resolve these conflicts.
- Use git status to see conflicting files.
- Manually edit the files to resolve the conflicts.
- git add <resolved-file> for each resolved file.
- git rebase --continue to proceed with the rebase.
- If you encounter difficulties or wish to stop, use git rebase --abort.
Completing the Rebase:
Once all steps (including conflict resolution) are complete, Git will finalize the rebase, and your history will be rewritten with the new squashed commit(s).
Force Pushing (if necessary and with extreme caution):
If you have already pushed the original, un-squashed commits to a remote repository, your local history will now diverge from the remote. To update the remote, you will need to force push.
- Use git push --force-with-lease: This is generally safer than git push --force. It pushes only if your local branch is an ancestor of the remote branch, preventing you from accidentally overwriting someone else’s work if they’ve pushed changes in the meantime.
- git push --force: This will unconditionally overwrite the remote branch. Use it with extreme care and only if you are absolutely certain no one else has pushed to that branch.
- NEVER force push to shared branches (e.g., main, develop) without prior team consensus.

Method 2: Using `git reset --soft` and `git commit` (Simpler for Basic Cases)

This method is less flexible than git rebase -i but simpler for combining the very last N commits into one, without needing to interactively select pick/squash/fixup.

Reset HEAD Softly:
This command moves your branch’s HEAD pointer back N commits, but it keeps all the changes from those N commits in your staging area (index) and working directory.
bash git reset --soft HEAD~N
For example, to combine the last 3 commits:
bash git reset --soft HEAD~3
After this, your HEAD will point to the commit before the N commits you specified, and all the changes from those N commits will be staged as if you just made them.
Create a New Consolidated Commit:
Now, simply create a new commit that includes all the staged changes:
bash git commit -m "Your new consolidated commit message"
This will create a single new commit that encompasses all the changes from the previous N commits.
Force Push (if applicable):
As with interactive rebase, if you’ve already pushed the original commits, you’ll need to force push (git push --force-with-lease) to update the remote.

This method is ideal when you simply want to combine the last few commits without needing to reorder or pick individual messages.

Best Practices and Tips for Effective Squashing

To make squashing a productive part of your workflow:

Work on Feature Branches: Always perform squashing operations on local feature branches before they are merged or opened for pull requests. This minimizes the risk of affecting other developers.
Craft Descriptive Commit Messages: The message for your squashed commit should clearly summarize all the changes it contains. Think of it as a mini-release note for that logical unit of work.
Back Up Your Work: Before any history-rewriting operation like rebase, it’s wise to create a temporary backup branch: git branch backup-branch. If something goes wrong, you can always revert to backup-branch.
Practice Makes Perfect: If you’re new to git rebase -i, practice on a dummy repository or a non-critical local branch to get comfortable with the process.
Communicate with Your Team: Especially in larger teams, ensure everyone understands the team’s policy on squashing and force pushing.

Conclusion

Mastering the art of squashing Git commits is a vital skill for any developer aiming to maintain a clean, readable, and efficient project history. By transforming a series of iterative changes into coherent, logical units, you not only simplify code reviews and debugging but also foster better collaboration and a clearer understanding of your project’s evolution. While git rebase -i requires a bit of practice, its power in shaping a pristine commit log is unparalleled. Adopt squashing as a key component of your Git workflow, and watch your project’s history become a valuable asset rather than a tangled mess.