Mainline branch identification

When viewing a project's files, the initial view is the list of the project's branches. The branches appear in alphabetical order, but the branch identified as the main branch appears first and in bold. By default, a project overview page is displayed when there is a README Markdown file in the project mainline, this can be disabled by your Swarm administrator, see Project readme.

Swarm uses a list of names to identify which of a project branches should be considered as the main branch and which Markdown file is used for the project overview page. The mainlines array supports regular expressions, see Regular expressions. The default names are main, mainline, master, and trunk. For the steps Swarm goes through to find the mainline branch and the Markdown file for a project, see Project mainline and README check below.

Tip

The default main, mainline, master, and trunk names are hardcoded in Swarm, there is no need to add them to your array. Swarm will always try to find exact matches to them from your branch names.

Tip

If you make a configuration change, Swarm will not use it until the configuration cache has been reloaded, this forces Swarm to use the new configuration. You must be an admin or super user to reload the Swarm config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

You can adjust the configuration to match your local branch naming convention . Here is an example of the configuration block:

<?php
    // this block should be a peer of 'p4'
    'projects' => array(
        'mainlines' => array(
            'stable', 'release', // 'main', 'mainline', 'master', and 'trunk' are hardcoded, there is no need to add them to the array
        ),
    ),

Regular expressions

The mainlines array supports any valid PHP regular expression, this can be useful if you have a large number of similar branch names across different projects that you are using as your main branches. Regular expressions must be used with care to avoid accidentally including a branch that is not a mainline branch.

Note

Swarm adds a ^ character before your regular expression and a $ character after it. For example: ^your-reg-ex-pattern$ You must take this into account when constructing your regular expressions.

Tip
  • You can test the results of your regular expressions before using them, see regular expressions 101.
  • Regular expressions are case insensitive.

Regular expression examples

Useful regular expressions are shown below:

Exact match only:

'mymainbranch' branches named mymainbranch are treated as mainline branches.

Only match default mainlines array branch names:

'' (an empty mainlines array) only branches that exactly match the default names of 'main', 'mainline', 'master', or 'trunk' are treated as mainline branches.

Beginning with:

'stable.*' branch names beginning with stable are treated as mainline branches.

For example: the following are treated as mainline branches.

stablecode-01, stable2019_2, and stable_branchxyz

Ending with:

'.*mastprj' branch names ending with mastprj are treated as mainline branches.

For example: the following are treated as mainline branches.

productxy-mastprj, assets_mastprj, and project07mastprj

Ending with digits

'.*[0-9]+' branch names ending with digits are treated as mainline branches.

For example: the following are treated as mainline branches.

branch03, product-10, stable22, main_123456

Containing:

'.*main.*' branch names that contain main are treated as mainline branches.

For example: the following are treated as mainline branches.

swarm-main-branch, branchmain_22, main05, and assetmain-brnch

Project mainline and README check

Tip

Swarm checks the branches of a project in alphabetical order. 

Swarm uses the following process to find the mainline branch and README Markdown file for a project:

  1. Swarm searches the project branches in alphabetical order for a branch that matches a name in the mainlines array. The search includes the default names.
  2. When Swarm finds a matching branch, that branch is used as the mainline when displaying the branches on the project page.
    • If the branch contains a README Markdown file, that file is used for the project overview page.
    • If the branch does not contain a README Markdown file, see step 3.
  3. Swarm checks the remaining branches for a branch that matches a name in the mainlines array.
    • If Swarm finds a README file, that file is used for the project overview page and swarm stops checking the branches.
    • If a README file is not found, this step is repeated until a README file is found in a  in a branch that matches a name in the mainlines array or all of the project branches have been checked.
    • If no README Markdown page is found, the project overview page is not displayed.