Learn Branching with Bitbucket Cloud
Objective
This tutorial will teach you the basics of creating, working in, reviewing, and merging branches using Git and Bitbucket Cloud.
Time | Audience | Prerequisites |
---|---|---|
35 minutes | You already understand the basic Git workflow | You have installed Git |
You have a Bitbucket account |
This tutorial is for you if you already understand the basic Git workflow including how to:
- Clone: copying the remote repository in Bitbucket Cloud to your local system
- Add or stage: taking changes you have made and get them ready to add to your git history
- Commit: add new or changed files to the git history for the repository
- Pull: get new changes others have added to the repository into your local repository
- Push: get changes from your local system onto the remote repository
If you don't know the Git basics, don't worry just check out our Learn Git with Bitbucket Cloud tutorial and you'll be up to speed in no time.
Get set up
Since we want you to feel like you're working on a team, in a common Bitbucket repository, we will have you fork a public repository we have supplied.
- Go to tutorials/tutorials.git.bitbucket.org
- Click + > Fork this repository on the left side of the screen.
- Modify the Name so it is unique to your team, then click Fork repository.
- Create a directory for the repository which will be easy to navigate to. You might choose something like this:
$ mkdir test-repositories $ cd test-repositories/ $ test-repositories
- Clone the forked repository into the directory you just created. It might look something like this:
$ git clone https://dstevenstest@bitbucket.org/dstevenstest/mygittutorial.bitbucket.io.git Cloning into 'mygittutorial.bitbucket.io'... remote: Counting objects: 12392, done. remote: Compressing objects: 100% (12030/12030), done. remote: Total 12392 (delta 8044), reused 564 (delta 360) Receiving objects: 100% (12392/12392), 2.72 MiB | 701.00 KiB/s, done. Resolving deltas: 100% (8044/8044), done. $ cd mygittutorial.bitbucket.io/
Create a branch and change something using the branching workflow
You're going to add a quote on your website in this branch.
- Create a branch using the git branch command.
$ git branch test-1
- Check out the branch you just created using the git checkout command.
$ git checkout test-1 Switched to branch 'test-1'
- List the branches you have locally using the git branch command.
$ git branch main * test-1
- Make an update to the editme.html file by adding a quote. You can use something like the following:
This is a quote, and I like it.
A quote: The Art of Quoting - Add that change.
git add editme.html
- Commit the change with a descriptive commit message.
git commit editme.html -m'added a new quote' [test-1 063b772] added a new quote 1 file changed, 3 insertions(+), 3 deletions(-)
- Push that change to Bitbucket using the git push command.
git push fatal: The current branch test-1 has no upstream branch. To push the current branch and set the remote as upstream, use git push --set-upstream origin test-1
- Push the branch and change using the git push branch command.
$ git push origin test-1 Counting objects: 3, done. Delta compression using up to 8 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 363 bytes | 0 bytes/s, done. Total 3 (delta 2), reused 0 (delta 0) remote: remote: Create pull request for test-1: remote: https://bitbucket.org/dstevenstest/dans.git.bitbucket.org/pull-requests/new?source=test-1&t=1 remote: To https://bitbucket.org/dstevenstest/dans.git.bitbucket.org.git * [new branch] test-1 -> test-1
- Open your tutorial repository and click Branches. You should now see both the main and the test-1 branches. It should look something like this:

