Branching offers a way to work on a new feature without affecting the main codebase. You can create a branch from Bitbucket, Jira Software, 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.

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 three ways to create a Git branch: In Bitbucket, at your local command line, or in Jira Software.

To create a branch 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, select a Type (if using the Branching model), enter a Branch name and click Create.


    Whenever you create a branch from Bitbucket or from an issue in Jira Software, Bitbucket removes characters that are invalid in references, file systems or shell, and replace them with a valid substitute.

  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.

To create a branch locally

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, you can do it locally or in Jira Software.

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

To create a branch from an issue in Jira Software

To create branches in Jira Software it must be connected with Bitbucket.

  1. In the Development panel, click Create Branch. This will open up Bitbucket's create branch screen.
    Image showing Create Branch under the Development heading
  2. Choose the repository where you want to create the branch.
  3. Select the Branch type and Branch name, then click Create branch. Bitbucket may suggest a Branch type based on the Jira Software issue type, when the branching model is configured. 

    See how the branching models and issue types are mapped...
    Jira Software issue typeBitbucket branch type


    (Feature if Bugfix type is not enabled)


    image showing the new branch types dropdown

  4. Once the new branch is created, Bitbucket takes you to the file listing. You can now pull to your local repository and switch to the new branch.

The branching model

You can use the branching model to define a branch based workflow for your repositories. When you map your workflow to branch types, you can ensure that branches are named consistently by configuring which branch types to make available. We've suggested some branch prefixes you might want to use but you can also specify your own naming convention. A consistent naming convention makes it easier to identify branches by type. You can also define which branches are your development and production branches, which allows us to better suggest source and target branches for creation and pull requests.

Branch types

There are several types of branches that are frequently used in software development. This section explains what each branch type is for, and the typical prefix convention for each branch type. In Bitbucket, the prefix can be changed for all branches other than development or production.

 Development branch

Usually the integration branch for feature work and is often the default branch or a named branch. For pull request workflows, the branch where new feature branches are targeted.


 Production branch

Used for deploying a release. Branches from, and merges back into, the development branch. In a Gitflow-based workflow it is used to prepare for a new production release. 


 Feature branch

Used for specific feature work or improvements. Generally branches from, and merges back into, the development branch, using pull requests.


 Release branch

Used for release tasks and long-term maintenance versions. They are branched from the development branch and then merged into the production branch.


 Bugfix branch

Typically used to fix Release branches.


 Hotfix branch

Used to quickly fix a Production branch without interrupting changes in the development branch. In a Gitflow-based workflow, changes are usually merged into the production and development branches.


Configure a repository's branching model

To configure the branching model for a repository (requires repository admin permission):

  1. Go to Repository settings
  2. Under Workflow select Branching model
  3. Choose the details of your repository branching model, then click Save

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:
    image showing commits show in relation to the branch
  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.
    image showing delete branch as the last option on the dropdown
  • When you create a pull request on a branch, pick the Close branch checkbox, which closes the branch when the pull request merges.
    image of the pull request dialogue box