When you have a multi-branch pipeline that checks out other sibling repositories, you may want to check out the matching branch from that sibling repository (assuming it exists) but fall back to the main branch if there is no matching branch.

This step lets you create a branch in the primary repository and then when you need downstream / upstream changes in the sibling repository you can just create a matching branch and it will be resolved automatically. For example:

// checkout the main source
dir('main'){
    // this will checkout the source repository that is driving the multi-branch pipeline
    checkout scm
}
// now checkout the tests
dir('tests'){
    // this will check if there is a branch with the same name as the current branch in
    // https://example.com/example.git and use that for the checkout, but if there is no
    // branch with the same name it will fall back to the master branch
    checkout resolveScm(source: git('https://example.com/example.git'), targets: [BRANCH_NAME,'master']
}
// rest of pipeline

The return value is the resolved SCM instance (or null if ignoring errors). Where the SCM implementation supports it, the SCM instance will be pinned to the current head revision of the resolved branch. This can be useful if, for example, you want to check out the resolved branch on multiple nodes because all the nodes will get the same revision.