Branch a repository

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

There are three ways to create a Git branch: In Bitbucket, at your local command line, or in Jira.

To create a branch from Bitbucket

1. From the repository, select the Create button.

2. Select Branch from the dropdown menu.

3. From the popup that appears, select a Type (if using the Branching model), enter a Branch name and click Create.

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

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

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

6. Click the Source page of your repository. You should see both the main branch 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

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

   $ git checkout main

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

To create a branch from an issue in Jira

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

1. In the Development panel, click Create Branch. This will open up Bitbucket's create branch screen.

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 issue type, when the branching model is configured. 

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.

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 your main branch.  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.

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.
  

Bitbucket maintains a list of commits by branch. The list shows only the open branches with pending commits ahead of your main branch.  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.

3. Click the commit tag link to drill down to its contents.

Bulk-delete branches

You can delete branches in bulk by following these steps:

1. In your repository, select Branches on the left sidebar.

2. Click (…) > Delete multiple.

3. Check the branches you want to delete and click Delete selected branches.

4. Confirm your selection.