How to squash and merge in Git

Greg Foster
Greg Foster
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


Git merge squash is a merging strategy that allows you to take an entire branch's commit history and condense it into a single commit upon merging. This process is beneficial for keeping your main branch's history neat and manageable, without the clutter of often numerous and potentially messy intermediate commits that a feature branch might contain.

  • Cleaner history: Squashing commits can lead to a much cleaner, linear history, making it easier to navigate and understand.
  • Easier code review: A single commit means just one set of changes to review, as opposed to trying to understand multiple commits that may include fixes, reversals, and re-attempts.
  • Simplified revert process: If something goes wrong, you only need to revert a single commit.

Here’s a step-by-step guide on how to squash commits:

Before merging, make sure your feature branch is up to date with the latest changes from your main branch (typically main or develop). You can do this by running:

Terminal
git checkout feature-branch
git pull origin main # Ensure the feature branch is updated

To start the merging process with squashing, use the following command from the main branch:

Terminal
git checkout main
git merge --squash feature-branch

This command prepares the changes from feature-branch to be merged into main but doesn't actually commit them. Your staging area will now contain the changes from all the commits that were in feature-branch.

Before committing, you can review the changes that are staged for commit:

Terminal
git status # Check which files are staged for commit
git diff --staged # Review the changes in detail

This is your opportunity to make sure that everything looks right and no unintended changes are included.

Once you're satisfied with the changes, commit them:

Terminal
git commit -m "Describe the feature or changes being merged"

This step creates a single new commit on the main branch that represents all the changes that were previously spread across multiple commits in the feature-branch.

After the commit, push your changes to the remote repository:

Terminal
git push origin main
  • Use descriptive commit messages: Since the squash merge condenses many changes into one commit, it’s crucial to use a clear, descriptive commit message that explains why the changes were made.
  • Regular communication: If you're working in a team, keep others informed about the squash merges, as they might be looking for their commits in the main branch history.
  • Consider the context: Squash merging is great for feature branches or working branches with many intermediate commits. However, for branches with significant, distinct changes, consider a standard merge to preserve the context of each commit.

For further reading see the official Git documentation.

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2