4.5 KiB
| stage | group | info |
|---|---|---|
| Create | Source Code | To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments |
Squash and merge (FREE)
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 both merge commits and squashing.
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. To do this:
- Go to the merge request and 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:
- Go to the merge request, and 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
- Introduced in GitLab 13.2 with a flag named
squash_options, disabled by default.- Enabled on GitLab.com and self-managed by default in GitLab 13.3.
- Generally available in GitLab 13.8. Feature flag
squash_optionsremoved.
To configure the default squashing behavior for all merge requests in your project:
- On the top bar, select Menu > Projects and find your project.
- On the left sidebar, select Settings > General.
- Expand 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 deselected 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.