Jenkins : Git Client Plugin

Plugin Information
View Git client on the plugin site for more information.

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

Official Documentation

'Shared library plugin for other Git related Jenkins plugins.

Usage

Plugin provides a builder-style factory to retrieve a GitClient:

GitClient git = Git.with(listener, environment)
   .in(repository)
   .using(gitExe)
   .getClient();

Using "jgit" will force use of JGit implementation.

Gotchas

GIT_ASKPASS and permissions

The Git Client plugins uses GIT_ASKPASS and creates a temporary script to execute when git prompts for credentials. This approach requires that the user running Jenkins or the Agent has the sufficient permissions (read/write/execute) on the temp folder.

This has always been true for SSH Authentication. It however has not always been the case for HTTP/s authentication. Since version 2.0.0, the Git Client plugin now uses GIT_ASKPASS for Username/Password credentials too. See the detailed explanation in this commit. If you are upgrading to this version ensure that the temporary folder permissions are configured accordingly.

Insufficient permissions on the temp folder would make git commands fail with a stacktrace similar to the following:

hudson.plugins.git.GitException: Command "/usr/local/bin/git fetch --tags --progress https://github.com/user/repo.git +refs/heads/*:refs/remotes/origin/*" returned status code 128:
stdout:
stderr: fatal: cannot exec '/tmp/pass4619352834734512307.sh': Permission denied
fatal: could not read Username for 'https://github.com': No such device or address

Note: If security on the default temp folder is a concern, note that you can change the location of the temp folder in Jenkins via the system property `java.io.tmpDir`as explained in here. This would need to be done on the Jenkins master and the Agents.

Change Log - Moved to GitHub

2.8.0 (June 16, 2019)

Require Java 8
Require Jenkins 2.121 or later
Use JGit 4.5.7 (rather than JGit 4.5.5)

3.0.0-beta9 (April 24, 2019)

Require Java 8
Require Jenkins 2.60
Use JGit 5.3.0 instead of JGit 4.5.4 (many bug fixes, more consistent with command line git, includes git protocol 2 support)
Add optional submodule delete when cleaning (JENKINS-26660)
Add optional parallel submodule update support (JENKINS-44720)
Add optional shallow submodule update support (JENKINS-21248)
Always log the timeout for a CliGit command (JENKINS-52891)
Add test utility for use by git plugin test automation
Fix openPackedFromSelfOrAlternate stack overflow in JGit (JENKINS-46344)
Use distinctive file name prefix for temporary files (JENKINS-48258)
Fix clean before checkout with specific JGit directory and file name patterns (JENKINS-43198)
Use ssh username from git URL instead of passed username (OpenSSH 7.7 fix) (JENKINS-50573, JENKINS-52721 , JENKINS-52678 )
Avoid 'text file busy' random ssh clone failures (JENKINS-48258)
Use NTLM as Windows fallback authentication in JGit (JGit fix) (JENKINS-37934)
Allow shell special characters in passwords (JENKINS-47514)
Prevent 'Could not initialize class ... MasterComputer' in withRepository() remote call (JENKINS-49402, JENKINS-50019, JENKINS-53279)

2.7.7 (April 11, 2019)

Use JGit 4.5.5 (rather than JGit 4.5.4)
Automated test extension to better support git plugin test automation

2.7.6 (January 10, 2019)

Part 2 - Adapt to CLI git 2.20 tag update behavior change (JENKINS-55284)

2.7.5 (December 22, 2018)

Adapt to CLI git 2.20 tag update behavior change (JENKINS-55284)

2.7.4 (November 16, 2018)

Prevent 'Could not initialize class ... MasterComputer' in withRepository() remote call (JENKINS-49402, JENKINS-50019, JENKINS-53279)

2.7.3 (July 24, 2018)

Adapt to OpenSSH 7.7 behavior change for command line arguments, as seen in Windows git 2.17.0, Debian Buster, Alpine Linux 3.8 and OpenBSD 6.3 (JENKINS-50573, JENKINS-52721, JENKINS-52678)

2.7.2 (May 12, 2018)

Adapt to OpenSSH 7.7 behavior change for command line arguments, as seen in Windows git 2.17.0, Debian Buster, and OpenBSD 6.3 (JENKINS-50573)

2.7.1 (January 25, 2018)

Adapt to Linux git 2.16 behavior change for non-default ssh ports (JENKINS-49111)
Fix submodule cloning for submodule names containing spaces (JENKINS-48818 and JENKINS-48997)

