Package org.jenkinsci.plugins.gitclient

Class CliGitAPIImpl

java.lang.Object

org.jenkinsci.plugins.gitclient.CliGitAPIImpl

All Implemented Interfaces:

IGitAPI, Serializable, GitClient

Direct Known Subclasses:

GitAPI

public class CliGitAPIImpl
extends Object

Implementation class using command line CLI ran as external command. For internal use only, don't use directly. See Git

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface org.jenkinsci.plugins.gitclient.GitClient

GitClient.ConfigLevel

Field Summary

Fields

Modifier and Type	Field	Description
protected ProxyConfiguration	proxy
static int	TIMEOUT	preventive Time-out for git command execution.
static boolean	USE_SETSID	Constant which can block use of setsid in git calls for ssh credentialed operations.
protected File	workspace

Fields inherited from interface org.jenkinsci.plugins.gitclient.GitClient

CREDENTIALS_MATCHER, quietRemoteBranches, verbose

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	CliGitAPIImpl(String gitExe, File workspace, TaskListener listener, EnvVars environment)	Constructor for CliGitAPIImpl.

Method Summary

Modifier and Type	Method	Description
void	add(String filePattern)	add.
void	addCredentials(String url, com.cloudbees.plugins.credentials.common.StandardCredentials credentials)	Adds credentials to be used against a specific url.
void	addDefaultCredentials(com.cloudbees.plugins.credentials.common.StandardCredentials credentials)	Adds credentials to be used when there are not url specific credentials defined.
void	addNote(String note, String namespace)	Adds a new git-note on the current HEAD commit.
void	addRemoteUrl(String name, String url)	addRemoteUrl.
void	addSubmodule(String remoteURL, String subdir)	Create a submodule in subdir child directory for remote repository
void	appendNote(String note, String namespace)	Appends to an existing git-note on the current HEAD commit.
void	branch(String name)	branch.
ChangelogCommand	changelog()	changelog.
void	changelog(String revFrom, String revTo, OutputStream outputStream)	changelog.
void	changelog(String revFrom, String revTo, Writer w)	Adds the changelog entries for commits in the range revFrom..revTo.
CheckoutCommand	checkout()	checkout.
void	checkout(String commit)	Checks out the specified commit/tag/branch into the workspace.
void	checkout(String ref, String branch)	Creates a new branch that points to the specified ref.
void	checkoutBranch(String branch, String ref)	Regardless of the current state of the workspace (whether there is some dirty files, etc) and the state of the repository (whether the branch of the specified name exists or not), when this method exits the following conditions hold: The branch of the specified name branch exists and points to the specified ref HEAD points to branch.
void	clean()	Remove untracked files and directories, including files listed in the ignore rules.
void	clean(boolean cleanSubmodule)	Remove untracked files and directories, including files listed in the ignore rules.
void	clearCredentials()	clearCredentials.
void	clone(String url, String origin, boolean useShallowClone, String reference)	Clone a remote repository
void	clone(org.eclipse.jgit.transport.RemoteConfig source)	Deprecated.
void	clone(org.eclipse.jgit.transport.RemoteConfig rc, boolean useShallowClone)	Deprecated.
CloneCommand	clone_()	clone_.
void	commit(String message)	commit.
void	commit(String message, org.eclipse.jgit.lib.PersonIdent author, org.eclipse.jgit.lib.PersonIdent committer)	commit.
void	config(GitClient.ConfigLevel configLevel, String key, String value)	Execute git config at the specified configuration level.
void	deleteBranch(String name)	(force) delete a branch.
void	deleteRef(String refName)	Deletes a ref.
void	deleteTag(String tagName)	deleteTag.
String	describe(String commitIsh)	Equivalent of "git-describe --tags".
protected String	extractBranchNameFromBranchSpec(String branchSpec)	This method takes a branch specification and normalizes it get unambiguous results.
void	fetch()	Deprecated.
void	fetch(String repository, String refspec)	Deprecated.
void	fetch(String remoteName, org.eclipse.jgit.transport.RefSpec refspec)	fetch.
void	fetch(String remoteName, org.eclipse.jgit.transport.RefSpec... refspec)	fetch.
void	fetch(org.eclipse.jgit.transport.RemoteConfig remoteRepository)	Deprecated.
void	fetch(org.eclipse.jgit.transport.URIish url, List<org.eclipse.jgit.transport.RefSpec> refspecs)	Fetch commits from url which match any of the passed in refspecs.
FetchCommand	fetch_()	fetch_.
void	fixSubmoduleUrls(String remote, TaskListener listener)	fixSubmoduleUrls.
String	getAllLogEntries(String branch)	Deprecated.
Set<Branch>	getBranches()	Returns the set of branches defined in this repository, including local branches and remote branches.
List<Branch>	getBranchesContaining(String revspec)	Deprecated.
List<Branch>	getBranchesContaining(String revspec, boolean allBranches)	Find all the branches that include the given commit.
String	getDefaultRemote()	Get the default remote.
String	getDefaultRemote(String _default_)	Returns name of default remote.
Map<String,org.eclipse.jgit.lib.ObjectId>	getHeadRev(String url)	getHeadRev.
org.eclipse.jgit.lib.ObjectId	getHeadRev(String url, String branchSpec)	getHeadRev.
HostKeyVerifierFactory	getHostKeyFactory()
Set<String>	getRefNames(String refPrefix)	List refs with the given prefix.
Set<Branch>	getRemoteBranches()	Returns the remote branches defined in this repository.
Map<String,org.eclipse.jgit.lib.ObjectId>	getRemoteReferences(String url, String pattern, boolean headsOnly, boolean tagsOnly)	List references in a remote repository.
Map<String,String>	getRemoteSymbolicReferences(String url, String pattern)	List symbolic references in a remote repository.
Set<String>	getRemoteTagNames(String tagPattern)	getRemoteTagNames.
String	getRemoteUrl(String name)	From a given repository, get a remote's URL
String	getRemoteUrl(String name, String GIT_DIR)	Returns URL of remote name in repository GIT_DIR.
org.eclipse.jgit.lib.Repository	getRepository()	Returns the Repository used by this git instance.
File	getSSHExecutable()	Returns an executable file of ssh installed in Windows
String	getSubmodulePath(String name)	Get submodule path.
List<IndexEntry>	getSubmodules(String treeIsh)	Finds all the submodule references in this repository at the specified tree.
String	getSubmoduleUrl(String name)	Returns URL of the named submodule.
String	getTagMessage(String tagName)	getTagMessage.
Set<String>	getTagNames(String tagPattern)	getTagNames.
Set<GitObject>	getTags()	Return name and object ID of all tags in current repository.
List<Tag>	getTagsOnCommit(String revName)	Deprecated.
FilePath	getWorkTree()	getWorkTree.
boolean	hasGitModules()	hasGitModules.
boolean	hasGitModules(String treeIsh)	Deprecated.
boolean	hasGitRepo()	Returns true if this workspace has a git repository.
boolean	hasGitRepo(boolean checkParentDirectories)	Returns true if this workspace has a git repository.
boolean	hasGitRepo(String GIT_DIR)	Returns true if the parameter GIT_DIR is a directory which contains a git repository.
void	init()	Initialize an empty repository for further git operations.
InitCommand	init_()	init_.
boolean	isBareRepository()	isBareRepository.
boolean	isBareRepository(String GIT_DIR)	Detect whether a repository at the given path is bare or not.
boolean	isCliGitVerAtLeast(int major, int minor, int rev, int bugfix)	Compare the current cli git version with the required version.
boolean	isCommitInRepo(org.eclipse.jgit.lib.ObjectId commit)	isCommitInRepo.
boolean	isShallowRepository()	Returns true if this repository is configured as a shallow clone.
String	launchCommand(ArgumentListBuilder args)	Launch command using the workspace as working directory
String	launchCommand(String... args)	Launch command using the workspace as working directory
List<IndexEntry>	lsTree(String treeIsh)	This method has been implemented as non-recursive historically, but often that is not what the caller wants.
List<IndexEntry>	lsTree(String treeIsh, boolean recursive)	lsTree.
boolean	maintenance(String task)	Executes git maintenance commands based on the git version.
MergeCommand	merge()	merge.
void	merge(String refSpec)	Deprecated.
void	merge(org.eclipse.jgit.lib.ObjectId rev)	merge.
org.eclipse.jgit.lib.ObjectId	mergeBase(org.eclipse.jgit.lib.ObjectId id1, org.eclipse.jgit.lib.ObjectId id2)	Deprecated.
void	prune(org.eclipse.jgit.transport.RemoteConfig repository)	Prune stale remote tracking branches with "git remote prune" on the specified remote.
PushCommand	push()	push.
void	push(String remoteName, String refspec)	Deprecated.
void	push(org.eclipse.jgit.transport.RemoteConfig repository, String refspec)	Deprecated.
void	push(org.eclipse.jgit.transport.URIish url, String refspec)	Deprecated.
RebaseCommand	rebase()	rebase.
void	ref(String refName)	Create (or update) a ref.
boolean	refExists(String refName)	Check if a ref exists.
protected org.jenkinsci.plugins.gitclient.RemoteGitImpl	remoteProxyFor(GitClient proxy)	remoteProxyFor.
void	reset()	Deprecated.
void	reset(boolean hard)	Reset the contents of the working directory of this repository.
List<org.eclipse.jgit.lib.ObjectId>	revList(String ref)	revList.
RevListCommand	revList_()	revList_.
List<org.eclipse.jgit.lib.ObjectId>	revListAll()	revListAll.
List<org.eclipse.jgit.lib.ObjectId>	revListBranch(String branchId)	Deprecated.
org.eclipse.jgit.lib.ObjectId	revParse(String revName)	Retrieve commit object that is direct child for revName revision reference.
void	setAuthor(String name, String email)	Sets the identity of the author for future commits and merge operations.
void	setAuthor(org.eclipse.jgit.lib.PersonIdent p)	setAuthor.
void	setCommitter(String name, String email)	Sets the identity of the committer for future commits and merge operations.
void	setCommitter(org.eclipse.jgit.lib.PersonIdent p)	setCommitter.
void	setCredentials(com.cloudbees.plugins.credentials.common.StandardUsernameCredentials cred)	setCredentials.
void	setHostKeyFactory(HostKeyVerifierFactory verifier)
void	setProxy(ProxyConfiguration proxy)	setProxy.
void	setRemoteUrl(String name, String url)	For a given repository, set a remote's URL
void	setRemoteUrl(String name, String url, String GIT_DIR)	Set remote repository name and URL.
void	setSubmoduleUrl(String name, String url)	Sets URL of the named submodule.
void	setupSubmoduleUrls(Revision rev, TaskListener listener)	Set up submodule URLs so that they correspond to the remote pertaining to the revision that has been checked out.
void	setupSubmoduleUrls(String remote, TaskListener listener)	Deprecated.
List<String>	showRevision(Revision r)	Deprecated.
List<String>	showRevision(org.eclipse.jgit.lib.ObjectId r)	Given a Revision, show it as if it were an entry from git whatchanged, so that it can be parsed by GitChangeLogParser.
List<String>	showRevision(org.eclipse.jgit.lib.ObjectId from, org.eclipse.jgit.lib.ObjectId to)	Given a Revision, show it as if it were an entry from git whatchanged, so that it can be parsed by GitChangeLogParser.
List<String>	showRevision(org.eclipse.jgit.lib.ObjectId from, org.eclipse.jgit.lib.ObjectId to, Boolean useRawOutput)	Given a Revision, show it as if it were an entry from git whatchanged, so that it can be parsed by GitChangeLogParser.
GitClient	subGit(String subdir)	subGit.
void	submoduleClean(boolean recursive)	submoduleClean.
void	submoduleInit()	submoduleInit.
void	submoduleReset(boolean recursive, boolean hard)	Reset submodules
void	submoduleSync()	Sync submodule URLs
SubmoduleUpdateCommand	submoduleUpdate()	Update submodules.
void	submoduleUpdate(boolean recursive)	Run submodule update optionally recursively on all submodules (equivalent of git submodule update --recursive.)
void	submoduleUpdate(boolean recursive, boolean remoteTracking)	Run submodule update optionally recursively on all submodules, optionally with remoteTracking submodules (equivalent of git submodule update --recursive --remote.)
void	submoduleUpdate(boolean recursive, boolean remoteTracking, String reference)	Run submodule update optionally recursively on all submodules, optionally with remoteTracking, with a specific reference passed to git clone if needing to --init.
void	submoduleUpdate(boolean recursive, String reference)	Run submodule update optionally recursively on all submodules, with a specific reference passed to git clone if needing to --init.
void	tag(String tagName, String comment)	Create (or update) a tag.
boolean	tagExists(String tagName)	tagExists.
org.eclipse.jgit.lib.ObjectId	validateRevision(String revName)	validateRevision.
<T> T	withRepository(RepositoryCallback<T> callable)	Runs the computation that requires local access to Repository.
protected Object	writeReplace()	When sent to remote, switch to the proxy.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.jenkinsci.plugins.gitclient.GitClient

