Merge strategies

By default, merge strategy settings from the project level are inherited by the repositories. Repository admins can either choose to inherit the project-level settings or override it by configuring custom settings at the repository level.

Later when you modify project settings, only settings in repositories that are set to inherit the project-level setting change to match the project merge strategy settings.

Starting from Bitbucket 8.10, project admins can also restrict changes to repository-level settings. Note that when you restrict changes, any custom settings saved at the repository-level are deleted and the repositories 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 message templates

Instead of using the default commit message in your pull requests, you can create a custom template for commit messages and apply this template at a project or repository level.

When you merge a pull request, the value set in the template will be used to populate the title and body fields of the commit message in the merge modal. Commit message templates also support variables, allowing your commit messages to include details such as the source and target branch or the approvers of the pull request.

To configure a custom template for commit messages:

1. Navigate to Project or Repository settings > Merge strategies.
2. Under Commit message template, set Template behavior to Use a custom template.

3. Enter the desired title and body in the Commit message fields. You can use the supported variables.
   
   

   The title is mandatory.
   
   The following variables are supported:

   1. title – the pull request title

   2. id – the pull request ID

   3. description – the pull request description

   4. toProjectKey – the project key of the target project

   5. fromProjectKey – the project key of the source project

   6. toRepoSlug – the slug of the target repository

   7. fromRepoSlug – the slug of the source repository

   8. crossRepoPullRequestRepo – the project and repository of the source ref when the pull request is a cross-repo pull request; or an empty string in the case where the source and target repositories are the same

   9. toRefName – the display name of the target ref

   10. fromRefName – the display name of the source ref

   11. approvers – a comma-separated list of users that have approved the pull request at the time the merge modal is opened; or an empty string in the case where there are no such approvals
       
       

4. Select Save.

The template is applied when merging a pull request:

Custom commit messages remain editable, so you can always make changes to yours before merging a pull request.

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. 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. You can do this for all repositories in a project or a single repository (if your project admin hasn't restricted repository-level changes).

1. Commit with no summaries. 
2. Commit with two summaries. 

To set the maximum number of commit summaries for a single repository (requires repository admin permissions):

1. Go to Repository settings > Merge strategies.
2. 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):

1. Go to Project settings > Merge strategies
2. 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 pull locally 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.

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:

1. When merging a pull request, click the default merge strategy in use, then select a new one.
2. 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.

To enable (or disable) merge strategies for all repositories in a project (requires project admin permissions):

1. Go to Project settings > Merge strategies.
2. Select the toggle next to a merge strategy to enable (or disable) it.
3. Click Save.
4. Optional: To restrict repository-level changes, select Don't allow changes to merge strategies from the Restrict changes to repository settings menu.

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

If the project admin hasn't restricted repository-level changes, you can customize settings for individual repositories.

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):

1. Go to Repository settings > Merge strategies.
2. In the Project settings inheritance section, select Use custom settings.
3. Click the toggle by a merge strategy to enable (or disable) it.
4. (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.
   
   
   
5. 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.