Git Merge Squash: Combine Multiple Commits

The git merge --squash command is the primary method to combine multiple commits from a feature branch into a single squashed commit on your target branch. This approach stages all the changes from your feature branch but doesn’t create a merge commit, allowing you to craft a single, descriptive commit message before finalizing the merge.

Contents

• Understanding Squash Merging
• Step-by-Step Squash Merge Workflow
• Alternative Approach: Interactive Rebase
• Platform-Specific Squash and Merge
• Best Practices and Considerations
• Troubleshooting Common Issues

Understanding Squash Merging

Squash merging consolidates all changes from a feature branch into a single commit on the target branch, creating a clean and linear project history. Unlike a regular merge that preserves the original commit history, squash merging combines all commits from the feature branch into one unified commit.

The key difference between regular merge and squash merge:

• Regular merge: Creates a merge commit that preserves the branch structure
• Squash merge: Creates a single commit that represents all the changes, effectively flattening the branch into the target

According to Git Tower documentation, the --squash option allows you to create a single commit whose effect is the same as merging another branch, but without automatically creating a merge commit.

Step-by-Step Squash Merge Workflow

Here’s the complete process to merge your feature branch into another branch as a single squashed commit:

1. Prepare Your Branch

Start by ensuring your feature branch is up to date and you’re ready to merge:

# Switch to your feature branch
git checkout feature-branch

# Pull the latest changes from remote
git pull origin feature-branch

# Ensure all your commits are ready
git status

2. Switch to Target Branch

Move to the branch where you want to merge your changes (typically main, master, or develop):

git checkout main
git pull origin main

3. Perform Squash Merge

Use the git merge --squash command to consolidate all commits from your feature branch:

git merge --squash feature-branch

This command:

• Stages all changes from feature-branch into your working directory
• Does not create a merge commit
• Prepares everything for a single commit with your custom message

4. Review and Commit

Now review the changes and create your single, official commit:

# Review what will be committed
git diff --staged

# Add a descriptive commit message
git commit -m "Implement user authentication feature with JWT tokens and password reset functionality"

5. Push to Remote

Finally, push your changes to the remote repository:

git push origin main

6. Clean Up (Optional)

Since all your changes are now in the target branch as a single commit, you can safely delete your feature branch:

# Delete local branch
git branch -d feature-branch

# Delete remote branch
git push origin --delete feature-branch

Alternative Approach: Interactive Rebase

If you want more control over which commits to include in your squashed commit, you can use interactive rebase:

1. Start Interactive Rebase

git checkout feature-branch
git rebase -i HEAD~n

Replace n with the number of commits you want to squash.

2. Edit Commit List

This opens an editor where you can change pick to squash or s for each commit you want to combine:

pick a1b2c3d Initial setup
pick d4e5f6g Add user model
pick h7i8j9k Implement authentication
pick l0m1n2o Add tests

# Rebase ...
#
# Commands:
# p, pick <commit> = use commit
# s, squash <commit> = use commit, but meld into previous commit
#

3. Combine Commits

Save and close the editor. Another editor will open asking you to combine commit messages. Edit this to create your final commit message.

4. Merge to Target

git checkout main
git merge feature-branch
git push origin main

Platform-Specific Squash and Merge

Most modern Git platforms provide built-in squash and merge functionality:

GitHub Squash and Merge

1. Open your pull request on GitHub
2. Click the “Merge pull request” dropdown
3. Select “Create a merge commit” or “Squash and merge”
4. Edit the commit message if needed
5. Confirm the merge

GitLab Squash and Merge

1. Navigate to your merge request
2. Click the “Merge” button
3. Choose “Squash” option
4. Edit the commit message
5. Click “Merge”

Bitbucket Squash and Merge

1. Open your pull request
2. Click the “Merge pull request” button
3. Select “Squash commits”
4. Edit the commit message
5. Confirm the merge

Best Practices and Considerations

When to Use Squash Merging

✅ Use squash merge when:

• You want a clean, linear project history
• Multiple commits represent different steps of the same feature
• You need to combine small, incremental commits into logical units
• Your team prefers simplified commit histories

❌ Avoid squash merge when:

• Each commit represents a critical milestone or step
• You need to preserve detailed commit history for auditing
• You’re working with multiple contributors on the same branch
• Some commits should remain separate for easier rollback

Commit Message Guidelines

When crafting your squashed commit message:

• Use the conventional commit format: type(scope): description
• Be descriptive but concise
• Include relevant issue numbers or references
• Explain the “why” behind the changes

Example:

feat(auth): implement JWT-based authentication system with password reset

- Add user model with password hashing
- Implement login/logout endpoints
- Add email verification and password reset flow
- Include comprehensive test coverage

Branch Management

After squash merging:

• The original feature branch becomes orphaned from the target branch
• You cannot easily track individual commits from the feature branch
• Consider keeping the feature branch until the merge is confirmed

Troubleshooting Common Issues

Merge Conflicts

If conflicts occur during squash merge:

# Abort the squash merge if there are conflicts
git merge --abort

# Fix conflicts manually
git add resolved-file.txt
git commit -m "Resolve merge conflicts"

# Try squash merge again
git merge --squash feature-branch

Permission Issues

If you can’t push to the target branch:

# Ensure you have permission to push
git remote show origin

# Check out the correct branch
git checkout main

# Pull latest changes
git pull origin main

Branch Cleanup Issues

After squash merging, you might need force delete:

# Force delete local branch (only if sure it's merged)
git branch -D feature-branch

# Force delete remote branch
git push origin --delete feature-branch

Conclusion

Squash merging is an essential Git workflow technique that helps maintain clean, professional commit histories while preserving all your work. The key takeaways are:

1. Use git merge --squash for the most straightforward approach to combine multiple commits into one
2. Write descriptive commit messages that clearly explain the feature or bug fix
3. Consider your team’s workflow and whether squash merging aligns with your collaboration style
4. Leverage platform features when available for easier workflow management
5. Clean up branches after successful merges to keep your repository organized

The squash merge workflow perfectly addresses your need to merge multiple informal commits into a single, official commit per feature or bug fix, giving you both the flexibility of individual work sessions and the professionalism of clean project history.

Sources

1. How to Squash Commits in Git | Git Tower
2. Git merge squash | Graphite.dev
3. How to squash and merge in Git | Graphite.dev
4. Squash and merge | GitLab Docs
5. Squash the Last X Commits Using Git | Baeldung on Ops
6. Git Squash - GeeksforGeeks
7. How to Merge Multiple Commits as Single Squashed Commit | Squash.io
8. Git Squash and Merge Workflow | Daniel Chen
9. About pull request merges - GitHub Docs
10. Squash commits into one with Git - Internal Pointers