changelog, checkout, checkout, clone, commit, merge, setAuthor, setCommitter, setCredentials, setProxy, submoduleUpdate, submoduleUpdate, submoduleUpdate, submoduleUpdate, withRepository

Methods inherited from interface hudson.plugins.git.IGitAPI

changelog, checkoutBranch

Field Detail

USE_SETSID

public static final boolean USE_SETSID

Constant which can block use of setsid in git calls for ssh credentialed operations. USE_SETSID=Boolean.valueOf(System.getProperty(CliGitAPIImpl.class.getName() + ".useSETSID", "false")). Allow ssh authenticated git calls on Unix variants to be preceded by setsid so that the git command is run without being associated with a terminal. Some docker runtime cases, and some automated test cases have shown that some versions of command line git or ssh will not allow automatic answers to private key passphrase prompts unless there is no controlling terminal associated with the process.

TIMEOUT

public static final int TIMEOUT

preventive Time-out for git command execution.

We run git as an external process so can't guarantee it won't hang for whatever reason. Even though the plugin does its best to avoid git interactively asking for credentials, there are many of other cases where git may hang.

workspace

protected final File workspace

proxy

protected ProxyConfiguration proxy

Constructor Detail

CliGitAPIImpl

protected CliGitAPIImpl(String gitExe,
                        File workspace,
                        TaskListener listener,
                        EnvVars environment)

