×
Find plugins

Git
4.0.0Minimum Jenkins requirement: 2.138.4ID: git

Introduction

Git logo

The git plugin provides fundamental git operations for Jenkins projects. It can poll, fetch, checkout, branch, list, merge, and tag repositories.

Changelog in GitHub Releases

Release notes are recorded in GitHub Releases beginning July 1, 2019 (git plugin 3.10.1 and later). Prior release notes are recorded in the git plugin repository change log.

Configuration

Using Credentials

The git plugin supports username / password credentials and private key credentials provided by the Jenkins credentials plugin. Select credentials from the job definition drop down menu or enter their identifiers in Pipeline job definitions.

Enabling JGit

See the git client plugin documentation for instructions to enable JGit. JGit becomes available throughout Jenkins once it has been enabled.

Extensions

Extensions add new behavior or modify existing plugin behavior for different uses. Extensions help users more precisely tune the plugin to meet their needs.

Extensions include:

Clone Extensions

Advanced clone behaviours

Advanced clone behaviors modify the git clone and git fetch commands. They control:

  • breadth of history retrieval (refspecs)

  • depth of history retrieval (shallow clone)

  • disc space use (reference repositories)

  • duration of the command (timeout)

  • tag retrieval

Advanced clone behaviors include:

Honor refspec on initial clone

Perform initial clone using the refspec defined for the repository. This can save time, data transfer and disk space when you only need to access the references specified by the refspec. If this is not enabled, then the plugin default refspec includes all remote branches.

Shallow clone

Perform a shallow clone by requesting a limited number of commits from the tip of the requested branch(es). Git will not download the complete history of the project. This can save time and disk space when you just want to access the latest version of a repository.

Shallow clone depth

Set shallow clone depth to the specified numebr of commits. Git will only download depth commits from the remote repository, saving time and disk space.

Path of the reference repo to use during clone

Specify a folder containing a repository that will be used by git as a reference during clone operations. This option will be ignored if the folder is not available on the agent.

Timeout (in minutes) for clone and fetch operations

Specify a timeout (in minutes) for clone and fetch operations.

Fetch tags

Deselect this to perform a clone without tags, saving time and disk space when you want to access only what is specified by the refspec, without considering any repository tags.

Checkout Extensions

Advanced checkout behaviors

Advanced checkout behaviors modify the git checkout command. Advanced checkout behaviors include

Timeout (in minutes) for checkout operation

Specify a timeout (in minutes) for checkout. The checkout is stopped if the timeout is exceeded. Checkout timeout is usually only required with slow file systems or large repositories.

Advanced sub-modules behaviours

Advanced sub-modules behaviors modify the git submodule commands. They control:

  • depth of history retrieval (shallow clone)

  • disc space use (reference repositories)

  • credential use

  • duration of the command (timeout)

  • concurrent threads used to fetch submodules

Advanced sub-modules include:

Disable submodules processing

Ignore submodules in the repository.

Recursively update submodules

Retrieve all submodules recursively. Without this option, submodules which contain other submodules will ignore the contained submodules.

Update tracking submodules to tip of branch

Retrieve the tip of the configured branch in .gitmodules.

Use credentials from default remote of parent repository

Use credentials from the default remote of the parent project. Submodule updates do not use credentials by default. Enabling this extension will provide the parent repository credentials to each of the submodule repositories. Submodule credentials require that the submodule repository must accept the same credentials as the parent project. If the parent project is cloned with https, then the authenticated submodule references must use https as well. If the parent project is cloned with ssh, then the authenticated submodule references must use ssh as well.

Shallow clone

Perform shallow clone of submodules. Git will not download the complete history of the project, saving time and disk space.

Shallow clone depth

Set shallow clone depth for submodules. Git will only download recent history of the project, saving time and disk space.

Path of the reference repo to use during submodule update

Folder containing a repository that will be used by git as a reference during submodule clone operations. This option will be ignored if the folder is not available on the agent running the build. A reference repository may contain multiple subprojects. See the combining repositories section for more details.

