Pull request merge strategies
Conflicts can happen with any of these merge strategies. When a conflict occurs,Bitbucket Data Center and Server will leave the repository as it was before attempting to apply the merge. To resolve such conflicts, check out the target branch locally and attempt to apply the rebase. The Git client can then facilitate resolution of these conflicts, finalize the local rebase and be pushed to the server. At that point you may wish to manually fast-forward the target branch, or simply attempt the pull request merge again using the web interface.
Git merge strategies affect the way the Git history appears after merging a pull request. With Bitbucket, you can choose which merge strategies to allow, and enable one or more merge strategies for all repositories in a project or for an individual repository. You can also allow users to choose a merge strategy from the merge dialog when they create a pull request.This page describes how to configure which merge strategies are available to your users, and briefly describes the merge strategies available.
On this page:
Merge strategies
Bitbucket comes with only one merge strategy enabled by default, but all merge strategies can be enabled (or disabled) at the project level for all repositories in a project or for individual repositories, provided merge strategies for a repository are configured to inherit project settings.
The merge strategies available in Bitbucket are:
- Merge commit (
--no-ff) DEFAULT: Always create a new merge commit and update the target branch to it, even if the source branch is already up to date with the target branch. - Fast-forward (
--ff): If the source branch is out of date with the target branch, create a merge commit. Otherwise, update the target branch to the latest commit on the source branch. - Fast-forward only (
--ff-only): If the source branch is out of date with the target branch, reject the merge request. Otherwise, update the target branch to the latest commit on the source branch. - Rebase, merge
(rebase + merge --no-ff): Commits from the source branch onto the target branch, creating a new non-merge commit for each incoming commit. Creates a merge commit to update the target branch. The PR branch is not modified by this operation. - Rebase, fast-forward (
rebase + merge --ff-only): Commits from the source branch onto the target branch, creating a new non-merge commit for each incoming commit. Fast-forwards the target branch with the resulting commits. The PR branch is not modified by this operation. - Squash (
--squash): Combine all commits into one new non-merge commit on the target branch. Squash, fast-forward only (
--squash --ff-only): If the source branch is out of date with the target branch, reject the merge request. Otherwise, combine all commits into one new non-merge commit on the target branch.
Commit summaries
When you merge a pull request, you can control the number of commit summaries included in commit messages with the Commit summaries option. You can do this for a single repository or all repositories in a project. This setting is helpful if you don't want to see as many commit details in the commit message when merging or squashing a pull request.
- Commit with no summaries.
- Commit with two summaries.
To set the maximum number of commit summaries for a single repository (requires repository admin permissions):
- Go to Repository settings > Merge strategies.
- Enter the maximum number of commit summaries to include. Specify zero to display no summaries.
To set the maximum number of commit summaries for a project (requires project admin permissions):
- Go to Project settings > Merge strategies
- Enter the maximum number of commit summaries to include. Specify zero to display no summaries.
Using rebase in Bitbucket
Rebasing allows you to replay feature branch commits onto the tip of your target branch, creating a linear history.
By rebasing your commits to the tip of the target branch, you retain existing commits, and simply add yours on top.
Potential issues
When using a rebase workflow, it's possible to encounter unexpected side effects if branches aren't carefully managed and tracked. For example:
- If you have a branch that uses a previously merged branch (using rebase) as a common ancestor, further merging (using rebase) can cause duplicate commits with empty content to be applied to a target branch.
- When running a
git pulllocally after a pull request's source branch has been rebased using the UI, it can result in unexpected merges between the original commits (still present on the local branch), and their rebased replacements, (fetched from the server). When pulling, if the tracking branch has been updated on the remote, by default Git will merge the incoming changes with the local commit.
Conflicts
Conflicts can happen with any merge strategy. When a conflict occurs, Bitbucket will leave the repository as it was before attempting to apply the merge.
To resolve such conflicts, check out the target branch locally, and attempt to apply the rebase. The Git client can then facilitate resolution of these conflicts, finalize the local rebase, and be pushed to the server.
At that point you may wish to manually fast-forward the target branch, or simply attempt the pull request merge again using the web interface.
Transactional failures
A transactional failure occurs when a two-step process (ie rebase, then merge) is taking place and other changes are made at the same time that prevent the second step from applying as expected. The impact for you means on occasion, if you try to rebase, it will fail, and won't apply the merge. You will receive a transactional failure notification if this happens.
In the event there is a transactional failure, we recommend waiting a short time, refreshing the browser to load the latest pull request state, and trying again.
An asynchronous process updates pull requests when the source and target branches change, so multiple retries (or a longer wait) may be required before the system is in a consistent state to attempt the merge.
Need more context? Try our merging versus rebasing tutorial.
Change the merge strategy for a single pull request
Which merge strategies can be used is determined by the merge strategies enabled by your project or repository admins.
To change the merge strategy for a specific pull request:
- When merging a pull request, click the default merge strategy in use, then select a new one.
- Add a comment (if applicable), the click Merge.
Configure merge strategies for all repositories in a project
Enabling a merge strategy at the project level allows users to choose that merge strategy when merging pull requests for all repositories in a project, unless a repository is configured to use custom settings instead.
To enable (or disable) merge strategies for all repositories in a project (requires project admin permissions):
- Go to Project settings > Merge strategies.
- Click the toggle by a merge strategy to enable (or disable) it.
- Click Save.
Users can now choose any of the merge strategies you enabled when they merge pull requests from the repositories in the project.
Configure merge strategies for an individual repository
Enabling (or disabling) a merge strategy at the repository level allows users to choose that merge strategy when merging pull requests created in that repository. Configuring merge strategies at the repository level requires you to override merge strategies configured at the project level. If you have not configured merge strategies for an individual repository it will inherit the merge strategies enabled at the project level.
To enable (or disable) merge strategies for a single repository (requires repository admin permissions):
- Go to Repository settings > Merge strategies.
- In the Project settings inheritance section, select Use custom settings.
- Click the toggle by a merge strategy to enable (or disable) it.
- (Optional) Once a merge strategy is enabled you can set it as the default merge strategy for that repository by hovering next to the toggle and clicking Set as default.
- Click Save.
Once set, any changes made to merge strategies at the project level will be ignored for this repository because it was changed independent of the project configuration.