Constructor for CliGitAPIImpl.

Parameters:

gitExe - a String object.

workspace - a File object.

listener - a TaskListener object.

environment - a EnvVars object.

Method Detail

isCliGitVerAtLeast

public boolean isCliGitVerAtLeast(int major,
                                  int minor,
                                  int rev,
                                  int bugfix)

Compare the current cli git version with the required version. Finds if the current cli git version is at-least the required version. Returns True if the current cli git version is at least the required version.

Parameters:

major - required major version for command line git

minor - required minor version for command line git

rev - required revision for command line git

bugfix - required patches for command line git

Returns:

true if the command line git version is at least the required version

subGit

public GitClient subGit(String subdir)

subGit.

Parameters:

subdir - a String object.

Returns:

a IGitAPI implementation to manage git submodule repository

init

public void init()
          throws GitException,
                 InterruptedException

Initialize an empty repository for further git operations.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

hasGitRepo

public boolean hasGitRepo()
                   throws GitException,
                          InterruptedException

Returns true if this workspace has a git repository. Also returns true if this workspace contains an empty .git directory and a parent directory has a git repository.

Returns:

true if this workspace has a git repository

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

hasGitRepo

public boolean hasGitRepo(boolean checkParentDirectories)
                   throws GitException,
                          InterruptedException

Returns true if this workspace has a git repository. If checkParentDirectories is true, searches parent directories. If checkParentDirectories is false, checks workspace directory only.

Parameters:

checkParentDirectories - if true, search upward for a git repository

Returns:

true if this workspace has a git repository

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

hasGitRepo

public boolean hasGitRepo(String GIT_DIR)
                   throws GitException

Returns true if the parameter GIT_DIR is a directory which contains a git repository.

Parameters:

GIT_DIR - a String object.

Returns:

true if GIT_DIR has a git repository

Throws:

GitException - if underlying git operation fails.

getSubmodules

public List<IndexEntry> getSubmodules(String treeIsh)
                               throws GitException,
                                      InterruptedException

Finds all the submodule references in this repository at the specified tree.

Parameters:

treeIsh - a String object.

Returns:

never null.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

fetch_

public FetchCommand fetch_()

fetch_.

Returns:

a FetchCommand object.

fetch

public void fetch(org.eclipse.jgit.transport.URIish url,
                  List<org.eclipse.jgit.transport.RefSpec> refspecs)
           throws GitException,
                  InterruptedException

Fetch commits from url which match any of the passed in refspecs. Assumes remote.remoteName.url has been set.

Parameters:

url - a URIish object.

refspecs - a List object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

fetch

public void fetch(String remoteName,
                  org.eclipse.jgit.transport.RefSpec... refspec)
           throws GitException,
                  InterruptedException

fetch.

Parameters:

remoteName - a String object.

refspec - a RefSpec object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

fetch

public void fetch(String remoteName,
                  org.eclipse.jgit.transport.RefSpec refspec)
           throws GitException,
                  InterruptedException

fetch.

Parameters:

remoteName - a String object.

refspec - a RefSpec object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

reset

public void reset(boolean hard)
           throws GitException,
                  InterruptedException

Reset the contents of the working directory of this repository. Refer to git reset documentation.

Parameters:

hard - reset as though "--hard" were passed to "git reset"

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

clone_

public CloneCommand clone_()

clone_.

Returns:

a CloneCommand object.

merge

public MergeCommand merge()

merge.

Returns:

a MergeCommand object.

rebase

public RebaseCommand rebase()

rebase.

Returns:

a RebaseCommand object.

init_

public InitCommand init_()

init_.

Returns:

a InitCommand object.

clean

public void clean(boolean cleanSubmodule)
           throws GitException,
                  InterruptedException

Remove untracked files and directories, including files listed in the ignore rules.

Parameters:

cleanSubmodule - flag to add extra -f

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

clean

public void clean()
           throws GitException,
                  InterruptedException

Remove untracked files and directories, including files listed in the ignore rules.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

revParse

public org.eclipse.jgit.lib.ObjectId revParse(String revName)
                                       throws GitException,
                                              InterruptedException

Retrieve commit object that is direct child for revName revision reference.

Parameters:

revName - a commit sha1 or tag/branch refname

Returns:

a ObjectId object.

Throws:

GitException - when no such commit / revName is found in repository.

InterruptedException - if interrupted.

validateRevision

public org.eclipse.jgit.lib.ObjectId validateRevision(String revName)
                                               throws GitException,
                                                      InterruptedException

validateRevision.

Parameters:

revName - a String object.

Returns:

a ObjectId object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

describe

public String describe(String commitIsh)
                throws GitException,
                       InterruptedException

Equivalent of "git-describe --tags". Find a nearby tag (including unannotated ones) and come up with a short identifier to describe the tag.

Parameters:

commitIsh - a String object.

Returns:

a String object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

prune

public void prune(org.eclipse.jgit.transport.RemoteConfig repository)
           throws GitException,
                  InterruptedException

Prune stale remote tracking branches with "git remote prune" on the specified remote.

Parameters:

repository - a RemoteConfig object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

changelog

public ChangelogCommand changelog()

changelog.

Returns:

a ChangelogCommand object.

showRevision

public List<String> showRevision(org.eclipse.jgit.lib.ObjectId from,
                                 org.eclipse.jgit.lib.ObjectId to)
                          throws GitException,
                                 InterruptedException

Given a Revision, show it as if it were an entry from git whatchanged, so that it can be parsed by GitChangeLogParser.

Changes are computed on the [from..to] range. If from is null, this prints just one commit that to represents.

For merge commit, this method reports one diff per each parent. This makes this method behave differently from GitClient.changelog().

Parameters:

from - a ObjectId object.

to - a ObjectId object.

Returns:

The git whatchanged output, in raw format.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

showRevision

public List<String> showRevision(org.eclipse.jgit.lib.ObjectId from,
                                 org.eclipse.jgit.lib.ObjectId to,
                                 Boolean useRawOutput)
                          throws GitException,
                                 InterruptedException

Given a Revision, show it as if it were an entry from git whatchanged, so that it can be parsed by GitChangeLogParser.

If useRawOutput is true, the '--raw' option will include commit file information to be passed to the GitChangeLogParser.

Changes are computed on the [from..to] range. If from is null, this prints just one commit that to represents.

For merge commit, this method reports one diff per each parent. This makes this method behave differently from GitClient.changelog().

Parameters:

from - a ObjectId object.

to - a ObjectId object.

useRawOutput - a {java.lang.Boolean} object.

Returns:

The git whatchanged output, in raw format.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

submoduleInit

public void submoduleInit()
                   throws GitException,
                          InterruptedException

submoduleInit.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

addSubmodule

public void addSubmodule(String remoteURL,
                         String subdir)
                  throws GitException,
                         InterruptedException

Create a submodule in subdir child directory for remote repository

Parameters:

remoteURL - a String object.

subdir - a String object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

submoduleSync

public void submoduleSync()
                   throws GitException,
                          InterruptedException

Sync submodule URLs

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

submoduleUpdate

public SubmoduleUpdateCommand submoduleUpdate()

Update submodules.

Returns:

a SubmoduleUpdateCommand object.

submoduleReset

public void submoduleReset(boolean recursive,
                           boolean hard)
                    throws GitException,
                           InterruptedException

Reset submodules

Parameters:

recursive - if true, will recursively reset submodules (requires git>=1.6.5)

hard - if true, the --hard argument will be passed to submodule reset

Throws:

GitException - if executing the git command fails

InterruptedException - if git command interrupted

submoduleClean

public void submoduleClean(boolean recursive)
                    throws GitException,
                           InterruptedException

submoduleClean. Cleans submodules

Parameters:

recursive - a boolean.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

getSubmoduleUrl

@CheckForNull
public String getSubmoduleUrl(String name)
                       throws GitException,
                              InterruptedException

Returns URL of the named submodule. Get submodule URL

Parameters:

name - submodule name whose URL will be returned

Returns:

URL of the named submodule

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

setSubmoduleUrl

public void setSubmoduleUrl(String name,
                            String url)
                     throws GitException,
                            InterruptedException

Sets URL of the named submodule. Set submodule URL

Parameters:

name - submodule name whose URL will be set

url - URL for the named submodule

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

getSubmodulePath

@CheckForNull
public String getSubmodulePath(String name)
                        throws GitException,
                               InterruptedException

Get submodule path.

Parameters:

name - submodule name whose path is returned

Returns:

path to submodule

Throws:

GitException - on git error

InterruptedException - if interrupted

getRemoteUrl

@CheckForNull
public String getRemoteUrl(String name)
                    throws GitException,
                           InterruptedException

From a given repository, get a remote's URL

Parameters:

name - The name of the remote (e.g. origin)

Returns:

a String object.

Throws:

GitException - if executing the git command fails

InterruptedException - if interrupted.

setRemoteUrl

public void setRemoteUrl(String name,
                         String url)
                  throws GitException,
                         InterruptedException

For a given repository, set a remote's URL

Parameters:

name - The name of the remote (e.g. origin)

url - The new value of the remote's URL

Throws:

GitException - if executing the git command fails

InterruptedException - if interrupted.

addRemoteUrl

public void addRemoteUrl(String name,
                         String url)
                  throws GitException,
                         InterruptedException

addRemoteUrl.

Parameters:

name - a String object.

url - a String object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

getRemoteUrl

public String getRemoteUrl(String name,
                           String GIT_DIR)
                    throws GitException,
                           InterruptedException

Returns URL of remote name in repository GIT_DIR.

Parameters:

name - name for the remote repository, for example, "origin"

GIT_DIR - directory containing git repository

Returns:

URL of remote "name" in repository GIT_DIR.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

setRemoteUrl

public void setRemoteUrl(String name,
                         String url,
                         String GIT_DIR)
                  throws GitException,
                         InterruptedException

Set remote repository name and URL.

Parameters:

name - name for the remote repository, for example, "origin"

url - URL for the remote repository, for example https://github.com/jenkinsci/git-client-plugin.git

GIT_DIR - directory containing git repository

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

getDefaultRemote

public String getDefaultRemote(String _default_)
                        throws GitException,
                               InterruptedException

Returns name of default remote.

Parameters:

_default_ - value to return if no remote is defined in this repository

Returns:

name of default remote

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

getDefaultRemote

public String getDefaultRemote()
                        throws GitException,
                               InterruptedException

Get the default remote.

Returns:

default git remote for this repository (often "origin")

Throws:

GitException - if executing the git command fails

InterruptedException - if interrupted

isBareRepository

public boolean isBareRepository(String GIT_DIR)
                         throws GitException,
                                InterruptedException

Detect whether a repository at the given path is bare or not.

Parameters:

GIT_DIR - The path to the repository (must be to .git dir).

Returns:

true if this repository is bare

Throws:

GitException - on failure

InterruptedException - if interrupted

isShallowRepository

public boolean isShallowRepository()

Returns true if this repository is configured as a shallow clone. Shallow clone requires command line git 1.9 or later.

Returns:

true if this repository is configured as a shallow clone

fixSubmoduleUrls

public void fixSubmoduleUrls(String remote,
                             TaskListener listener)
                      throws GitException,
                             InterruptedException

fixSubmoduleUrls. Fixes urls for submodule as stored in .git/config and $SUBMODULE/.git/config for when the remote repo is NOT a bare repository. It is only really possible to detect whether a repository is bare if we have local access to the repository. If the repository is remote, we therefore must default to believing that it is either bare or NON-bare. The defaults are according to the ending of the super-project remote.origin.url: - Ends with "/.git": default is NON-bare - otherwise: default is bare .

Parameters:

remote - a String object.

listener - a TaskListener object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

setupSubmoduleUrls

public void setupSubmoduleUrls(Revision rev,
                               TaskListener listener)
                        throws GitException,
                               InterruptedException

