Branching a Repository

Branching offers a way to work on a new feature without affecting the main code line. You can branch on a local repository and make changes without ever making that branch visible in Bitbucket Cloud. Or you can push a branch up to Bitbucket so other repository users can access and work with your changes.

There are a number of ways to branch a repository this documentation only shows you the very basic ways to branch. Review your Git or Mercurial resources to get fancy with branching. From a Bitbucket perspective, you have to do some extra work to get a branch to appear:

Git Mercurial
Clone a repository to your local system. Clone a repository to your local system.
Create a branch on your local system.
git branch BRANCH_NAME

Create a named branch.
hg branch NAME

Push the branch to Bitbucket.
git push origin BRANCH_NAME

Push the repository to Bitbucket.
hg push --new-branch

Git branches always have a name. Mercurial has the concept of branch and named branch. (Steve Losh's guide is a good resource explaining branching in the two systems).

On this page:

Branch a Git repo

If you still have your bb101practice repository from the 101, you can try these operations directly on that.

  1. Open a terminal window on your local system.
  2. 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.

  3. Create a new feature branch in the repository

    $ git branch feature
  4. Switch to the feature branch to work on it.

    $ git checkout feature

    List the branches again with the git branch command.

  5. Edit the README file and add a new line.
  6. Commit the change to the feature branch:

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

    $ git checkout master
  8. Push the feature branch to Bitbucket.

    $ git push origin feature
  9. View the bb101repo Source page 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.

  10. Select the feature branch to view its Recent commits.

Branch a Mercurial repo

  1. Create a new feature branch in the repository.

    $ hg branch feature

    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 --new-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 is important to prune branches from your repository on a regular basis. You should close branches when you merge any final commits into the trunk with a  pull request. Simply choose to close the branch with the final pull request:

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.

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