Using branches in Bitbucket Server
Bitbucket Data Center and Server makes it easy to use a branching workflow for your Git development process. This page describes how to use to use branches with Bitbucket.
On this page:
Creating a branch
You can create a new branch from within JIRA Software or in Bitbucket. Bitbucket suggests the Branch type and Branch name based on where you are creating the branch from in the application. You can change these values depending on your branching model.
When creating a branch, you will provide this information for each branch:
- the Repository
- the Branch type, if a branching model has been previously configured – choose Custom if you need an ad hoc branch type
- the Branch from point – you can choose either a branch or a tag.
- the Branch name – the prefix is based on the branch type you selected, and as defined by the branching model.
Create a branch from JIRA Software
To create a branch when viewing an issue in JIRA Software:
Must have JIRA Software version 6.1 or above, and it must be connected with Bitbucket by an application link.
- In the Development pane, click Create Branch (requires the View Development Tools project permission).
- Choose the SCM, if more than one is available, where you want to create the branch.
Select the Branch type and Branch name, then click Create branch. Bitbucket suggests a Branch type based on the JIRA Software issue type, when a branching model is configured.
- Once the new branch is created, Bitbucket takes you to the file listing for that. You can now pull to your local repository and switch to the new branch.
Create a branch from Bitbucket
To create a branch:
- In Bitbucket, choose Create branch from the sidebar.
- Select the Branch type and Branch name.
- Click Create branch. Once the new branch is created, Bitbucket takes you to the file listing for that. You can now pull to your local repository and switch to the new branch.
Configuring branching models
With Bitbucket you can use branching models to define a branch workflow for repositories. When you map your workflow to repository branches with a branching model, admins can guide developers to name branches consistently by configuring which branch types to make available. There are a number of branch types available, and several branch types have default branch naming prefixes (described below). You can also specify your own naming convention for each branch type. A consistent naming convention makes it easier to identify branches by type.
Branch types
Bitbucket comes with several types of branches that are frequently used in software development. This section explains what each branch type is for, and has the typical naming convention for the prefix for each branch type. The prefix can be changed for each branch type.
 Development branchUsually 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. | varies |
 Production branchUsed 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. | varies |
 Feature branchUsed for specific feature work or improvements. Generally branch from, and merge back into, the development branch using pull requests. See Feature branch workflow. | feature/ |
 Release branchUsed for release task and long-term maintenance versions. They branch from, and merge back into, the development branch. Merging into an older release branch can be configured to automatically merge to newer release branches, as well as the development branch. | release/ |
 Bugfix branchTypically used to fix Release branches. | bugfix/ |
 Hotfix branchUsed 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. | hotfix/
|
You can configure a branching model for either:
- a whole project, so that repositories within a project can inherit the same branching model, or
- an individual repository, to override a project's branching model.
Configure a project's branching model
New repositories will have the branching model enabled by default, and use the default branch prefixes.
- Enabled branch types can't have empty prefixes, have a 30 character limit, and can't overlap (for example PROD and PRODUCT would overlap).
To configure a branching model for a project (requires project admin permission):
- Go to Project settings > Branching model.
- Choose the details of branching model for repositories that inherit the project settings, then click Save.
Configure a repository's branching model
To configure the branching model for a repository (requires repository admin permission),
- Go to Repository settings > Branching model for a repository
- Under Project settings inheritance, select Use custom settings.
- Choose the details of your repository branching model, then click Save.
Automating the branch workflow
Bitbucket can automate some merges in the branch workflow, based on the branching model for the repository. This allows merges to be cascaded to newer branches of the same parent, subject to a few conditions, so reducing the need for manual maintenance of branches.
To enable automatic merge for a project or repository (requires repo/project admin permissions):
- Go to Settings > Branching model for a project or repository.
- Under Automatic merge, check Enable automatic merging.
- Click Save.
If Bitbucket cannot perform an automatic merge, perhaps because of a conflict, it creates a new pull request for that merge, and the automatic merge operation stops. You should then resolve the conflict locally before approving the new pull request, which may involve further cascading merges.
See Automatic branch merging for more information about the conditions for automatic merging, and how Bitbucket determines the ordering of branches.
Finding and managing branches
The branch listing page makes it easy to keep track of all the branches in your repository, to get there just select Branches from the side navigation bar.
The branch listing allows you to:
- See how many commits behind or ahead your branch is compared to a chosen 'base branch'.
- See the latest status for pull requests originating from branches.
- See the build status of branches at a glance.
- Track the review and merge work that still needs to be done and can help with branch cleanup.
- Identify work in progress as well as stale branches. It is calculated for each branch against the base branch.
| Behind/Ahead | Shows by how many commits a branch has diverged from the (default) 'base branch'. Use the branch selector to change the base branch. |
|---|---|
| Pull requests | Shows the relevant state of pull requests against each branch – click the status to see detailed pull request information.
|
* Builds | Shows the status of the latest build results published to Bitbucket. The overall status is 'passed' if all the different builds (for example, unit tests, functional tests, deploy to staging) succeeded and 'failed' if at least one run failed for any of those. Click an icon to see details of the builds. |
| Actions | Menu that includes tasks for working with branches. |
* Only if you have an integrated build server.
Search for branches
You can easily find branches by using the search at the top of the table on the Branches screen. If you're using a branching model, you can filter by branch type simply by searching for the prefix – for example, search for "feature/" to see all your feature branches.
You can find the feature and bugfix branches that haven't yet been merged into a particular release (for example, "release/2.10") by changing the 'base branch' – just use the branch selector to change the base branch, and refer to the Behind/Ahead and Pull requests columns.