Learn Branching with Bitbucket Cloud

Get set up Review the branching workflow

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.

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.

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
```
The preceding example creates the test-repositories directory using the mkdir (make directory) command and switches to that directory using the cd (change directory) command.

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/

Which 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.

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
  master
  * test-1
```

Make an update to the editme.html file by adding a quote. You can use something like the following:

<div class="quote">
  <blockquote>This is a quote, and I like it.</blockquote>
  <cite>A quote: The Art of Quoting</cite>
</div>

Add that change.
```
git add editme.html
```
Note: your change isn't committed to the Git history yet it's in a "waiting" state. We learned about this in Saving changes.
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 changes is part of the Git history as a single "commit" We learned about this in Saving changes.
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
```
You will see an error because the first time you push a new branch you created locally you have to designate that branch.

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

This tells the system that the origin repository is the destination of this new branch.

Open your tutorial repository and click Branches. You should now see both the master 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
  master
  test-1
* test-2
```
The branch with the asterisk * is the active branch. This is critical to remember when you are working in any branching workflow.
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
```
You can see what branch you're on and that the branch is currently up to date with your remote (origin) branch.
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.

Click +> Create a pull request. You can see your test-1 branch as the source branch and master in the destination branch.

Because we created this repository by forking an existing repository the destination is set to the master 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
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.
Learn more for details on these two types of merge strategies.
Click Commits and you will see how the branch you just merged fits into the larger scheme of changes.

Delete a branch and pull master into local working branch

Now you've gone through the basic branching workflow and your change is in master. The last thing we'll learn is how to delete the branch you just merged, pull the updated master branch, and merge the updated master 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 master 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 master 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.

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
```
You 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.
Switch to the master branch by running the git checkout master command. The result should look something like this:
```
git checkout master
Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.
```
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 master and haven't pulled that change from the remote repository to our local system. That's what we'll do next.

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 master -> origin/master
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.

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.

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 master branch into your working branch using the git merge master test-2 command. The result will look something like this:
```
$ git merge master 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 master into test-2 you want to have test-2 checked out (active). The same is true if you want to merge test-2 into master you need to have master 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 master branch. As a result, multiple developers can work on their own features without touching the main code.

Start with the master 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 master 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.