2.7.0 (December 18, 2017)

Add GitClient.getTags() to fix git rev-parse related checkout performance regression (JENKINS-45447 and JENKINS-47169)
Fix submodule cloning for repository URLs that end with '.url' (JENKINS-46054)
Make GitClient.getRemoteReferences() return empty map from both implementations when remote references are not found (JENKINS-30589)
Use JGit 4.5.4 (rather than JGit 4.5.3) (fix some cases of incorrect NFS file locking)
Improve GitClient.isCommitInRepo() performance with the "--no-walk" argument

2.6.0 (October 27, 2017)

Fix unit test failures on freshly installed systems (JENKINS-47373)
Fix ArrayBoundsException when repository includes commit with embedded control character(JENKINS-45894, JENKINS-47196)
Use env vars to prevent command line credential (CLI git 2.3+) prompts which block the plugin (JENKINS-35959, JENKINS-25878)
Add API to support LFS credentials separate from repository credentials (JENKINS-47531)
Report the path to a reference repository if reference repository is configured and used (JENKINS-46737)
Use JGit 4.5.3 (rather than JGit 4.5.2)
Use apache http client plugin and jsch as bundled with Jenkins

2.5.0 (July 27, 2017)

Honor credential path exclusion (JENKINS-43022)
Fix a submodule case of "no revision to build" (JENKINS-45729)
Add a RECURSIVE_THEIRS merge strategy
Detect setsid command in /usr/local/bin (MacOS) (JENKINS-20879)
Allow boolean options to be toggled rather than just set (JENKINS-45771)

2.4.6 (May 24, 2017)

Fix clone failures when workspace path contains specific special characters (JENKINS-43931, JENKINS-44041, JENKINS-44127, and JENKINS-44420)

2.4.5 (April 29, 2017)

Fix Windows regression when using passphrase protected private keys with a workspace name containing a space (JENKINS-43931)

2.4.4 (April 27, 2017)

Better protect temporary files (Security advisory 2017-04-27)

2.4.2 (April 20, 2017)

Support passphrase protected private keys even when Jenkins is attached to a controlling terminal (docker with "-it" argument, or "mvn hpi:run") (JENKINS-20879, JENKINS-25194)
Require credentials plugin 2.1.13 for credentials tracking API support
Use JGit 4.5.2 (bug fix)
Add Italian language translation

2.4.1 (March 30, 2017)

Work around JGit clean bug (JENKINS-43198)

2.4.0 (March 24, 2017)

Add API to determine default remote branch (JENKINS-40834)
Use JGit 4.5.1 (bug fixes)

2.3.0 (February 28, 2017)

Support git large file storage (LFS) with command line git versions 1.9 and later (JENKINS-30318, JENKINS-35687, JENKINS-38708, JENKINS-40174)
Fix ssh passphrase distribution to agents (JENKINS-37899)
Fix ssh passphrase use on Windows agents (JENKINS-20356)

2.2.1 (January 16, 2017)

Fix 2.0.0 regression with special characters in Windows https git passwords (JENKINS-40166, JENKINS-38194, JENKINS-38179, JENKINS-38138)

2.2.0 (January 2, 2017)

Fix 2.0.0 regression with renamed submodules (JENKINS-37495)
Fix 2.0.0 regression reading wrong file for submodule configuration (JENKINS-37419, JENKINS-38860)

2.1.0 (November 3, 2016)

Add jgitapache as alternate git implementation - JGit with Apache HTTP
Use JGit 4.5.0

2.0.0 (September 10, 2016)

Require Java 7 (Jenkins 1.625 or newer) - try with resources and other code simplifications
Use JGit 4.4.1
Use Apache httpclient 4.5.2

1.21.0 (August 20, 2016)

Prepare for command line git support of multi-branch plugin (JENKINS-37297, JENKINS-36958, JENKINS-33983, JENKINS-35567) (authenticate for branch pruning, create directory if needed in command line git init)
Fix timeout support in command line checkout (JENKINS-37185, JENKINS-22547)
Don't throw an exception on unexpected command line git ls-remote output

1.19.7 (July 15, 2016)

Fix StringIndexException in parseBranches (JENKINS-34309)
Support NixOS, don't hard code path to echo (JENKINS-36255)

2.0.0-beta1 (June 14, 2016)

