Branching a Repository

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. Click Create branch in the left panel.
  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_name>
  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_branch>
  5. 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.

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. Merge changes from the <feature_branch> into the master branch:

    $ git merge <feature_branch>
  7. Push the feature branch to Bitbucket:

    $ git push origin <feature_branch>
  8. 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, creating it locally is the best way to do it.

  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, etc, 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.

    $ hg push --<feature_branch>

Viewing Commits by 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.
    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.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport