Git Plugin

Checkout to specific local branch

Branch name

If given, checkout the revision to build as HEAD on the named branch. If value is an empty string or "**", then the branch name is computed from the remote branch without the origin. In that case, a remote branch 'origin/master' will be checked out to a local branch named 'master', and a remote branch 'origin/develop/new-feature' will be checked out to a local branch named 'develop/new-feature'. If a specific revision and not branch HEAD is checked out, then 'detached' will be used as the local branch name.

Wipe out repository and force clone

Delete the contents of the workspace before build and before checkout. Deletes the git repository inside the workspace and will force a full clone.

Clean after checkout

Clean the workspace after every checkout by deleting all untracked files and directories, including those which are specified in .gitignore. Resets all tracked files to their versioned state. Ensures that the workspace is in the same state as if clone and checkout were performed in a new workspace. Reduces the risk that current build will be affected by files generated by prior builds. Does not remove files outside the workspace (like temporary files or cache files). Does not remove files in the .git repository of the workspace.

Delete untracked nested repositories

Remove subdirectories which contain .git subdirectories if this option is enabled. This is implemented in command line git as git clean -xffd. Refer to the Clean before checkout

Clean before checkout

Clean the workspace before every checkout by deleting all untracked files and directories, including those which are specified in .gitignore. Resets all tracked files to their versioned state. Ensures that the workspace is in the same state as if cloned and checkout were performed in a new workspace. Reduces the risk that current build will be affected by files generated by prior builds. Does not remove files outside the workspace (like temporary files or cache files). Does not remove files in the .git repository of the workspace.

Delete untracked nested repositories

Remove subdirectories which contain .git subdirectories if this option is enabled. This is implemented in command line git as git clean -xffd. Refer to the Sparse checkout paths

Sparse checkout paths

Specify the paths that you’d like to sparse checkout. This may be used for saving space (Think about a reference repository). Be sure to use a recent version of Git, at least above 1.7.10.

Multiple sparse checkout path values can be added to a single job.

Path

File or directory to be included in the checkout

checkout scmGit(
 branches: [[name: 'master']],
 extensions: [
 sparseCheckout(sparseCheckoutPaths: [[path: 'src'], [path: 'Makefile']])
 ],
 userRemoteConfigs: [[url: 'https://github.com/jenkinsci/git-plugin.git']])

Git LFS pull after checkout

Git LFS pull after checkout

Enable Changelog Extensions

The plugin can calculate the source code differences between two builds. Changelog extensions adapt the changelog calculations for different cases.

Calculate changelog against a specific branch

Calculate changelog against a specific branch

'Calculate changelog against a specific branch' uses the specified branch to compute the changelog instead of computing it based on the previous build. This extension can be useful for computing changes related to a known base branch, especially in environments which do not have the concept of a "pull request".

Name of repository

Name of the repository, such as 'origin', that contains the branch.

Name of branch

Name of the branch used for the changelog calculation within the named repository.

Use commit author in changelog

Use commit author in changelog

The default behavior is to use the Git commit’s "Committer" value in build changesets. If this option is selected, the git commit’s "Author" value is used instead.

Tagging Extensions

Tagging extensions allow the plugin to apply tags in the current workspace.

Create a tag for every build

Create a tag for every build

Create a tag in the workspace for every build to unambiguously mark the commit that was built. You can combine this with Git publisher to push the tags to the remote repository.

Build Initiation Extensions

The git plugin can start builds based on many different conditions. The build initiation extensions control the conditions that start a build. They can ignore notifications of a change or force a deeper evaluation of the commits when polling

Don’t trigger a build on commit notifications

Do not trigger a build on commit notifications

If checked, this repository will be ignored when the notifyCommit URL is accessed whether the repository matches or not.

Force polling using workspace

Force polling using workspace

The git plugin polls remotely using ls-remote when configured with a single branch (no wildcards!). When this extension is enabled, the polling is performed from a cloned copy of the workspace instead of using ls-remote.

If this option is selected, polling will use a workspace instead of using ls-remote.

By default, the plugin polls by executing a polling process or thread on the Jenkins controller. If the Jenkins controller does not have a git installation, the administrator may enable JGit to use a pure Java git implementation for polling. In addition, the administrator may need to disable command line git to prevent use of command line git on the Jenkins controller.

Polling ignores commits from certain users

Polling ignores commits from certain users

These options allow you to perform a merge to a particular branch before building. For example, you could specify an integration branch to be built, and to merge to master. In this scenario, on every change of integration, Jenkins will perform a merge with the master branch, and try to perform a build if the merge is successful. It then may push the merge back to the remote repository if the Git Push post-build action is selected.

Excluded Users

If set and Jenkins is configured to poll for changes, Jenkins will ignore any revisions committed by users in this list when determining if a build should be triggered. This can be used to exclude commits done by the build itself from triggering another build, assuming the build server commits the change with a distinct SCM user. Using this behavior prevents the faster git ls-remote polling mechanism. It forces polling to require a workspace, as if you had selected the Force polling using workspace extension.

Each exclusion uses exact string comparison and must be separated by a new line.
User names are only excluded if they exactly match one of the names in this list.

Polling ignores commits in certain paths

Polling ignores commits in certain paths

If set and Jenkins is configured to poll for changes, Jenkins will pay attention to included and/or excluded files and/or folders when determining if a build needs to be triggered.

Using this behavior will preclude the faster remote polling mechanism, forcing polling to require a workspace thus sometimes triggering unwanted builds, as if you had selected the Force polling using workspace extension as well. This can be used to exclude commits done by the build itself from triggering another build, assuming the build server commits the change with a distinct SCM user. Using this behavior will preclude the faster git ls-remote polling mechanism, forcing polling to require a workspace, as if you had selected the Force polling using workspace extension as well.