Require Java 7 (Jenkins 1.625 or newer) - try with resources and other code simplifications
Use JGit 4.3.1 (though may be affected by JGit bug 496262)
Use Apache httpclient 4.5.2

1.20.0-beta3 (March 10, 2016)

Guard rev-parse calls from surprise blank lines (JENKINS-20991)
Reduce memory use generating changelog (JENKINS-31326 partial fix, also needs new git plugin)
Warn if JGit fetch attempted with shallow clone options, don't throw exception
Fix one case of passphrase protected ssh clone (JENKINS-32834)
Improve Windows ssh finding code (JENKINS-30045)
Read git changelog as UTF-8 (JENKINS-6203, JENKINS-14798, JENKINS-23091)
Improve performance of calls to git rev-parse (JENKINS-32258)

1.19.6 (March 6, 2016)

Guard rev-parse calls from surprise blank lines (JENKINS-20991)
Reduce memory use generating changelog (JENKINS-31326 partial fix, also needs new git plugin)

1.19.5 (February 17, 2016) 824604b

Warn if JGit fetch attempted with shallow clone options, don't throw exception

1.19.4 (February 9, 2016)

Fix one case of passphrase protected ssh clone (JENKINS-32834)

1.19.3 (February 6, 2016)

Improve Windows ssh finding code (JENKINS-30045)
Read git changelog as UTF-8 (JENKINS-6203, JENKINS-14798, JENKINS-23091)

1.19.2 (January 9, 2016)

Improve performance of calls to git rev-parse (JENKINS-32258)

1.20.0-beta1 (November 4, 2015)

Support submodule authentication (JENKINS-20941) - requires git plugin 2.5.0-beta1

1.19.1 (December 26, 2015)

Allow symbolic links with JGit (JENKINS-30371)
Allow push from shallow clones (JENKINS-31108)
Add merge and rebase API's (JENKINS-30486, JENKINS-12402, JENKINS-28833, JENKINS-30839)
Parse log dates per ISO 8601 (JENKINS-27097)

1.19.0 (August 20, 2015)

Support Windows git 2.5.0 (JENKINS-30045, JENKINS-30032)
Add API support for shallow clone depth (JENKINS-24728)
Remove distracting warning about invalid gitTool (JENKINS-29368)
Use Bourne shell for ASKPASS answer for portability (JENKINS-29813)
Include username in GIT_SSH calls (JENKINS-29604)
Allow push from JGit (JENKINS-20393)

1.18.0 (July 18, 2015)

Update minimum Jenkins version from 1.509 to 1.532.2
Update JGit to 3.7.1
Add squash as merge option (JENKINS-28833)
Allow Linux ssh keys with passphrase (JENKINS-20638, JENKINS-20879, JENKINS-27998)
Implement prune for JGit repositories (JENKINS-26197)
Improve checkout failure message (JENKINS-26748)
Use ISO-8601 date format in changelog (JENKINS-27097)
Find ssh.exe on Windows even if git is in cmd directory (JENKINS-28943)
Guard against null pointer exceptions in several API calls
Update other dependencies (httpclient 4.4.1, ssh-credentials 1.11, etc.)

1.17.1 (May 8, 2015)

Revert all changes introduced in 1.17.0, will revisit later
Restore 1.16.1 ISO date implementation to avoid git plugin bugs (JENKINS-28134, JENKINS-28260, and JENKINS-28291)

1.17.0 (April 25, 2015)

Update minimum Jenkins version from 1.509 to 1.532.2
Update JGit to 3.7.0
Implement prune for JGit repositories (JENKINS-26197)
Use ISO-8601 date format in changelog (JENKINS-27097)
Improve checkout failure message (JENKINS-26748)
Guard against null pointer exceptions in several API calls
Update other dependencies (httpclient 4.4.1, ssh-credentials 1.11, etc.)

1.16.1 (February 6, 2015)

Allow API access to all merge modes, including fast forward, and no fast forward (JENKINS-12402)
Allow clone with multiple refspecs (JENKINS-26417)
Improve javadoc, including fixes for Java 8 javadoc

1.15.0 (January 6, 2015)

Update from JGit 3.6.0 to JGit 3.6.1
Guard web pages with "jelly escape"

1.14.1 (December 27, 2014)

