Bitbucket Cloud is making changes to pull request diff functionality that will improve diff performance, particularly on complex diffs. We are changing our diff algorithm from what we call a ‘3-way’ diff to a 2-way ‘three-dot’ diff, which will show the difference between the tip of a source branch and the commit from which it branched off the destination, as shown below. Starting June 6, 2022, this new diff will be progressively rolled out on the Pull request and Branch page.
What’s changing?
The main difference is the ‘3-way’ diff includes changes to the destination branch, whereas the ‘three-dot’ diff does not reflect changes made to the destination branch since the source branch was created from the destination branch. This small difference better isolates the changes introduced by the source branch and also allows the diff to be calculated much more quickly, resulting in improved diff performance, especially on complex diffs.
In most cases, you will have the same diff experience: When users make changes in some file(s) and others make changes to other files, the diff shown to the user will be exactly the same as it is today (only faster).
In the case where files changed in the source branch are the same files as those changed in the destination branch, the ‘three-dot’ diff will show only the changes introduced in the source branch. In order to see the changes to the destination branch in the diff, see the next section below.
How to see changes to the destination branch in a pull request
Most of the time you do not need to see the changes in the destination branch as the changes are completely unrelated; however, in case you do, simply merge the destination branch into the source branch. You can do this locally or using the Sync now button.
To merge the destination branch into the source branch locally:
Run git merge source_branch destination_branch
To merge the destination branch to the source branch of a pull request on the Pull request page:
Select the Sync now button at the top of the Commits list on the pull request page.
To rebase:
1. Run git checkout source_branch
2. Run git rebase destination_branch
For more information on merging and rebasing, see our Merging vs Rebasing tutorial.
Once the source branch includes the destination’s changes, the diff will match what you would have seen with a ‘3-way’ diff.
What about conflicts?
While the ‘three-dot’ diff will not reflect the changes made in the destination branch, the UI will still identify and indicate the files that have conflicts. However, instead of highlighting the conflicted lines in the diffs, conflicts will only be marked at the file level with a label. Just as before, you need to resolve conflicts locally before you can merge the changes.
See our support documentation about resolving merge conflicts for more information.
How does this affect Bitbucket’s Diff API?
As of May 23, 2022, the boolean query parameter merge will be deprecated in the Bitbucket diff and diffstat API. It will be replaced with a new query parameter topic, an optional boolean where true returns the more performant ‘three-dot’ diff and false returns a simple, ‘two-dot’ diff.
For the next six months, requests to the diff APIs with neither the merge nor topic parameter provided will return a ‘3-way’ diff. However, in six months, the merge parameter will be removed entirely, and requests without the topic parameter (or topic=true) will return a ‘three-dot’ diff.
Why the change?
The ‘3-way’ diff is an expensive operation that caused many customers to experience unacceptable levels of performance. Pull requests with ‘3-way’ diffs do not scale linearly with activity, because it requires the diff to change every time either the source or target branch changes, requiring comments to drift as well.
The ‘three-dot’ diff better isolates the changes in the source and destination branch and initial testing has shown that moving to the ‘three-dot’ diff reduces latency, therefore significantly improving performance on complex diffs in particular.
We believe that the majority of our customers will benefit from the improvements in performance and reduced complexity, as well as have an easier transition migrating from Server to Cloud (Bitbucket Server released the same change in version 7.0).