Set up submodule URLs so that they correspond to the remote pertaining to the revision that has been checked out. Set up submodule URLs so that they correspond to the remote pertaining to the revision that has been checked out.

Parameters:

rev - a Revision object.

listener - a TaskListener object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

tag

public void tag(String tagName,
                String comment)
         throws GitException,
                InterruptedException

Create (or update) a tag. If tag already exist it gets updated (equivalent to git tag --force)

Parameters:

tagName - a String object.

comment - a String object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

appendNote

public void appendNote(String note,
                       String namespace)
                throws GitException,
                       InterruptedException

Appends to an existing git-note on the current HEAD commit. If a note doesn't exist, it works just like GitClient.addNote(String, String)

Parameters:

note - Content of the note.

namespace - If unqualified, interpreted as "refs/notes/NAMESPACE" just like cgit.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

addNote

public void addNote(String note,
                    String namespace)
             throws GitException,
                    InterruptedException

Adds a new git-note on the current HEAD commit.

Parameters:

note - Content of the note.

namespace - If unqualified, interpreted as "refs/notes/NAMESPACE" just like cgit.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

launchCommand

public String launchCommand(ArgumentListBuilder args)
                     throws GitException,
                            InterruptedException

Launch command using the workspace as working directory

Parameters:

args - arguments to the command

Returns:

command output

Throws:

GitException - if launched command fails

InterruptedException - if interrupted

launchCommand

public String launchCommand(String... args)
                     throws GitException,
                            InterruptedException

Launch command using the workspace as working directory

Parameters:

args - command argumnents

Returns:

command output

Throws:

GitException - on failure

InterruptedException - if interrupted

getSSHExecutable

public File getSSHExecutable()

Returns an executable file of ssh installed in Windows

Returns:

File The ssh executable file File

push

public PushCommand push()

push.

Returns:

a PushCommand object.

getBranches

public Set<Branch> getBranches()
                        throws GitException,
                               InterruptedException

Returns the set of branches defined in this repository, including local branches and remote branches. Remote branches are prefixed by "remotes/".

Returns:

a Set object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

getRemoteBranches

public Set<Branch> getRemoteBranches()
                              throws GitException,
                                     InterruptedException

Returns the remote branches defined in this repository.

Returns:

Set of remote branches in this repository

Throws:

GitException - if underlying git operation fails

InterruptedException - if interrupted

checkout

public CheckoutCommand checkout()

checkout.

Returns:

a CheckoutCommand object.

tagExists

public boolean tagExists(String tagName)
                  throws GitException,
                         InterruptedException

tagExists.

Parameters:

tagName - a String object.

Returns:

true if tag exists in repository

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

deleteBranch

public void deleteBranch(String name)
                  throws GitException,
                         InterruptedException

(force) delete a branch.

Parameters:

name - a String object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

deleteTag

public void deleteTag(String tagName)
               throws GitException,
                      InterruptedException

deleteTag.

Parameters:

tagName - a String object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

lsTree

public List<IndexEntry> lsTree(String treeIsh,
                               boolean recursive)
                        throws GitException,
                               InterruptedException

lsTree.

Parameters:

treeIsh - a String object.

recursive - a boolean.

Returns:

a List object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

revList_

public RevListCommand revList_()

revList_.

Returns:

a RevListCommand object.

revListAll

public List<org.eclipse.jgit.lib.ObjectId> revListAll()
                                               throws GitException,
                                                      InterruptedException

revListAll.

Returns:

a List object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

revList

public List<org.eclipse.jgit.lib.ObjectId> revList(String ref)
                                            throws GitException,
                                                   InterruptedException

revList.

Parameters:

ref - a String object.

Returns:

a List object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

isCommitInRepo

public boolean isCommitInRepo(org.eclipse.jgit.lib.ObjectId commit)
                       throws InterruptedException

isCommitInRepo.

Parameters:

commit - a ObjectId object.

Returns:

true if commit is in repository

Throws:

InterruptedException - if interrupted.

add

public void add(String filePattern)
         throws GitException,
                InterruptedException

add.

Parameters:

filePattern - a String object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

branch

public void branch(String name)
            throws GitException,
                   InterruptedException

branch.

Parameters:

name - a String object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

commit

public void commit(String message)
            throws GitException,
                   InterruptedException

commit.

Parameters:

message - a String object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

addCredentials

public void addCredentials(String url,
                           com.cloudbees.plugins.credentials.common.StandardCredentials credentials)

Adds credentials to be used against a specific url.

Parameters:

url - the url for the credentials to be used against.

credentials - the credentials to use.

clearCredentials

public void clearCredentials()

clearCredentials.

addDefaultCredentials

public void addDefaultCredentials(com.cloudbees.plugins.credentials.common.StandardCredentials credentials)

Adds credentials to be used when there are not url specific credentials defined.

Parameters:

credentials - the credentials to use.

See Also:

GitClient.addCredentials(String, com.cloudbees.plugins.credentials.common.StandardCredentials)

setAuthor

public void setAuthor(String name,
                      String email)
               throws GitException

Sets the identity of the author for future commits and merge operations.

Parameters:

name - a String object.

email - a String object.

Throws:

GitException - if underlying git operation fails.

setCommitter

public void setCommitter(String name,
                         String email)
                  throws GitException

Sets the identity of the committer for future commits and merge operations.

Parameters:

name - a String object.

email - a String object.

Throws:

GitException - if underlying git operation fails.

getRepository

@NonNull
public org.eclipse.jgit.lib.Repository getRepository()
                                              throws GitException

Returns the Repository used by this git instance.

Returns:

a Repository object.

Throws:

GitException - if underlying git operation fails.

getWorkTree

public FilePath getWorkTree()

getWorkTree.

Returns:

a FilePath object.

getRemoteTagNames

public Set<String> getRemoteTagNames(String tagPattern)
                              throws GitException

getRemoteTagNames.

Parameters:

tagPattern - a String object.

Returns:

a Set object.

Throws:

GitException - if underlying git operation fails.

getTagNames

public Set<String> getTagNames(String tagPattern)
                        throws GitException

getTagNames.

Parameters:

tagPattern - a String object.

Returns:

a Set object.

Throws:

GitException - if underlying git operation fails.

getTagMessage

public String getTagMessage(String tagName)
                     throws GitException,
                            InterruptedException

getTagMessage.

Parameters:

tagName - a String object.

Returns:

a String object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

ref

public void ref(String refName)
         throws GitException,
                InterruptedException

Create (or update) a ref. The ref will reference HEAD (equivalent to git update-ref ... HEAD).

Parameters:

