This article was updated on April 18, 2023, by Content and Marketing Specialist Dominik Letner.

Atlassian’s Bitbucket is a web-based version control repository service that comes in handy in terms of teams employing Git revision control systems. In this article, we will show you how to facilitate your Bitbucket use with one of Git’s principal functionalities – merge. We will also give you tips on handling merge conflicts.

In Git, merging is like rejoining a forked history of commits. By using the git merge command, developers can integrate the independent lines of development into a single branch. 

Bitbucket can a powerful tool in the hands of a development team. If you need a better grip on the basics, you can find them in our previous article. Here, we will go over the specific process of git merge in Bitbucket.

Here’s how git merge works

The command combines multiple commit sequences into one unified stream. Most of the time, development teams use it to combine two branches. In this most typical merging pattern, Git merge takes two commit pointers – usually the branch tips – and finds a common base commit they share. Once that happens, Git creates a new merge commit that includes the changes of every queued merge commit sequence.

Here’s an example

Let’s say that you have a new branch feature that is based on the master branch. Now you want to merge this feature into the master. If you use this command, you will merge the branch feature into the current branch – which we will assume here is the master. Git will automatically come up with the merge algorithm.

The thing about merge commits is that they have two parent commits – contrary to other types of commits. That’s why when creating a merge commit, Git will try to automatically merge their separate sequences. But if it stumbles upon a piece of data changed in both histories, it won’t be able to put them together. That’s when a version control conflict arises. Git requires users to fix that before continuing the merge. 

Take these preparation steps to make sure your Git merge goes smoothly:

Execute git status to make sure that HEAD is pointing to the correct branch that will be receiving the merge. You can also use git checkout <receiving> for switching to the receiving branch.

Ensure that the receiving branch and merging branch are kept up-to-date with the latest remote changes. To do that, execute git fetch so that you can pull the latest remote commits. Once this action is completed, you can be sure that the master branch has all the latest updates by using the git pull command.

You’re ready to initiate the merge by executing the following command: git merge <branch name>. The part called <branch name> refers to the one you’re planning to merge into the receiving branch.

NOTE: This and other commands mentioned in this article allow you to merge into the current branch. We will update the content to reflect performing the merge while leaving the target branch unaffected. That’s why developers use git merge together with git checkout for selecting the current branch. They also use git branch -d to delete the obsolete target branch if necessary.

When the path from the current branch tip to the target branch is linear, we can talk about a fast-forward merge. In this scenario, Git doesn’t really merge branches. Instead, it integrates the histories by moving (or fast-forwarding) the current branch tip to the target branch tip.

This method helps to combine these sequences efficiently – all the commits that can be reached from the target branch are now available in the current branch.

NOTE: Bitbucket Cloud introduced some changes to pull request diff functionality on 6 June 2022. You can find your way of navigating around them here.

If the branches have diverged at some point, fast-forward merge won’t be an option. When Git doesn’t see a linear path to the target branch, it is forced to combine the branches using a 3-way merge (the two branches’ tips and their common ancestor) which uses a dedicated commit to tie two sequences together. 

Development teams like to use fast-forward merges for smaller features or simple bug fixes. However, 3-way merges work best for integrating longer-running features. 

If a feature branch is small, developers can rebase it onto the master branch and do a fast-forward merge. That way, you won’t be cluttering the project’s history with unnecessary merges.

Let’s imagine the following situation. You have two branches to merge, but both have changed the same part of the same file. Git will have no idea which version it should use. In this scenario, Git will stop right before the merge commit to allow you to resolve the conflict manually.

To resolve merge conflicts, Git uses the edit, stage, commit workflow which is familiar to most developers. When a merge conflict occurs, all you need to do is run the git status command to see which files need to be manually resolved. Also, when Git encounters a conflict during a merge, it edits the affected files’ content using visual indicators that mark both sides of the content where conflict occurs. 

So, once you identify the conflicting sections, you can fix the merge easily. When you are ready to finish it, all it takes is running git add on the conflicted file or multiple files. That’s how you tell Git that you have resolved the conflict. After that, run the regular git commit to generate the merge commit. This process makes it easier for developers to manage their merges.

NOTE: It’s not possible to encounter conflicts in a fast-forward merge. Merge conflicts will only occur in a 3-way merge.

Bitbucket offers many features. You can discover more of them in our next article. Here, we discussed merging – one of the key processes for development teams working with Git. Make sure to apply the knowledge from this article with your next git merge commands to simplify your work with Git and Bitbucket.