Great question—this is a super common point of confusion because at first glance, it seems to contradict how Git works (since Git can only have one branch checked out in a working directory at a time). Let’s break down what this configuration actually does, from a Git perspective:

Key Background First #

Git itself never checks out multiple branches simultaneously—your working directory will always reflect exactly one branch (or a detached HEAD state) at any given moment. Jenkins' multi-branch setting in the checkout step doesn’t change this fundamental behavior. Instead, it’s a Jenkins-level abstraction for a few specific use cases:

1. Fallback Branch Selection #

The most common use case is defining ordered fallback branches. Jenkins will attempt to check out the branches in the order you list them:

• First, it tries to fetch and checkout release-1.2 from the remote.
• If that branch doesn’t exist (e.g., it was deleted, or you made a typo), it falls back to checking out master next.

From Git’s perspective, this just means Jenkins runs two separate git fetch/git checkout attempts under the hood (stopping at the first successful one). Your working directory will only ever have the content of one branch.

2. SCM Polling for Multiple Branches #

If you’ve configured Jenkins to poll your SCM for changes, listing multiple branches tells Jenkins to monitor all of them for new commits. Any new push to release-1.2 OR master will trigger a build.

Again, Git is just being used to check the commit history of each branch individually during polling. When the build runs, Jenkins still only checks out one branch (using the fallback logic mentioned above).

3. Compatibility with Git Extensions #

In some cases, multiple branch definitions work with Jenkins Git extensions to support advanced workflows. For example:

• If you’re using extensions that handle branch merging or comparison, Jenkins might need to know about multiple branches to perform those operations (but the working directory still only holds one branch’s content).
• Some extensions use the branch list to fetch additional refs from the remote, even if they aren’t checked out immediately.

Example Breakdown #

Looking at your sample code:

checkout([$class: 'GitSCM', branches: [[name: 'release-1.2'], [name: 'master']], doGenerateSubmoduleConfigurations: false, extensions: [], submoduleCfg: [], userRemoteConfigs: [[]] ])

Here’s the play-by-play:

1. Jenkins connects to the remote Git repo specified in userRemoteConfigs.
2. It tries to fetch the release-1.2 ref and check it out into the working directory.
3. If that fails (branch not found, permission issues, etc.), it repeats the process with master.
4. Once a branch is successfully checked out, Git operates exactly as it would if you’d run git checkout <branch> manually—your working directory reflects that single branch.

Important Note #

If you need to work with multiple branches’ content in a single build, this configuration won’t help you. Instead, you’d need to:

• Run separate checkout steps for each branch (into different directories, using the local extension).
• Use git fetch to pull all remote branches, then manually switch between them or check out specific commits.

内容的提问来源于stack exchange，提问作者Bernie Lenz