refName - the full name of the ref (e.g. "refs/myref"). Spaces will be replaced with underscores.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

refExists

public boolean refExists(String refName)
                  throws GitException,
                         InterruptedException

Check if a ref exists. Equivalent to comparing the return code of git show-ref to zero.

Parameters:

refName - the full name of the ref (e.g. "refs/myref"). Spaces will be replaced with underscores.

Returns:

True if the ref exists, false otherwise.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

deleteRef

public void deleteRef(String refName)
               throws GitException,
                      InterruptedException

Deletes a ref. Has no effect if the ref does not exist, equivalent to git update-ref -d.

Parameters:

refName - the full name of the ref (e.g. "refs/myref"). Spaces will be replaced with underscores.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

getRefNames

public Set<String> getRefNames(String refPrefix)
                        throws GitException,
                               InterruptedException

List refs with the given prefix. Equivalent to git for-each-ref --format="%(refname)".

Parameters:

refPrefix - the literal prefix any ref returned will have. The empty string implies all.

Returns:

a set of refs, each beginning with the given prefix. Empty if none.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

getHeadRev

public Map<String,org.eclipse.jgit.lib.ObjectId> getHeadRev(String url)
                                                           throws GitException,
                                                                  InterruptedException

getHeadRev.

Parameters:

url - a String object.

Returns:

a Map object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

getHeadRev

public org.eclipse.jgit.lib.ObjectId getHeadRev(String url,
                                                String branchSpec)
                                         throws GitException,
                                                InterruptedException

getHeadRev.

Parameters:

url - a String object.

branchSpec - a String object.

Returns:

a ObjectId object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

getRemoteReferences

public Map<String,org.eclipse.jgit.lib.ObjectId> getRemoteReferences(String url,
                                                                           String pattern,
                                                                           boolean headsOnly,
                                                                           boolean tagsOnly)
                                                                    throws GitException,
                                                                           InterruptedException

List references in a remote repository. Equivalent to git ls-remote [--heads] [--tags] <repository> [<refs>].

Parameters:

url - Remote repository URL.

pattern - Only references matching the given pattern are displayed.

headsOnly - Limit to only refs/heads.

tagsOnly - Limit to only refs/tags. headsOnly and tagsOnly are not mutually exclusive; when both are true, references stored in refs/heads and refs/tags are displayed.

Returns:

a map of reference names and their commit hashes. Empty if none.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

getRemoteSymbolicReferences

public Map<String,String> getRemoteSymbolicReferences(String url,
                                                            String pattern)
                                                     throws GitException,
                                                            InterruptedException

Description copied from interface: GitClient

List symbolic references in a remote repository. Equivalent to git ls-remote --symref <repository> [<refs>]. Note: the response may be empty for multiple reasons

Parameters:

url - Remote repository URL.

pattern - Only references matching the given pattern are displayed.

Returns:

a map of reference names and their underlying references. Empty if none or if the remote does not report symbolic references (i.e. Git 1.8.4 or earlier) or if the client does not support reporting symbolic references (e.g. command line Git prior to 2.8.0).

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

merge

@Deprecated
public void merge(String refSpec)
           throws GitException,
                  InterruptedException

Deprecated.

Merge commits from revspec into the current branch.

Parameters:

refSpec - the revision specification to be merged (for example, origin/main)

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

push

@Deprecated
public void push(org.eclipse.jgit.transport.RemoteConfig repository,
                 String refspec)
          throws GitException,
                 InterruptedException

Deprecated.

Push revspec to repository.

Parameters:

repository - git repository to receive commits

refspec - commits to be pushed

Throws:

GitException - if underlying git operating fails

InterruptedException - if interrupted

getBranchesContaining

@Deprecated
public List<Branch> getBranchesContaining(String revspec)
                                   throws GitException,
                                          InterruptedException

Deprecated.

Find all the branches that include the given commit.

Parameters:

revspec - substring to be searched for branch name

Returns:

list of branches containing revspec

Throws:

GitException - on failure

InterruptedException - if interrupted

getBranchesContaining

public List<Branch> getBranchesContaining(String revspec,
                                          boolean allBranches)
                                   throws GitException,
                                          InterruptedException

Find all the branches that include the given commit.

Parameters:

revspec - commit id to query for

allBranches - whether remote branches should be also queried (true) or not (false)

Returns:

list of branches the specified commit belongs to

Throws:

GitException - on Git exceptions

InterruptedException - on thread interruption

mergeBase

@Deprecated
public org.eclipse.jgit.lib.ObjectId mergeBase(org.eclipse.jgit.lib.ObjectId id1,
                                               org.eclipse.jgit.lib.ObjectId id2)
                                        throws InterruptedException

Deprecated.

mergeBase.

Parameters:

id1 - a ObjectId object.

id2 - a ObjectId object.

Returns:

a ObjectId object.

Throws:

InterruptedException - if interrupted.

getAllLogEntries

@Deprecated
public String getAllLogEntries(String branch)
                        throws InterruptedException

Deprecated.

This method makes no sense, in that it lists all log entries across all refs and yet it takes a meaningless 'branch' parameter. Please do not use this.

Parameters:

branch - a String object.

Returns:

a String object.

Throws:

InterruptedException - if interrupted.

getTags

public Set<GitObject> getTags()
                       throws GitException,
                              InterruptedException

Return name and object ID of all tags in current repository.

Returns:

set of tags in current repository

Throws:

GitException - on Git exceptions

InterruptedException - on thread interruption

maintenance

public boolean maintenance(String task)
                    throws InterruptedException

Executes git maintenance commands based on the git version.

Parameters:

task - a String object. i.e (prefetch/gc/commit-graph/incremental-repack/loose-objects)

Returns:

Boolean if maintenance has been executed or not.

Throws:

InterruptedException - if underlying git operation fails.

config

public void config(GitClient.ConfigLevel configLevel,
                   String key,
                   String value)
            throws GitException,
                   InterruptedException

Execute git config at the specified configuration level. If value is null, the key will be removed from the configuration.

Parameters:

configLevel - configuration level that will be modified. If null, then GitClient.ConfigLevel.LOCAL will be used.

key - configuration section expressed as section[.subsection].name

value - configuration value. If null, the key will be removed from the configuration (unset)

Throws:

GitException - on Git exception

InterruptedException - on thread interruption

isBareRepository

public boolean isBareRepository()
                         throws GitException,
                                InterruptedException

isBareRepository.

Specified by:

isBareRepository in interface IGitAPI

Returns:

true if this repository is a bare repository

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

getHostKeyFactory

public HostKeyVerifierFactory getHostKeyFactory()

setHostKeyFactory