Create, fetch, and checkout a remote branch
When you're working in a team you'll likely have to pull or fetch branches which other team members create and push to Bitbucket. This example will give you some of the basics of creating and working with branches others create.
- Go to your tutorial repository in Bitbucket and click Branches. You should see something like this:
- Click Create branch, name the branch test-2, and click Create.
- Copy the git fetch command in the check out your branch dialog. It will probably look something like this:
$ git fetch && git checkout test-2 From https://bitbucket.org/dstevenstest/dans.git.bitbucket.org * [new branch] test-2 -> origin/test-2 Branch test-2 set up to track remote branch test-2 from origin. Switched to a new branch 'test-2'
- Use the git branch command in your terminal. You should see a list of branches something like this:
$ git branch main test-1 * test-2
- Use the git status command and you'll see something like this:
$ git status On branch test-2 Your branch is up-to-date with 'origin/test-2'. nothing to commit, working tree clean
- Use the git checkout command to change the focus back to your other branch. The command will look something like this:
$ git checkout test-1 Switched to branch 'test-1' Your branch is ahead of 'origin/test-1' by 3 commits. (use "git push" to publish your local commits)
Push change and create a pull request
Now it's time to get your first change reviewed and merge the branch.
- Click +> Create a pull request. You can see your test-1 branch as the source branch and main in the destination branch.
- Click Create pull request.
- Make a comment in the pull request by selecting a line in the diff (the area displaying the change you made to the editme.html file).
- Click Approve in the top left of the page. Of course in a real pull request you'd have reviewers making comments
- Click Merge.
- (Optional) Update the Commit message with more details.
- Select the Merge commit Merge strategy from the two options:
- Merge commit—Keeps all commits from your source branch and makes them part of the destination branch. This option is the same as entering git merge --no-ff in the command line.
- Squash—Combines your commits when you merge the source branch into the destination branch. This option is the same as entering git merge --squash in the command line.
- Click Commits and you will see how the branch you just merged fits into the larger scheme of changes.
Delete a branch and pull main into local working branch
Now you've gone through the basic branching workflow and your change is in main. The last thing we'll learn is how to delete the branch you just merged, pull the updated main branch, and merge the updated main branch into your test-2 branch.
- Open your terminal and run the git status command the result should look something like this:
$ git status On branch test-1 nothing to commit, working tree clean
- Switch to the main branch by running the git checkout main command. The result should look something like this:
git checkout main Switched to branch 'main' Your branch is up-to-date with 'origin/main'.
- Run the git pull command. The result should look something like this:
$ git pull remote: Counting objects: 1, done. remote: Total 1 (delta 0), reused 0 (delta 0) Unpacking objects: 100% (1/1), done. From https://bitbucket.org/dstevenstest/dans.git.bitbucket.org 2d4c0ab..dd424cb main -> origin/main Updating 2d4c0ab..dd424cb Fast-forward editme.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
- Run the git branch -d {branch_name} command to remove the test-1 branch. The result will look something like this:
$ git branch -d test-1 Deleted branch test-1 (was 063b772)
- Switch to the test-2 branch using the git checkout command.
$ git checkout test-2 Switched to branch 'test-2' Your branch is up-to-date with 'origin/test-2'.
- Merge the main branch into your working branch using the git merge main test-2 command. The result will look something like this:
$ git merge main test-2 Updating 2d4c0ab..dd424cb Fast-forward editme.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
- The active branch matters. If you want to merge main into test-2 you want to have test-2 checked out (active). The same is true if you want to merge test-2 into main you need to have main checked out.
- To see what branch is active at any time use git branch and the active branch will have an asterisk or use git status and it will tell you want branch you are on and if there are pending local changes.
We hope you've learned a bit about branching and the commands involved. Let's review what we just covered:
Review the branching workflow
The Git Feature Branch workflow is an efficient way to get working with your team in Bitbucket. In this workflow, all feature development takes place on branches separate from the main branch. As a result, multiple developers can work on their own features without touching the main code.
![]() | Start with the main branchThis workflow helps you collaborate on your code with at least one other person. As long as your Bitbucket and local repos are up-to-date, you're ready to get started. |
Create a new-branchUse a separate branch for each feature or issue you work on. After creating a branch, check it out locally so that any changes you make will be on that branch. | |
Update, add, commit, and push changesWork on the feature and make commits like you would any time you use Git. When ready, push your commits, updating the feature branch on Bitbucket. | |
Get your code reviewedTo get feedback on your code, create a pull request in Bitbucket. From there, you can add reviewers and make sure everything is good to go before merging. | |
Resolve feedbackNow your teammates comment and approve. Resolve their comments locally, commit, and push changes to Bitbucket. Your updates appear in the pull request. | |
Merge your branchBefore you merge, you may have to resolve merge conflicts if others have made changes to the repo. When your pull request is approved and conflict-free, you can add your code to the main branch. Merge from the pull request in Bitbucket. |
This tutorial is limited in it's ability to show how branches make teams more effective. There are several approaches to branching and we discuss some of these approaches in: Comparing workflows.