How to use Git merge in Atlassian’s Bitbucket

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

Git merge and Bitbucket

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.

Merge commits 

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. 

What to do before merging in Bitbucket

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

Step 1: Verify the receiving branch

A graph showing how to identify the right branch to use the git merge feature.
Source: Atlassian.

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.

Step 2: Fetch the latest remote commits

A graph showing how a new merge commit is introduced.
Source: Atlassian.

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.

Now it’s time to merge!

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.

Fast-forward merge

A graph showing the fast-forward merge option.
Source: Atlassian.

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.

Three-way merge

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.

A graph showing two variants of the three-way merge option.
Source: Bitbucket.

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.

How to deal with Merge conflicts

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.

Git merge in Bitbucket summary

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.

Ready to work with ease thanks to Bitbucket?

If you are looking for expert consultants, who could help you take advantage of Bitbucket, get in touch with us. We help development teams streamline their processes with Atlassian tools to position their organizations for success.

Boguslaw Osuch

Bogusław is the Head of Atlassian Services at Deviniti. His brightness star in Deviniti Galaxy is to share knowledge about methodology, best practices, and IT standards. He uses his many years of experience every day to support companies in optimizing their internal processes and developing strategies. He believes that people are the essential element in every team, and the most effective teams are those that work according to jointly developed processes and use tools that release their potential. Bogusław is a pragmatist, entrepreneur, and passionate developer of algorithms, interested in psychology and development.

More from this author