Included Regions

Each inclusion uses java regular expression pattern matching, and must be separated by a new line. An empty list implies that everything is included.

Excluded Regions

Each exclusion uses java regular expression pattern matching, and must be separated by a new line. An empty list excludes nothing.

Polling ignores commits with certain messages

Polling ignores commits with certain messages

Excluded Messages

If set and Jenkins is set to poll for changes, Jenkins will ignore any revisions committed with message matched to the regular expression pattern when determining if a build needs to be triggered. This can be used to exclude commits done by the build itself from triggering another build, assuming the build server commits the change with a distinct message. You can create more complex patterns using embedded flag expressions.

Strategy for choosing what to build

Strategy for choosing what to build

When you are interested in using a job to build multiple branches, you can choose how Jenkins chooses the branches to build and the order they should be built.

This extension point in Jenkins is used by many other plugins to control the job as it builds specific commits. When you activate those plugins, you may see them installing a custom build strategy.

Ancestry

Maximum Age of Commit

The maximum age of a commit (in days) for it to be built. This uses the GIT_COMMITTER_DATE, not GIT_AUTHOR_DATE

Commit in Ancestry

If an ancestor commit (SHA-1) is provided, only branches with this commit in their history will be built.

Default

Build all the branches that match the branch name pattern.

Inverse

Build all branches except for those which match the branch specifiers configure above. This is useful, for example, when you have jobs building your master and various release branches and you want a second job which builds all new feature branches. For example, branches which do not match these patterns without redundantly building master and the release branches again each time they change.

First build changelog

First build changelog

The Jenkins git plugin provides an option to trigger a Pipeline build on the first commit on a branch. By default, no changelog is generated for the first build because the first build has no predecessor build for comparison. When the first build changelog option is enabled, the most recent commit will be used as the changelog of the first build.

checkout scmGit(
 branches: [[name: 'master']],
 extensions: [ firstBuildChangelog() ],
 userRemoteConfigs: [[url: 'https://github.com/jenkinsci/git-plugin.git']])

Merge Extensions

The git plugin can optionally merge changes from other branches into the current branch of the agent workspace. Merge extensions control the source branch for the merge and the options applied to the merge.

Merge before build

Merge before build

These options allow you to perform a merge to a particular branch before building. For example, you could specify an integration branch to be built, and to merge to master. In this scenario, on every change of integration, Jenkins will perform a merge with the master branch, and try to perform a build if the merge is successful. It then may push the merge back to the remote repository if the Git Publisher post-build action is selected.

Name of repository

Name of the repository, such as origin, that contains the branch. If left blank, it’ll default to the name of the first repository configured.

Branch to merge to

The name of the branch within the named repository to merge to, such as master.

Merge strategy

Merge strategy selection. Choices include:

• default

• resolve

• recursive

• octopus

• ours

• subtree

• recursive_theirs

Fast-forward mode

• --ff: fast-forward which gracefully falls back to a merge commit when required

• -ff-only: fast-forward without any fallback

• --no-ff: merge commit always, even if a fast-forward would have been allowed

Custom user name/e-mail address

Custom user name/e-mail address

user.name

Defines the user name value which git will assign to new commits made in the workspace. If given, the environment variables GIT_COMMITTER_NAME and GIT_AUTHOR_NAME are set for builds and override values from the global settings.

user.email

Defines the user email value which git will assign to new commits made in the workspace. If given, the environment variables GIT_COMMITTER_EMAIL and GIT_AUTHOR_EMAIL are set for builds and override values from the global settings.

Deprecated Extensions

Custom SCM name - Deprecated

Unique name for this SCM. Was needed when using Git within the Multi SCM plugin. Pipeline is the robust and feature-rich way to checkout from multiple repositories in a single job.

Submodule Combinator - Removed

An experiment was created many years ago that attempted to create combinations of submodules within the Jenkins job. The experiment was never available to Freestyle projects or other legacy projects like multi-configuration projects. It was visible in Pipeline, configuration as code, and JobDSL.

The implementation of the experiment has been removed. Dependabot and other configuration tools are better suited to evaluate submodule combinations.

There are no known uses of the submodule combinator and no open Jira issues reported against the submodule combinator. Those who were using submodule combinator should remain with git plugin versions prior to 4.6.0.

The submodule combinator ignores any user provided value of the following arguments to git’s checkout scm:

doGenerateSubmoduleConfigurations

A boolean that is now always set to false. Submodule configurations are no longer evaluated by the git plugin.

submoduleCfg

A list of submodule names and branches that is now always empty. Submodule configurations are no longer evaluated by the git plugin.

Previous Pipeline syntax looked like this:

checkout([$class: 'GitSCM',
 branches: [[name: 'master']],
 doGenerateSubmoduleConfigurations: false,
 extensions: [],
 submoduleCfg: [],
 userRemoteConfigs: [[url: 'https://github.com/jenkinsci/git-plugin.git']]])

Current Pipeline Syntax looks like this:

checkout scmGit(
 branches: [[name: 'master']],
 userRemoteConfigs: [[url: 'https://github.com/jenkinsci/git-plugin.git']])

Environment Variables

Properties

$ mkdir multirepository-cache.git
$ cd multirepository-cache.git
$ git init --bare
$ git remote add parent https://github.com/jenkinsci/git-plugin
$ git remote add child-1 https://github.com/jenkinsci/git-client-plugin
$ git remote add child-2 https://github.com/jenkinsci/platformlabeler-plugin
$ git fetch --all