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
35 minutes
Audience
You already understand the basic Git workflow
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.
Why branching matters
Branching is one of the best ways to get the most out of Git for version control. Branching in Git allows you to:
- Have several teams working from a single repository concurrently.
- Have team members anywhere in the world using Bitbucket Cloud to collaborate.
- Have multiple lines of development running at the same time independent of each other without needing code freezes.
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.
What is a fork?
Fork is another way of saving a clone or copy. The term fork (in programming) derives from a Unix system call that creates a copy of an existing process. So, unlike a branch, a fork is independent from the original repository. If the original repository is deleted, the fork remains. If you fork a repository, you get that repository and all of its branches.
1. Go to tutorials/tutorials.git.bitbucket.org
2. Click + > Fork this repository on the left side of the screen.
3. Modify the Name so it is unique to your team, then click Fork repository.
4. Create a directory for the repository which will be easy to navigate to. You might choose something like this:
SEE SOLUTION
Learn Git with Bitbucket Cloud
related material
Git commands
$ mkdir test-repositories $ cd test-repositories/ $ test-repositoriesThe preceding example creates the test-repositories directory using the mkdir (make directory) command and switches to that directory using the cd (change directory) command.
5. 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/This clones the repository using the git clone command and creates the directory the clone created mygittutorial.git.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.
1. Create a branch using the git branch command.
$ git branch test-12. Check out the branch you just created using the git checkout command.
$ git checkout test-1 Switched to branch 'test-1'3. List the branches you have locally using the git branch command.
$ git branch main * test-14. 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 5. Add that change.
git add editme.htmlNote: Your change isn't committed to the git history yet – it's in a "waiting" state. We learned about this in Saving changes.
6. 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(-)Note: Now the change is part of the git history as a single "commit." We learned about this in Saving changes.
7. 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-1You will see an error because the first time you push a new branch you created locally you have to designate that branch.
8. 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-1This tells the system that the origin repository is the destination of this new branch.
9. 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.
1. Go to your tutorial repository in Bitbucket and click Branches. You should see something like this:
2. Click Create branch, name the branch test-2, and click Create.
3. 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'4. Use the git branch command in your terminal. You should see a list of branches something like this:
$ git branch main test-1 * test-2The branch with the asterisk * is the active branch. This is critical to remember when you are working in any branching workflow.
5. 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 cleanYou can see what branch you're on and that the branch is currently up to date with your remote (origin) branch.
6. 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)One of the most important things to remember when working in branches is that you want to be sure the branch you're making changes to is the correct branch.
Push change and create a pull request
Now it's time to get your first change reviewed and merge the branch.
1. Click +> Create a pull request. You can see your test-1 branch as the source branch and main in the destination branch.
Because we created this repository by forking an existing repository the destination is set to the main branch of the repository we forked.
To correct this you will need to change the repository destination branch (the branch into which you will merge your changes) from tutorials/tutorials.git.bitbucket.org to your repository.
You would also add reviewers on your team to the pull request. Learn more about pull requests
2. Click Create pull request.
3. 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).
4. Click Approve in the top left of the page. Of course in a real pull request you'd have reviewers making comments
5. Click Merge.
6. (Optional) Update the Commit message with more details.
7. 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.
Learn more for details on these two types of merge strategies.
8. 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.
Why delete the branch?
Remember, branching in Git differs from SVN or similar version control systems by using a branches as both long running branches, like a main and development branch, and short term development branches like the examples we use in this tutorial. Because this is the case it's not a bad idea to delete local branches to keep your local environment cleaner.
Why pull main and merge it into test-2?
We're using this as an example of you working on a repository into which another team member is working. It's a good idea to pull changes into your working branch from time to time to prevent merge conflicts in pull requests.
1. 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 cleanYou can see you're on the branch you just used to make your change and that you don't have any changes. We're ready to get rid of that branch now that we've finished that work.
2. 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'.Notice that the message says you are up-to-date? This is only your local branch. We know this because we just merged a change into main and haven't pulled that change from the remote repository to our local system. That's what we'll do next.
3. 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(-)
What happened is that when you pull the changes from the remote repository git runs a fast-forward merge to integrate the changes you made. It also lists how many files and lines in that file changed.
4. 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)You can see that it deleted the branch and what the last commit hash was for that branch. This is the safe way to delete a branch because git won't allow you to delete the branch if it has uncommitted changes. You should be aware however that this won't prevent deleting changes which are committed to the git history but not merged into another branch.
5. 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'.6. 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(-)
It's important to remember the following:
- The active branch matters. If you want to merge main into test-2, you need 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 branch
This 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-branch
Use 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 changes
Work 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 reviewed
To 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 feedback
Now your teammates comment and approve. Resolve their comments locally, commit, and push changes to Bitbucket. Your updates appear in the pull request.
Merge your branch
Before 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 its 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.
Share this article
Next Topic
Recommended reading
Bookmark these resources to learn about types of DevOps teams, or for ongoing updates about DevOps at Atlassian.
Bitbucket blog
DevOps learning path
