Squash and merge
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
As you work on a feature branch, you often create small, self-contained commits. These small commits help describe the process of building a feature, but can clutter your Git history after the feature is finished. As you finish features, you can combine these commits and ensure a cleaner merge history in your Git repository by using the squash and merge strategy.
- Small commits are joined together, making it simpler to revert all parts of a change.
- When the single commit merges into the target branch, it retains the full commit history.
- Your base branch remains clean, and contains meaningful commit messages.
Each time a branch merges into your base branch, up to two commits are added:
- The single commit created by squashing the commits from the branch.
- A merge commit, unless you have enabled fast-forward merges in your project. Fast-forward merges disable merge commits.
By default, squashed commits contain the following metadata:
- Message: Description of the squash commit, or a customized message
- Author: User that created the merge request
- Committer: User who initiated the squash
Project owners can create new default messages for all squash commits and merge commits.
Set default squash options for a merge request
Users with permission to create or edit a merge request can set the default squash options for a merge request.
Prerequisites:
- Your project must be configured to allow or encourage squashing.
To do this:
- On the left sidebar, select Search or go to and find your project.
- Select Code > Merge requests and find your merge request.
- Select Edit.
- Select or clear the Squash commits when merge request is accepted checkbox.
- Select Save changes.
Squash commits in a merge request
If your project allows you to select squashing options for merge requests, to squash the commits as part of the merge process:
- On the left sidebar, select Search or go to and find your project.
- Select Code > Merge requests and find your merge request.
- Scroll to the merge request reports section that contains the Merge button.
- Ensure the Squash commits checkbox is selected. This checkbox doesn’t display if the project’s squashing option is set to either Do not allow or Require.
- Optional. To modify either the squash commit message or the merge commit message (depending on your project configuration), select Modify commit messages.
- When the merge request is ready to merge, select Merge.
Configure squash options for a project
Prerequisites:
- You must have at least the Maintainer role for this project.
To configure the default squashing behavior for all merge requests in your project:
- On the left sidebar, select Search or go to and find your project.
- Select Settings > Merge requests.
- In the Squash commits when merging section, select your desired behavior:
- Do not allow: Squashing is never performed, and the option is not displayed.
- Allow: Squashing is allowed, but cleared by default.
- Encourage: Squashing is allowed and selected by default, but can be disabled.
- Require: Squashing is always performed. While merge requests display the option to squash, users cannot change it.
- Select Save changes.
Related topics
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support