Branching a Repository

Still need help?

The Atlassian Community is here for you.

Ask the community

Branching offers a way to work on a new feature without affecting the main codebase. You can create a branch from Bitbucket or from your terminal. After you make changes, you push your branch to Bitbucket so that you can get it reviewed with a pull request.

On this page:

Creating a branch

You can create branches on Git and Mercurial repositories. Git branches always have a name, but Mercurial has the concept of a branch and a named branch. For more information, Steve Losh's guide is a good resource explaining branching in the two systems.

Create a Git branch

There are two ways to create a Git branch. The first way is from Bitbucket.

  1. From the repository, click + in the global sidebar and select Create a branch under Get to work.
  2. From the popup that appears, enter a Branch name and click Create.
  3. After you create a branch, you need to check it out from your local system. Use the fetch and checkout commands that Bitbucket provides, similar to the following:

    $ git fetch && git checkout <feature>
  4. Make your changes locally and then add, commit, and push your changes to the <feature> branch:

    $ git add .
    $ git commit -m "adding a change from the feature branch"
    $ git push origin <feature>
  5. Click the Source page of your repository. You should see both the master and the <feature> branch in the branches dropdown. When you make commits to the feature branch, you'll see the files specific to that branch.

You can create a branch locally as long as you have a cloned version of the repo.

  1. From your terminal window, list the branches on your repository.

    $ git branch
    * master

    This output indicates there is a single branch, the master and the asterisk indicates it is currently active.

  2. Create a new feature branch in the repository

    $ git branch <feature_branch>
  3. Switch to the feature branch to work on it.

    $ git checkout <feature_branch>

    You can list the branches again with the git branch command.

  4. Commit the change to the feature branch:

    $ git add .
    $ git commit -m "adding a change from the feature branch"
  5. Switch back to the master branch.

    $ git checkout master
  6. Push the feature branch to Bitbucket:

    $ git push origin <feature_branch>
  7. View the Source page of your repository in Bitbucket. You should see both the master and the feature branch. When you select the feature branch, you see the Source page from that perspective. Select the feature branch to view its Recent commits.

Create a Mercurial branch

If you want to create a Mercurial branch, the best way to do it is locally.

  1. Create a new feature branch in the repository.

    $ hg branch <feature_branch>

    Nothing changes in the working directory. The branch command tells Mercurial the branch name to use with your next commit. If you use the hg branches command, you'll see you still only have the default branch.

  2. Edit files, add files, and commit in the working copy.

  3. Commit your changes.
  4. Run the hg branches command again.

    $ hg branches
    feature                     3159:6ab9a159fc43
    default                     3158:5b8b05432593 (inactive)
  5. Push the feature branch back to Bitbucket. To do so, you'll need to do a force push with hg push -f.

    $ hg push --<feature_branch>

Listing commits on a branch

Bitbucket maintains a list of commits by branch. The list shows only the open branches with pending commits ahead of master.  To view the commits associated with a particular branch, view your repository and do the following:

  1. Go to the Commits page.
  2. Choose Show all if All branches isn't already selected.
    You'll see a list of commits with branch tags to the right and a graph to the left:
  3. Click the commit tag link to drill down to its contents.

Closing a branch

It's important to prune branches from your repository on a regular basis. Closing a branch deletes the branch from the Bitbucket interface. It does nothing to the branch in your local repository. You must delete that using the command associated with Git or Hg as applicable.

You can close a branch in two ways:

  • From the Branches page of the repository, hover over the options link on the right side and pick Delete branch.
  • When you create a pull request on a branch, pick the Close branch checkbox, which closes the branch when the pull request merges.
Last modified on Jul 16, 2018

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.