Branching 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 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
- From the repository, click + in the global sidebar and select Create a branch under Get to work.
- From the popup that appears, select a Type (if using the Branching model), enter a Branch name and click Create.
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>
Make your changes locally and then add, commit, and push your changes to the
$ git add .
$ git commit -m "adding a change from the feature branch"
$ git push origin <feature>
Click the Source page of your repository. You should see both 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.
From your terminal window, list the branches on your repository.
$ git branch
This output indicates there is a single branch, the
masterand the asterisk indicates it is currently active.
Create a new feature branch in the repository
$ git branch <feature_branch>
Switch to the feature branch to work on it.
$ git checkout <feature_branch>
You can list the branches again with the
Commit the change to the feature branch:
$ git add .
$ git commit -m "adding a change from the feature branch"
Switch back to the
$ git checkout master
Push the feature branch to Bitbucket:
$ git push origin <feature_branch>
View the Source page of your repository in Bitbucket. You should see both the
masterand 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.
Create a new feature branch in the repository.
$ hg branch <feature_branch>
Nothing changes in the working directory. The
branchcommand tells Mercurial the branch name to use with your next commit. If you use the
hg branchescommand, you'll see you still only have the
Edit files, add files, and commit in the working copy.
- Commit your changes.
hg branchescommand again.
$ hg branches
feature 3159:6ab9a159fc43 default 3158:5b8b05432593 (inactive)
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.
- In the Development panel, click Create Branch. This will open up Bitbucket's create branch screen.
- Choose the repository where you want to create the branch.
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 type Bitbucket branch type Bug
(Feature if Bugfix type is not enabled)
Story Feature Other Other/Custom
- 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.
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.
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.
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.
Used for release tasks and long-term maintenance versions. They branch from, and merge back into, the development 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):
- Go to Repository settings
- Under Workflow select Branching model
- 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:
- Go to the Commits page.
- 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:
- 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.