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?

28 Archived comments

  1. User avatar


    I take it then that bitbucket does not support granular access to branches. I only want my Release Manager to have access to develop and master branches. 

    30 Jul 2012
    1. User avatar


      We do not support granular permissions on branches.   You could fork the repo and give the Release Manager access to the fork.  The fork can inherit or have its own permissions. As part of the release, you could ask the manager to pull incoming changes from the parent.  This off the top of my head. If that doesn't work for your use case please submit an issue to  

      30 Jul 2012
  2. User avatar


    In the git instructions for pushing a commit on the branch I actually had to switch back to the branch, to do the command git push origin feature.   When I checked out the master then attempted to do the push command I got this error: 

    fatal: 'origin' does not appear to be a git repository

    fatal: Could not read from remote repository.

    Please make sure you have the correct access rights and the repository exists.


    After checking the feature branch back out the push worked fine so I think steps 8 and step 9 need to be swapped.

    04 Mar 2013
    1. User avatar


      Edit to the above: Steps 7 and 8 need to be swapped

      04 Mar 2013
      1. User avatar


        Hi folks, 

        I retested the steps above and confirm they work in their current order. I was able to recreate problem you saw by removing the origin section from my .git/config:

        [remote "origin"]
        	url =
        	fetch = +refs/heads/*:refs/remotes/origin/*

        So, I don't think there is an issue with the instructions.  You can see if you have origin specified for the repository with this command:

        git remote -v
        05 Mar 2013
  3. User avatar


    Is there a way of closing a branch that has no commits to merge because you made your changes in another branch?

    15 Apr 2013
    1. User avatar


      Not through the GUI.  You'd need to remove the branch locally and push that back up to Bitbucket.

      19 Apr 2013
  4. User avatar


    I'm an hg branching n00b following the above using hg 2.2.2 on Debian.

    Couple of differences I notice in the above "Branch a Mercurial repo" section:

    • hg branch feature - this seems to switch the working area to the branch anyway, so the subsequent hg update branch isn't needed (in fact doesn't work; as I understand it, hg branch is used to select an existing branch too?)
    • The hg push of the new branch will need a hg push --new-branch else it will generate a "abort: push creates new remote branches" error.

    Maybe I just don't know what I'm doing though...

    30 Apr 2013
    1. User avatar


      Oh, modest one, you did know of course. My instructions were fubar. I've fixed them.  Thank you.  Let me know if  you spot anything else.

      30 Apr 2013
  5. User avatar


    There seems to be a missing step in the Mercurial column of the table at the top of this page.  After you do the "hg branch NAME" step you must "hg ci" to check-in the branch definition before you do the "hg push --new-branch".  I tried it without the "hg ci" step and it produced an error saying there was nothing to push.


    24 May 2013
    1. User avatar


      Note that in order for "hg ci" to work you may need to create a Mercurial.ini file in your home directory with

      ; editor used to enter commit logs, etc. Most text editors will work.
      editor = notepad
      username = <username>

      30 Jun 2013
  6. User avatar

    Will Moyer

    Is closing a branch the same as deleting the branch?

    10 Jul 2013
    1. User avatar


      Closing a branch will delete it 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.

      10 Jul 2013
      1. User avatar

        Will Moyer

        Thanks Mary!

        10 Jul 2013
  7. User avatar



    how to get rid of stale tags? I mean I have deleted tags from local and well as from remote, but I think the history exists and also the reference exists. so how to clean up?

    11 Oct 2013
  8. User avatar

    Jeff LeBrun


    My apologies but I'm new to git. Are there any detailed instructions (ideally a video or something with screenshots) explaining how to edit files locally and then push local files to a branch (not to the master repo)?  I'm unclear which directory I need to be in within Terminal and where I should be saving my edited files on my local machine.  I managed to do this correctly once but the last time I did it I pushed to the master directory instead of to the branch.

    30 Oct 2013
    1. User avatar


      Hi Jeff,

      Have you worked through out Bitbucket tutorial? It has very basic instructions for working with files locally.  

      Clone Your Git Repo and Add Source Files

      If you at least step through that page, it walks you through the basic workflow step-by-step with pictures and everything.


      30 Oct 2013
      1. User avatar

        Jeff LeBrun

        Thanks for the quick reply! I did work through that tutorial & it was helpful. I'm not having any problems cloning or working on the code.  Just pushing to a separate branch.  

        30 Oct 2013
        1. User avatar


          Jeff, you've discovered the hole in the docs safety net.  I need to fix this.  I'll try to give you a quick reference in lieu of the full enchilada.

          Before you start anything, make sure you've made your local clone. Then, choose the procedure below that best fits your situation.

          Creating and checking out a branch 

          If you want to push to your own branch, you should create it branch first.  To create a branch from Bitbucket, do the following:

          1. Go to the repository you want to branch.
          2. Press the Branch button.

            The create branch dialog appears. 
          3. Enter a name for your branch.
          4. Press Create.
            Bitbucket opens your branch in the Branches tab.  It also pops up a dialog with instructions for checking out your branch locally.

            If you have a local version of the repository already, you can immediately use this dialog to checkout your branch.  How you do that depends on if you are using the command line or SourceTree.  If the command line, you just need to copy the command, if SourceTree, go ahead and press the button.

          Checking out an existing branch 

          1. Go to the repository you want to branch.
          2. Click the Branches option from the application toolbar.
            The list of branches appears. 
          3. Click the branch you want to checkout.
            Bitbucket opens the branch view for that branch. 
          4. Click the Check out button.
            The system displays the Check out pop-up. 
          5. Use the command appropriate to your situation.

          How to push changes to a branch

          Git Mercurial
          git push origin branchname
          hg push --branch
          30 Oct 2013
          1. User avatar

            Jeff LeBrun

            Thanks, this worked!  I have been working from the command line.

            A couple things: Do you think would be beneficial to include the git add . & git commit steps prior to the push step (after editing the files locally)?  I know those are covered in other pages but it seems to be a normal part of the sequence.

            I had made the mistake of assuming that I would need to create a new folder on my local machine (e.g. I created a directory called repos/app/app-branch/ when it seems as if I should have been working within repos/app/app-master/

            Thanks again for the quick response!

            31 Oct 2013
            1. User avatar


              Glad that worked for you. I absolutely need to beef this up into a "real procedure." Shortly, I'll move everything I wrote here into its own page. I'll also take my time and test it all clearly.  In the mean time, I'm super happy you are own your way.

              31 Oct 2013
  9. User avatar

    Shawn Drake

    manthony, I used the "Close <branch> after the pull request is merged" option when issuing a pull request and got an unexpected result.... the feature branch still shows in the Branches list on BitBucket, but will give an error when I click on it or try to perform any actions on it, indicating that Git does, in fact, think it's been deleted. How would I go about removing it from the Branches list?

    Thanks for the assist!

    08 Nov 2013
    1. User avatar


      Hi Shawn, the data on the branch list is cached in our system.  So the list isn't automatically refreshed.  I'll update the documentation to clarify this behavior.

      08 Nov 2013
      1. User avatar

        Shawn Drake

        manthony - That makes perfect sense, and I see it is gone now. Thanks for the info!

        08 Nov 2013
  10. User avatar

    Philip Weaver

    Apparently bitbucket always creates a "created new branch" commit whenever you use the GUI to create a new branch. Is there anyway to disable this feature? I just want to create a branch without automatically adding a commit.

    19 Dec 2013
  11. User avatar

    Mustafa Arif

    How can I close a branch after the final pull request has already been merged? I don't want to delete it from git, just remove it from the UI.

    06 Mar 2014
  12. User avatar

    kama radski

    I have the following problem:

    i have Master branch and a Dev branch and i recently added another one called TA-17.

    I submitted all my commits to this branch merged it with Dev, and closed TA-17 branch.

    Then i commited twice something to Dev branch

    Now i created a new branch (from within JIRA) called TA-38 and made the first commit to it.

    In the commit history however i see that now all old commits from the start of TA-17 branch are in 2 branches in Dev and in TA-38, and TA-38 does not have a new branch in the tree-chart....

    What did i do wrong, and how can i fix it ? 

    07 Aug 2014
    1. User avatar

      Dan Stevens [Atlassian]

      Hello Kama,

      I apologize for the delayed response.

      If JIRA is creating new branches from Dev, and you merged the TA-17 branch before creating the new (TA-38) branch it would indeed have all the preceding commits. I'm not entirely sure why it would not also show a new branch in the tree, though it does look like I can see the T-38 branch at the merge point later on in the history.

      If you run a quick create experiment to see what JIRA create branch creates from ( I'm assuming you would like it to be the Dev branch) by creating an empty issue, then branch, then observe where the branch was created from, you'd have that knowledge.

      I don't know if that was at all helpful.


      27 Aug 2014
Powered by Confluence and Scroll Viewport