Using branches in Stash

Configuring the branching model

Stash uses a 'branching model' to define the branch workflow for each repository. As a project administrator, configuring the model lets you:

enable the branch types that will be available in your workflow.
specify the naming convention to be used for each branch type.

The naming convention simply adds prefixes to branch names, so that branches of the same type get the same prefix.

To configure the branching model for a repository, go to Settings > Branching model for the repository and click Enable branching model.

Stash makes a number of branch types available, as described below. Use the checkboxes to enable just those branch types that map to your workflow. Note that several branch types have default branch naming prefixes (for example the default prefix for the 'feature' branch type is /feature), as shown:

Development

This is generally the integration branch for feature work and is often the default branch (e.g. master) or a named branch such as develop. In a workflow using pull requests, this is usually the branch where new feature branches are targeted. In other cases, developers might commit directly to this branch.

Feature

Feature branches are used for specific feature work or improvements. They generally branch from, and merge back into, the development branch, by means of pull requests. See Feature branch workflow.

/feature

Production

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

Release

Release branches are used for release task and long-term maintenance of software versions. Typically, they branch from, and fixes are merged back into, the development branch. Merging into an older release branch allows for automatic merging to newer release branches as well as the development branch.

/release

Bugfix

Bugfix branches are typically used to fix release branches.

/bugfix

Hotfix

Hotfix branches are used to quickly fix the 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

Creating branches

You can create a new branch when in JIRA (version 6.1 and above) or in Stash. Either way, you can override the settings that Stash suggests for the repository, branch type, branching point and branch name.

From a JIRA issue

JIRA must be connected with Stash by an application link for this functionality to be available.

When viewing an issue in JIRA of JIRA Agile, click Create Branch (under 'Development' – you'll need the 'View Development Tools' project permission in JIRA to see this):

Choose the SCM, if more than one is available, where you want to create the branch:

Stash suggests the Branch type and Branch name based on the JIRA issue type and summary. Change the settings suggested by Stash, if necessary:

From in Stash

In Stash, choose Create branch from the Actions menu when viewing the Files, Commits or Branches tabs, or when viewing a particular branch.

Stash suggests the Branch type and Branch name based on the JIRA issue type and summary. Change the settings suggested by Stash if necessary:

Creating the branch

You can specify:

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 point
the Branch name – the prefix is based on the branch type you selected, and as defined by the branching model. Note that the branch name should follow your team's convention for this.

Note that Stash suggests a Branch type based on the JIRA issue type, when a branching model is configured. The mapping is:

JIRA issue type	Stash branch type
Bug	Bugfix
Story	Feature
New Feature	Feature

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

Automating the branch workflow

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

As a project administrator you can turn on automatic merging for a particular repository. Go to Settings > Branching model for the repository, and select Enable automatic merging (under 'Automatic merge').

If Stash cannot perform an automatic merge, perhaps because branch permissions prevent it, Stash creates a new pull request for that merge, and the automatic merge operation stops, This allows you to 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 Stash determines the ordering of branches.

Managing all your branches

The Branches tab in Stash provides an overview of all the branches in the repository that you have permissions to view:

The Behind/Ahead column shows by how many commits a branch has diverged from the default branch (for example, master) for the repository, which can help you to identify work in progress as well as stale branches.

Icons in the Builds column indicate the status of the latest build results published to Stash by an integrated build server. 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.

Use the Actions menu to manage a particular branch in the repository:

When viewing a particular branch, the Action menu provides options relevant to just that branch:

Child pages