public void setHostKeyFactory(HostKeyVerifierFactory verifier)

hasGitModules

@Deprecated
public boolean hasGitModules(String treeIsh)
                      throws GitException

Deprecated.

Returns true if this repository has submodules.

Specified by:

hasGitModules in interface IGitAPI

Parameters:

treeIsh - an ignored argument, kept for compatibility

Returns:

true if this repository has submodules (git modules file)

Throws:

GitException - if underlying git operation fails.

See Also:

GitClient.hasGitModules()

setupSubmoduleUrls

@Deprecated
public void setupSubmoduleUrls(String remote,
                               TaskListener listener)
                        throws GitException,
                               InterruptedException

Deprecated.

Specified by:

setupSubmoduleUrls in interface IGitAPI

Throws:

GitException

InterruptedException

fetch

@Deprecated
public void fetch(String repository,
                  String refspec)
           throws GitException,
                  InterruptedException

Deprecated.

Retrieve commits based on refspec from repository.

Specified by:

fetch in interface IGitAPI

Parameters:

repository - URL of the repository to be retrieved

refspec - definition of mapping from remote refs to local refs

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

fetch

@Deprecated
public void fetch(org.eclipse.jgit.transport.RemoteConfig remoteRepository)
           throws InterruptedException

Deprecated.

Retrieve commits from RemoteConfig.

Specified by:

fetch in interface IGitAPI

Parameters:

remoteRepository - remote configuration from which refs will be retrieved

Throws:

InterruptedException - if interrupted.

fetch

@Deprecated
public void fetch()
           throws GitException,
                  InterruptedException

Deprecated.

fetch.

Specified by:

fetch in interface IGitAPI

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

reset

@Deprecated
public void reset()
           throws GitException,
                  InterruptedException

Deprecated.

reset.

Specified by:

reset in interface IGitAPI

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

push

@Deprecated
public void push(org.eclipse.jgit.transport.URIish url,
                 String refspec)
          throws GitException,
                 InterruptedException

Deprecated.

push.

Specified by:

push in interface GitClient

Parameters:

url - a URIish object.

refspec - a String object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

push

@Deprecated
public void push(String remoteName,
                 String refspec)
          throws GitException,
                 InterruptedException

Deprecated.

push.

Specified by:

push in interface GitClient

Parameters:

remoteName - a String object.

refspec - a String object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

clone

@Deprecated
public void clone(org.eclipse.jgit.transport.RemoteConfig source)
           throws GitException,
                  InterruptedException

Deprecated.

Clone repository from source to this repository.

Specified by:

clone in interface IGitAPI

Parameters:

source - remote repository to be cloned

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

clone

@Deprecated
public void clone(org.eclipse.jgit.transport.RemoteConfig rc,
                  boolean useShallowClone)
           throws GitException,
                  InterruptedException

Deprecated.

Clone repository from RemoteConfig rc to this repository.

Specified by:

clone in interface IGitAPI

Parameters:

rc - the remote config for the remote repository

useShallowClone - if true, use a shallow clone

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

revListBranch

@Deprecated
public List<org.eclipse.jgit.lib.ObjectId> revListBranch(String branchId)
                                                  throws GitException,
                                                         InterruptedException

Deprecated.

revListBranch.

Specified by:

revListBranch in interface IGitAPI

Parameters:

branchId - a String object.

Returns:

a List object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

showRevision

@Deprecated
public List<String> showRevision(Revision r)
                          throws GitException,
                                 InterruptedException

Deprecated.

showRevision.

Specified by:

showRevision in interface IGitAPI

Parameters:

r - a Revision object.

Returns:

a List object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

getTagsOnCommit

@Deprecated
public List<Tag> getTagsOnCommit(String revName)
                          throws GitException,
                                 IOException

Deprecated.

getTagsOnCommit.

Specified by:

getTagsOnCommit in interface IGitAPI

Parameters:

revName - a String object.

Returns:

a List object.

Throws:

GitException - if underlying git operation fails.

IOException - if any IO failure

lsTree

public final List<IndexEntry> lsTree(String treeIsh)
                              throws GitException,
                                     InterruptedException

This method has been implemented as non-recursive historically, but often that is not what the caller wants.

Specified by:

lsTree in interface IGitAPI

Parameters:

treeIsh - string representation of a treeIsh item

Returns:

list of IndexEntry items starting at treeIsh

Throws:

GitException - on failure

InterruptedException - if interrupted

writeReplace

protected Object writeReplace()
                       throws ObjectStreamException

When sent to remote, switch to the proxy.

Returns:

a Object object.

Throws:

ObjectStreamException - if current channel is null

hasGitModules

public boolean hasGitModules()
                      throws GitException

hasGitModules.

Specified by:

hasGitModules in interface GitClient

Returns:

true if this repositor has one or more submodules

Throws:

GitException - if underlying git operation fails.

showRevision

public List<String> showRevision(org.eclipse.jgit.lib.ObjectId r)
                          throws GitException,
                                 InterruptedException

Given a Revision, show it as if it were an entry from git whatchanged, so that it can be parsed by GitChangeLogParser.

Changes are computed on the [from..to] range. If from is null, this prints just one commit that to represents.

For merge commit, this method reports one diff per each parent. This makes this method behave differently from GitClient.changelog().

Specified by:

showRevision in interface GitClient

Parameters:

r - a ObjectId object.

Returns:

The git whatchanged output, in raw format.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

extractBranchNameFromBranchSpec

protected String extractBranchNameFromBranchSpec(String branchSpec)

This method takes a branch specification and normalizes it get unambiguous results. This is the case when using "refs/heads/"

TODO: Currently only for specs starting with "refs/heads/" the implementation is correct. All others branch specs should also be normalized to "refs/heads/" in order to get unambiguous results. To achieve this it is necessary to identify remote names in the branch spec and to discuss how to handle clashes (e.g. "remoteName/main" for branch "main" (refs/heads/main) in remote "remoteName" and branch "remoteName/main" (refs/heads/remoteName/main)).

Existing behavior is intentionally being retained so that current use cases are not disrupted by a behavioral change.

E.g.

Branch Spec Normalization Examples

branch spec	normalized
main	main*
feature1	feature1*
feature1/main	main feature1/main*
origin/main	main*
repo2/feature1	feature1*
refs/heads/feature1	refs/heads/feature1
origin/namespaceA/fix15	fix15 namespaceA/fix15*
refs/heads/namespaceA/fix15	refs/heads/namespaceA/fix15
remotes/origin/namespaceA/fix15	refs/heads/namespaceA/fix15

*) TODO: Normalize to "refs/heads/"

Parameters:

branchSpec - a String object.

