Skip to end of metadata
Go to start of metadata

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

GitMercurial
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 Featured branches.
    You'll see a list of commits by branch:
     

  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.

26 Comments

  1. Anonymous

    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. 

    1. 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 support@bitbucket.org.  

  2. Anonymous

    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.

    1. Anonymous

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

      1. 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 = https://restbrowser@bitbucket.org/restbrowser/mydvcsproject.git
        	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
  3. Anonymous

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

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

  4. Anonymous

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

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

  5. Anonymous

    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.

     

    1. Anonymous

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

      [ui]
      ; editor used to enter commit logs, etc. Most text editors will work.
      editor = notepad
      username = <username>@bitbucket.org

  6. Is closing a branch the same as deleting the branch?

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

  7. Anonymous

    Hi,

    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?

  8. Hi,

    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.

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

      Mary

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

        1. 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
          1. 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!

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

  9. 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!

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

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

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

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