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.

A Stash admin can configure the branching model for a repository, by going to Settings > Branching model for the repository and clicking Enable branching model. Note that for new repositories, the branching model is enabled by default, and uses the default branch prefixes.

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:

Note that:

• Prefixes can't be empty.
• Prefixes can't be longer that 30 characters.
• Prefixes can't overlap; for example PROD and PRODUCT would be overlapping prefixes.
• For Stash instances using Microsoft SQL Server, prefixes can't use non-ASCII characters. See  STASH-3884 - Getting issue details... STATUS .

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.

Create a branch 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 or 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:

Create a branch from within Stash

In Stash, choose Create branch from the sidebar.

Stash will suggest the Branch type and Branch name based on the JIRA issue type and summary. Notice that Stash displays the current build status beside the source branch picker. 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 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. 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:

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.

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 branch listing page makes it easy to keep track of all the branches in your repository.

Searching for branches

You can easily find branches by using the search at the top of the table. Furthermore, if you're using the Stash branch 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 (arrowed in the screenshot below) to change the base branch, and refer to the Behind/Ahead and Pull requests columns.

Reading the table

Behind/Ahead

The Behind/Ahead column shows by how many commits a branch has diverged from the 'base branch' (for example, master). Use the branch selector (arrowed in the screenshot below) to change the base branch.

Pull requests

The Pull requests column shows the most relevant status from the pull requests against each branch – click an icon to see details. The status is: 

• OPEN if there is at least one open pull request.
• MERGED if there are no open pull requests, and at least one pull request has been merged.
• DECLINED if there are no open or merged pull requests, and at least one pull request has been declined.

Builds

If you have an integrated build server, the Builds column shows the status of the latest build results published to Stash. 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

The Actions menus include tasks for working with branches:

• Check out in SourceTree
• Create a pull request
• Edit permissions
• Delete branch

Navigation

Choose Keyboard shortcuts from the Stash Help menu to see shortcuts to help you navigate quickly around the branch listing.

Checking on your branches

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.

• The Pull requests status helps you to track the review and merge work that still needs to be done and can help with branch cleanup. For example, in combination with the Behind/Ahead information, you can decide whether to remove a feature branch that has already been merged.
• The Behind/Ahead column can help you to identify work in progress as well as stale branches. It is calculated for each branch against the base branch.

Read more

• http://blogs.atlassian.com/2013/10/inside-atlassian-feature-branching-on-the-stash-team/