Returns:

normalized branch name

withRepository

public <T> T withRepository(RepositoryCallback<T> callable)
                     throws IOException,
                            InterruptedException

Runs the computation that requires local access to Repository.

Specified by:

withRepository in interface GitClient

Type Parameters:

T - type for the repository callback

Parameters:

callable - the repository callback used as closure to instance

Returns:

a T object.

Throws:

IOException - in case of IO error

InterruptedException - if interrupted

commit

public void commit(String message,
                   org.eclipse.jgit.lib.PersonIdent author,
                   org.eclipse.jgit.lib.PersonIdent committer)
            throws GitException,
                   InterruptedException

commit.

Specified by:

commit in interface GitClient

Parameters:

message - a String object.

author - a PersonIdent object.

committer - a PersonIdent object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

setAuthor

public void setAuthor(org.eclipse.jgit.lib.PersonIdent p)

setAuthor.

Specified by:

setAuthor in interface GitClient

Parameters:

p - a PersonIdent object.

setCommitter

public void setCommitter(org.eclipse.jgit.lib.PersonIdent p)

setCommitter.

Specified by:

setCommitter in interface GitClient

Parameters:

p - a PersonIdent object.

changelog

public void changelog(String revFrom,
                      String revTo,
                      OutputStream outputStream)
               throws GitException,
                      InterruptedException

changelog.

Specified by:

changelog in interface GitClient

Parameters:

revFrom - a String object.

revTo - a String object.

outputStream - a OutputStream object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

changelog

public void changelog(String revFrom,
                      String revTo,
                      Writer w)
               throws GitException,
                      InterruptedException

Adds the changelog entries for commits in the range revFrom..revTo. This is just a short cut for calling GitClient.changelog() with appropriate parameters.

Specified by:

changelog in interface GitClient

Parameters:

revFrom - a String object.

revTo - a String object.

w - a Writer object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

clone

public void clone(String url,
                  String origin,
                  boolean useShallowClone,
                  String reference)
           throws GitException,
                  InterruptedException

Clone a remote repository

Specified by:

clone in interface GitClient

Parameters:

url - URL for remote repository to clone

origin - upstream track name, defaults to origin by convention

useShallowClone - option to create a shallow clone, that has some restriction but will make clone operation

reference - (optional) reference to a local clone for faster clone operations (reduce network and local storage costs)

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

checkout

public void checkout(String commit)
              throws GitException,
                     InterruptedException

Checks out the specified commit/tag/branch into the workspace. (equivalent of git checkout branch.)

Specified by:

checkout in interface GitClient

Parameters:

commit - A git object references expression (either a sha1, tag or branch)

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

checkout

public void checkout(String ref,
                     String branch)
              throws GitException,
                     InterruptedException

Creates a new branch that points to the specified ref. (equivalent to git checkout -b branch commit) This will fail if the branch already exists.

Specified by:

checkout in interface GitClient

Parameters:

ref - A git object references expression. For backward compatibility, null will checkout current HEAD

branch - name of the branch to create from reference

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

checkoutBranch

public void checkoutBranch(String branch,
                           String ref)
                    throws GitException,
                           InterruptedException

Regardless of the current state of the workspace (whether there is some dirty files, etc) and the state of the repository (whether the branch of the specified name exists or not), when this method exits the following conditions hold:

• The branch of the specified name branch exists and points to the specified ref
• HEAD points to branch. In other words, the workspace is on the specified branch.
• Both index and workspace are the same tree with ref. (no dirty files and no staged changes, although this method will not touch untracked files in the workspace.)

This method is preferred over the GitClient.checkout(String, String) family of methods, as this method is affected far less by the current state of the repository. The checkout methods, in their attempt to emulate the "git checkout" command line behaviour, have too many side effects. In Jenkins, where you care a lot less about throwing away local changes and care a lot more about resetting the workspace into a known state, methods like this is more useful.

For compatibility reasons, the order of the parameter is different from GitClient.checkout(String, String).

Specified by:

checkoutBranch in interface GitClient

Parameters:

branch - a String object.

ref - a String object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

merge

public void merge(org.eclipse.jgit.lib.ObjectId rev)
           throws GitException,
                  InterruptedException

merge.

Specified by:

merge in interface GitClient

Parameters:

rev - a ObjectId object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

remoteProxyFor

protected org.jenkinsci.plugins.gitclient.RemoteGitImpl remoteProxyFor(GitClient proxy)

remoteProxyFor.

Parameters:

proxy - a GitClient object.

Returns:

a RemoteGitImpl object.

setCredentials

public void setCredentials(com.cloudbees.plugins.credentials.common.StandardUsernameCredentials cred)

setCredentials.

Specified by:

setCredentials in interface GitClient

Parameters:

cred - a StandardUsernameCredentials object.

setProxy

public void setProxy(ProxyConfiguration proxy)

setProxy.

Specified by:

setProxy in interface GitClient

Parameters:

proxy - a ProxyConfiguration object.

submoduleUpdate

public void submoduleUpdate(boolean recursive)
                     throws GitException,
                            InterruptedException

Run submodule update optionally recursively on all submodules (equivalent of git submodule update --recursive.)

Specified by:

submoduleUpdate in interface GitClient

Parameters:

recursive - a boolean.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

submoduleUpdate

public void submoduleUpdate(boolean recursive,
                            String reference)
                     throws GitException,
                            InterruptedException

Run submodule update optionally recursively on all submodules, with a specific reference passed to git clone if needing to --init. (equivalent of git submodule update --recursive --reference 'reference'.)

Specified by:

submoduleUpdate in interface GitClient

Parameters:

recursive - a boolean.

reference - a String object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

submoduleUpdate

public void submoduleUpdate(boolean recursive,
                            boolean remoteTracking)
                     throws GitException,
                            InterruptedException

Run submodule update optionally recursively on all submodules, optionally with remoteTracking submodules (equivalent of git submodule update --recursive --remote.)

Specified by:

submoduleUpdate in interface GitClient

Parameters:

recursive - a boolean.

remoteTracking - a boolean.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.

submoduleUpdate

public void submoduleUpdate(boolean recursive,
                            boolean remoteTracking,
                            String reference)
                     throws GitException,
                            InterruptedException

Run submodule update optionally recursively on all submodules, optionally with remoteTracking, with a specific reference passed to git clone if needing to --init. (equivalent of git submodule update --recursive --remote --reference 'reference'.)

Specified by:

submoduleUpdate in interface GitClient

Parameters:

recursive - a boolean.

remoteTracking - a boolean.

reference - a String object.

Throws:

GitException - if underlying git operation fails.

InterruptedException - if interrupted.