Only use "-c core.askpass=true" if command line git is newer than 1.7.9 (don't break really old git versions unnecessarily)

1.14.0 (December 25, 2014)

Update from JGit 3.5.3 to JGit 3.6.0
Use command line credentials check when using command line git (JENKINS-22675, JENKINS-22909, JENKINS-23050, JENKINS-20533)

1.13.0 (December 18, 2014)

Update from JGit 3.5.2 to JGit 3.5.3 (CVE-2014-9390)
Remove .git/index.lock on command line git crash (JENKINS-25353)
Update a few dependencies, resolve a few findbugs warnings

1.12.0 (November 25, 2014)

Update from JGit 3.5.1 to JGit 3.5.2
Revision object now provides equals() and hashCode() (JENKINS-25639)
Update commons-codec to 1.10

1.11.1 (November 7, 2014)

Allow reference repositories with JGit - faster clone/fetch when commits are already in the reference repo (JENKINS-25387)
Add getBranchesContaining() to GitClient API - report branches containing a specific SHA1
Add getRemoteReferences() to GitClient API - list remote references without a repository
Allow PushCommand to push tags
Fix JGit fetch() to match CliGit behavior - delete local changes (JENKINS-25444)
Various test additions and improvements

1.11.0 (October 18, 2014)

Update from JGit 3.4.1 to JGit 3.5.1
Bundle jgit http server in git-client-plugin for easier version maintenance (JENKINS-21756)
Various test additions and improvements

1.10.2 (September 12, 2014)

Support authenticating proxies (JENKINS-24112)
Add API entry point for getRemoteTagNames
Warn Windows users if TEMP or TMP contains embedded space (JENKINS-22706)
Fix tag comparison (when refs/tags/tag_name is the branch to build) so tag based builds don't build at every poll (JENKINS-23299)

1.10.1 (July 30, 2014)

Timeout on checkout can be adjusted (JENKINS-22400)
Add API entry point to list first parent of revision list

1.10.0 (July 22, 2014)

Allow "Branches to build" to use refs/heads/ to specify branch precisely (JENKINS-23884, JENKINS-23266)
Add API entry points to manage refs through GitClient

1.9.2 (July 16, 2014)

Upgrade JGit to 3.4.1, httpclient 4.3.4, ssh-credentials 1.7.1
Simplify the pom
Improve ssh.exe location guessing on Windows (JENKINS-21806)
Reset tracked file local modifications on JGit checkout (JENKINS-23424)

1.9.1 (May 21, 2014)

Simplify the pom
Support polling behind an http proxy (JENKINS-22999)
Remove temp directory after authenticated fast remote poll (JENKINS-23017)

1.9.0 (May 8, 2014)

Allow timeout setting for submodule updates (JENKINS-22400)
Upgrade JGit to 3.4.0
Several test related improvements (Windows "busy file" test failures silenced on JDK 8, etc.)
Correctly display first revision when using JGit (JENKINS-22343)

1.8.1 (May 3, 2014)

Allow switch branch of a submodule before update (for later use in git plugin)
Upgrade JGit to 3.3.2
Several test related improvements (JaCoCo 0.7.0, Windows "busy file" test failures silenced, etc.)
Log executed git commands for easier diagnosis
Only use progress argument on git versions which support it
Warn if git version is too old for credentials support (JENKINS-21887)
Use a new temporary directory for remote polling of authenticated repositories (JENKINS-22039)

1.8.0 (April 3, 2014)

Upgrade JGit from 3.3.0 to 3.3.1
Update remote tracking branch support for submodules if using command line git version 1.8.2 or newer

1.7.0 (March 27, 2014)

Fix symlink behavior in CliGit checkout (JENKINS-22376, JENKINS-21168, and JENKINS-22391)
Add remote tracking branch support for submodules if using command line git version 1.8.2 or newer

1.6.6 (March 25, 2014)

Switch CheckoutCommand from abstract class to interface (sparse checkout support)

1.6.5 (March 22, 2014)

Add sparse checkout support (requires git-plugin 2.0.5, requires git 1.8.2)
Upgrade JGit from 3.2.0 to 3.3.0
Enable push from JGit
QA improvements (more tests)

1.6.4 (March 6, 2014)

Add NTLM authentication (for Team Foundation Server git implementation)
Support branch change detection in branches using namespaces (e.g. develop1/master)
Replace obsolete Apache HttpClient with Apache HttpComponents
Require at least Jenkins 1.509 so that authentication can be tested
QA improvements (more tests, findbugs warnings fixes, etc.)

1.6.3 (February 20, 2014)

Set remote URL during clone (implemented as init + fetch) to mimic an actual clone
CLI impl getRemoteUrl support empty git directory (align to JGit impl)
QA improvements

1.6.2 (February 04, 2014)

Fix credentials support on Windows (JENKINS-21016)
Fix use of credentials in Git publisher (JENKINS-21116)
Fix reference resolution (JENKINS-21434)
Fix JGit rebuilds on each poll if wildcard in branch name (JENKINS-20286)
Alternate way to find ssh.exe on windows (JENKINS-21030)
Expose git timeout for clone and fetch commands(JENKINS-20445 JENKINS-20387 JENKINS-20750)
Upgrade to JGit 3.2.0 and other dependencies
QA improvements - more tests, findbugs and jacoco coverage

1.6.1 (January 10, 2014)

Warn when credentials.helper can be removed form config but don't fail the command
Fix git-credentials-store syntax(JENKINS-21016)
Fix a file leak when JGit is used(JENKINS-19994)
Test coverage improvement (thanks to Mark Waite)
Throw GitLockFailedException on lock failure (to allow retry)
Printing error message on SSLException to help diagnose ssl problems

1.6 (December 18, 2013)

Method to push to URL (not implemented yet by JGit)
Method to add URL for remote (i.e. git config --add remote.foo.url bar)

1.5 (December 14, 2013)

Use git-credentials-store for http credentials(issue #20318)
Use ls-remote to retrieve all remote references (issue #10131)
Support non-proxy hosts (issue #20252)
Better support for .netrc (issue #20684)

1.4.6 (October 30, 2013)

Fix ssh private key support (using GIT_SSH) (issue #20223)
Append .git extension to repository URL on 404 (issue #20189)
Fix http proxy support (issue #20326)
Set a time-out running git commands (org.jenkinsci.plugins.gitclient.Git.timeOut, defaults to 10 minutes) (issue #11286)

1.4.5 (October 24, 2013)

Fix remoting bug (issue #20218)
Support for self-signed certificate (issue #20200)

1.4.4 (October 22, 2013)

Make JGit checkout compliant with CliGit
Support for http proxy (issue #20218)

1.4.3 (October 17, 2013)

Fix changelog generation on windows (JENKINS-18995)
Add support for .netrc as credential source for http(s) transport (backward compatibility)

1.4.2 (October 13, 2013)

Fix username/password support (JENKINS-19974, JENKINS-19995)
username/password can also be set in repository URL (backward compatibility issue)

1.4.0 (October 10, 2013)

JGit upgrade
Add support for username/password credentials

1.3.0 (September 21, 2013)

Add support for --shared option
JGit upgrade
Align JGit behavior for checkout to git-cli one (JENKINS-18988)
Bug in JGit implemenation (JENKINS-19108)

1.2.0 (September 16, 2013)

Support for SSH Credentials within Git CLI implementation using ssh-agent plugin

1.1.2 (August 07, 2013)

Integration with updates to Credentials and SSH Credentials plugins
Bug in JGit implementation of git-describe

1.1.1 (July 25, 2013)

Misnamed resource

1.1 (July 24th, 2013)

JGit implementation is feature complete
GitClient interface is now remotable (can be used safely as an argument/return value to remote call)

1.0.7 (June 6th, 2013)

Fixed exception when trying to use Git plugin immediately after installing without restart.

1.0.6 (May 11, 2013)

Resurrect the checkoutBranch method
Support multi-line commit messages for tags

1.0.5 (March 21, 2013)

Reverted default implementation to use git-cli, after many regressions reported by users. org.jenkinsci.plugins.gitclient.Git.useCLI=false can be used to test JGit support.

1.0.4 (March 12, 2013)

Consider first installation as "Default" if not explicitly set (JENKINS-17013).
Implement clean, revParse, deleteTag, getTagMessage, hasGitRepo, isCommitInRepo, addSubmodule in pure JGit
Introduce new method to commit with committer/author
Use JGit implementation in GitAPI for all supported methods, until org.jenkinsci.plugins.gitclient.Git.useCLI is set

1.0.3 (February 28, 2013)

Delete workspace content, not workspace directory, before cloning (JENKINS-16873)
Warn and ignore parameter, but don't break if reference is invalid (JENKINS-16911)
Clarify API usage with more explicit parameter name (JENKINS-16914)
Lock on repository files (issue #12188)
Implement push in pure JGit

1.0.2 (February 19, 2013)

initial design, with GitClient factory