Timeout (in minutes) for submodule operations

Specify a timeout (in minutes) for submodules operations. This option overrides the default timeout.

Number of threads to use when updating submodules

Number of parallel processes to be used when updating submodules. Default is to use a single thread for submodule updates

Checkout to a sub-directory

Checkout to a subdirectory of the workspace instead of using the workspace root.

This extension should not be used in Jenkins Pipeline (either declarative or scripted). Jenkins Pipeline already provides standard techniques for checkout to a subdirectory. Use ws and dir in Jenkins Pipeline rather than this extension.

Local subdirectory for repo

Name of the local directory (relative to the workspace root) for the git repository checkout. If left empty, the workspace root itself will be used.

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/newfeature'.

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.

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.

Git LFS pull after checkout

Enable git large file support for the workspace by pulling large files after the checkout completes. Requires that the master and each agent performing an LFS checkout have installed the git lfs command.

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' 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

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

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.

Don’t trigger a build on commit notifications

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

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.

Merge Extensions

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 Push 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

user.name

Defines the user name value which git will assign to new commits made in the workspace. If given, git config user.name [this] is called before builds. This overrides 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, git config user.email [this] is called before builds. This overrides whatever is in the global settings.

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 behaviour prevents the faster git ls-remote polling mechanism. It forces polling to require a workspace, as if you had selected the xxxx Force polling using workspace extension.

Each exclusion uses literal pattern matching, and must be separated by a new line.

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 behaviour 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 behaviour 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

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.

Prune stale remote tracking branches

Runs git remote prune for each remote to prune obsolete local branches.

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

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 (sha1) is provided, only branches with this commit in their history will be built.

Default

Build all the branches that match the branch namne 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.

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.

Environment Variables

The git plugin assigns values to environment variables in several contexts. Environment variables are assigned in Freestyle, Pipeline, Multibranch Pipeline, and Organization Folder projects.

Branch Variables

GIT_BRANCH

Name of branch being built including remote name, as in origin/master

GIT_LOCAL_BRANCH

Name of branch being built without remote name, as in master

Commit Variables

GIT_COMMIT

SHA1 of the commit used in this build

GIT_PREVIOUS_COMMIT

SHA1 of the commit used in the preceding build of this project

GIT_PREVIOUS_SUCCESSFUL_COMMIT

SHA1 of the commit used in the most recent successful build of this project

System Configuration Variables

GIT_URL

Remote URL of the first git repository in this workspace

GIT_URL_n

Remote URL of the additional git repositories in this workspace (if any)

GIT_AUTHOR_EMAIL

Author e-mail address that will be used for new commits in this workspace

GIT_AUTHOR_NAME

Author name that will be used for new commits in this workspace

GIT_COMMITTER_EMAIL

Committer e-mail address that will be used for new commits in this workspace*

GIT_COMMITTER_NAME

Committer name that will be used for new commits in this workspace

Properties

Some git plugin settings can only be controlled from command line properties set at Jenkins startup.

Default timeout

The default git timeout value (in minutes) can be overridden by the org.jenkinsci.plugins.gitclient.Git.timeOut property (see JENKINS-11286) ). The property should be set on the master and on all agents to have effect (see JENKINS-22547).

Combining repositories

A single reference repository may contain commits from multiple repositories. For example, if a repository named parent includes references to submodules child-1 and child-2, a reference repository could be created to cache commits from all three repositories using the commands:

$ 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

Those commands will create a single bare repository which includes the current commits from all three repositories. If that reference repository is used in the advanced clone options clone reference repository, it will reduce data transfer and disc use for the parent repository. If that reference repository is used in the submodule options clone reference repository, it will reduce data transfer and disc use for the submodule repositories.

Bug Reports

Report issues and enhancements in the Jenkins issue tracker.

Contributing to the Plugin

Refer to contributing to the plugin for contribution guidelines. Refer to plugin development priorities for the prioritized list of development topics.

ArchivesGet past versions
Links
Labels

Previous Security Warnings