hudson.plugins.git.extensions

Class GitSCMExtension

java.lang.Object

hudson.model.AbstractDescribableImpl<GitSCMExtension>

hudson.plugins.git.extensions.GitSCMExtension

All Implemented Interfaces:

Describable<GitSCMExtension>

Direct Known Subclasses:

BuildSingleRevisionOnly, ChangelogToBranch, CleanBeforeCheckout, CleanCheckout, CloneOption, DisableRemotePoll, FakeGitSCMExtension, GitLFSPull, GitSCMSourceDefaults, MergeWithGitSCMExtension, MessageExclusion, PathRestriction, PerBuildTag, PreBuildMerge, PruneStaleBranch, PruneStaleTag, RelativeTargetDirectory, SparseCheckoutPaths, SubmoduleOption, UserExclusion, UserIdentity, WipeWorkspace

public abstract class GitSCMExtension
extends AbstractDescribableImpl<GitSCMExtension>

Extension point to tweak the behaviour of GitSCM.

Since:

2.0.0

Author:

Kohsuke Kawaguchi

Constructor Summary

Constructors

Constructor and Description
GitSCMExtension()

Method Summary

Modifier and Type	Method and Description
void	beforeCheckout(GitSCM scm, AbstractBuild<?,?> build, org.jenkinsci.plugins.gitclient.GitClient git, BuildListener listener) Deprecated.
void	beforeCheckout(GitSCM scm, Run<?,?> build, org.jenkinsci.plugins.gitclient.GitClient git, TaskListener listener) Called before the checkout activity (including fetch and checkout) starts.
org.jenkinsci.plugins.gitclient.GitClient	decorate(GitSCM scm, org.jenkinsci.plugins.gitclient.GitClient git) Called when GitClient is created to decorate its behaviour.
void	decorateCheckoutCommand(GitSCM scm, AbstractBuild<?,?> build, org.jenkinsci.plugins.gitclient.GitClient git, BuildListener listener, org.jenkinsci.plugins.gitclient.CheckoutCommand cmd) Deprecated.
void	decorateCheckoutCommand(GitSCM scm, Run<?,?> build, org.jenkinsci.plugins.gitclient.GitClient git, TaskListener listener, org.jenkinsci.plugins.gitclient.CheckoutCommand cmd) Called before a CheckoutCommand is executed to allow extensions to alter its behaviour.
void	decorateCloneCommand(GitSCM scm, AbstractBuild<?,?> build, org.jenkinsci.plugins.gitclient.GitClient git, BuildListener listener, org.jenkinsci.plugins.gitclient.CloneCommand cmd) Deprecated.
void	decorateCloneCommand(GitSCM scm, Run<?,?> build, org.jenkinsci.plugins.gitclient.GitClient git, TaskListener listener, org.jenkinsci.plugins.gitclient.CloneCommand cmd) Called before a CloneCommand is executed to allow extensions to alter its behaviour.
void	decorateFetchCommand(GitSCM scm, org.jenkinsci.plugins.gitclient.GitClient git, TaskListener listener, org.jenkinsci.plugins.gitclient.FetchCommand cmd) Deprecated. use decorateCheckoutCommand(GitSCM, Run, GitClient, TaskListener, CheckoutCommand)
void	decorateFetchCommand(GitSCM scm, Run<?,?> run, org.jenkinsci.plugins.gitclient.GitClient git, TaskListener listener, org.jenkinsci.plugins.gitclient.FetchCommand cmd) Called before a FetchCommand is executed to allow extensions to alter its behaviour.
void	decorateMergeCommand(GitSCM scm, AbstractBuild<?,?> build, org.jenkinsci.plugins.gitclient.GitClient git, BuildListener listener, org.jenkinsci.plugins.gitclient.MergeCommand cmd) Deprecated.
void	decorateMergeCommand(GitSCM scm, Run<?,?> build, org.jenkinsci.plugins.gitclient.GitClient git, TaskListener listener, org.jenkinsci.plugins.gitclient.MergeCommand cmd) Called before a MergeCommand is executed to allow extensions to alter its behaviour.
hudson.plugins.git.Revision	decorateRevisionToBuild(GitSCM scm, AbstractBuild<?,?> build, org.jenkinsci.plugins.gitclient.GitClient git, BuildListener listener, hudson.plugins.git.Revision marked, hudson.plugins.git.Revision rev) Deprecated.
hudson.plugins.git.Revision	decorateRevisionToBuild(GitSCM scm, Run<?,?> build, org.jenkinsci.plugins.gitclient.GitClient git, TaskListener listener, hudson.plugins.git.Revision marked, hudson.plugins.git.Revision rev) Called after BuildChooser selects the revision to pick for this build, but before
void	determineSupportForJGit(GitSCM scm, org.jenkinsci.plugins.gitclient.UnsupportedCommand unsupportedCommand) Called when support of JGit for a particular or multiple extensions is to be determined
boolean	enableMultipleRevisionDetection()
GitSCMExtensionDescriptor	getDescriptor()
GitClientType	getRequiredClient() Let extension declare required GitClient implementation.
FilePath	getWorkingDirectory(GitSCM scm, AbstractProject<?,?> context, FilePath workspace, EnvVars environment, TaskListener listener) Deprecated.
FilePath	getWorkingDirectory(GitSCM scm, Job<?,?> context, FilePath workspace, EnvVars environment, TaskListener listener) Given the workspace root directory, gets the working directory, which is where the repository will be checked out.
Boolean	isRevExcluded(GitSCM scm, org.jenkinsci.plugins.gitclient.GitClient git, GitChangeSet commit, TaskListener listener, BuildData buildData) Given a commit found during polling, check whether it should be disregarded.
void	onCheckoutCompleted(GitSCM scm, AbstractBuild<?,?> build, org.jenkinsci.plugins.gitclient.GitClient git, BuildListener listener) Deprecated.
void	onCheckoutCompleted(GitSCM scm, Run<?,?> build, org.jenkinsci.plugins.gitclient.GitClient git, TaskListener listener) Called when the checkout was completed and the working directory is filled with files.
void	onClean(GitSCM scm, org.jenkinsci.plugins.gitclient.GitClient git) Signals when "git-clean" runs.
void	populateEnvironmentVariables(GitSCM scm, Map<String,String> env) Contribute additional environment variables for the Git invocation.
boolean	requiresWorkspaceForPolling()

Methods inherited from class java.lang.Object

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

Constructor Detail

GitSCMExtension

public GitSCMExtension()

Method Detail

requiresWorkspaceForPolling

public boolean requiresWorkspaceForPolling()

Returns:

true when this extension has a requirement to get a workspace during polling, typically as it has to check for incoming changes, not just remote HEAD.

isRevExcluded

@CheckForNull
public Boolean isRevExcluded(GitSCM scm,
                                           org.jenkinsci.plugins.gitclient.GitClient git,
                                           GitChangeSet commit,
                                           TaskListener listener,
                                           BuildData buildData)
                                    throws IOException,
                                           InterruptedException,
                                           hudson.plugins.git.GitException

Given a commit found during polling, check whether it should be disregarded.

Parameters:

scm - GitSCM object

git - GitClient object

commit - The commit whose exclusion is being tested.

listener - build log

buildData - build data to be used

Returns:

true to disregard this commit and not trigger a build, regardless of what later GitSCMExtensions say. false to trigger a build from this commit, regardless of what later GitSCMExtensions say. null to allow other GitSCMExtensions to decide.

Throws:

IOException - on input or output error

InterruptedException - when interrupted

hudson.plugins.git.GitException - on git error

getWorkingDirectory

public FilePath getWorkingDirectory(GitSCM scm,
                                    Job<?,?> context,
                                    FilePath workspace,
                                    EnvVars environment,
                                    TaskListener listener)
                             throws IOException,
                                    InterruptedException,
                                    hudson.plugins.git.GitException

Given the workspace root directory, gets the working directory, which is where the repository will be checked out.

Parameters:

scm - GitSCM object

context - job context for workspace root

workspace - starting directory of workspace

environment - environment variables used to eval

listener - build log

Returns:

working directory or null to let other GitSCMExtension control it.

Throws:

IOException - on input or output error

InterruptedException - when interrupted

hudson.plugins.git.GitException - on git error

getWorkingDirectory

@Deprecated
public FilePath getWorkingDirectory(GitSCM scm,
                                                AbstractProject<?,?> context,
                                                FilePath workspace,
                                                EnvVars environment,
                                                TaskListener listener)
                                         throws IOException,
                                                InterruptedException,
                                                hudson.plugins.git.GitException

Deprecated.

Throws:

IOException

InterruptedException

hudson.plugins.git.GitException

decorateRevisionToBuild

public hudson.plugins.git.Revision decorateRevisionToBuild(GitSCM scm,
                                                           Run<?,?> build,
                                                           org.jenkinsci.plugins.gitclient.GitClient git,
                                                           TaskListener listener,
                                                           hudson.plugins.git.Revision marked,
                                                           hudson.plugins.git.Revision rev)
                                                    throws IOException,
                                                           InterruptedException,
                                                           hudson.plugins.git.GitException

Called after BuildChooser selects the revision to pick for this build, but before

This allows extensions to select a derived revision (for example by merging another branch into the chosen revision and returning it) or manipulate the state of the working tree (such as running git-clean.)

decorateRevisionToBuild(GitSCM, Run, GitClient, TaskListener, Revision, Revision) vs BuildChooser

BuildChooser and this method are similar in the sense that they both participate in the process of determining what commits to build. So when a plugin wants to control the commit to be built, you have a choice of these two approaches. The rule of the thumb is to ask yourself if your process takes another commit as an input. BuildChooser is suitable when you do not take any commit as a parameter, and need to precisely control what commit to build. For example the gerrit-trigger plugin looks at a specific build parameter, then retrieves that commit from Gerrit and builds that. decorateRevisionToBuild(GitSCM, Run, GitClient, TaskListener, Revision, Revision) is suitable when you accept arbitrary revision as an input and then create some derivative commits and then build that result. The primary example is for speculative merge with another branch (people use this to answer the question of "what happens if I were to integrate this feature branch back to the master branch?")

Parameters:

scm - GitSCM object

git - GitClient object

build - run context

listener - build log

marked - The revision that started this build. (e.g. pre-merge)

rev - The revision selected for this build.

Returns:

The revision selected for this build. Unless you are decorating the given rev, return the value given in the rev parameter.

Throws:

IOException - on input or output error

InterruptedException - when interrupted

hudson.plugins.git.GitException - on git error

decorateRevisionToBuild

@Deprecated
public hudson.plugins.git.Revision decorateRevisionToBuild(GitSCM scm,
                                                                       AbstractBuild<?,?> build,
                                                                       org.jenkinsci.plugins.gitclient.GitClient git,
                                                                       BuildListener listener,
                                                                       hudson.plugins.git.Revision marked,
                                                                       hudson.plugins.git.Revision rev)
                                                                throws IOException,
                                                                       InterruptedException,
                                                                       hudson.plugins.git.GitException

Deprecated.

Throws:

IOException

InterruptedException

hudson.plugins.git.GitException

beforeCheckout

public void beforeCheckout(GitSCM scm,
                           Run<?,?> build,
                           org.jenkinsci.plugins.gitclient.GitClient git,
                           TaskListener listener)
                    throws IOException,
                           InterruptedException,
                           hudson.plugins.git.GitException

Called before the checkout activity (including fetch and checkout) starts.

Parameters:

scm - GitSCM object

build - run context

git - GitClient

listener - build log

Throws:

IOException - on input or output error

InterruptedException - when interrupted

hudson.plugins.git.GitException - on git error

beforeCheckout

@Deprecated
public void beforeCheckout(GitSCM scm,
                                       AbstractBuild<?,?> build,
                                       org.jenkinsci.plugins.gitclient.GitClient git,
                                       BuildListener listener)
                                throws IOException,
                                       InterruptedException,
                                       hudson.plugins.git.GitException

Deprecated.

Throws:

IOException

InterruptedException

hudson.plugins.git.GitException

onCheckoutCompleted

public void onCheckoutCompleted(GitSCM scm,
                                Run<?,?> build,
                                org.jenkinsci.plugins.gitclient.GitClient git,
                                TaskListener listener)
                         throws IOException,
                                InterruptedException,
                                hudson.plugins.git.GitException

Called when the checkout was completed and the working directory is filled with files. See SCM.checkout(Run, Launcher, FilePath, TaskListener, File, SCMRevisionState) for the available parameters, except workingDirectory Do not move the HEAD to another commit, as by this point the commit to be built is already determined and recorded (such as changelog.)

Parameters:

scm - GitSCM object

build - run context

git - GitClient

listener - build log

Throws:

IOException - on input or output error

InterruptedException - when interrupted

hudson.plugins.git.GitException - on git error

onCheckoutCompleted

@Deprecated
public void onCheckoutCompleted(GitSCM scm,
                                            AbstractBuild<?,?> build,
                                            org.jenkinsci.plugins.gitclient.GitClient git,
                                            BuildListener listener)
                                     throws IOException,
                                            InterruptedException,
                                            hudson.plugins.git.GitException

Deprecated.

Throws:

IOException

InterruptedException

hudson.plugins.git.GitException

onClean

public void onClean(GitSCM scm,
                    org.jenkinsci.plugins.gitclient.GitClient git)
             throws IOException,
                    InterruptedException,
                    hudson.plugins.git.GitException

Signals when "git-clean" runs. Primarily for running "git submodule clean" TODO: revisit the abstraction

Parameters:

scm - GitSCM object

git - GitClient

Throws:

IOException - on input or output error

InterruptedException - when interrupted

hudson.plugins.git.GitException - on git error

decorate

public org.jenkinsci.plugins.gitclient.GitClient decorate(GitSCM scm,
                                                          org.jenkinsci.plugins.gitclient.GitClient git)
                                                   throws IOException,
                                                          InterruptedException,
                                                          hudson.plugins.git.GitException

Called when GitClient is created to decorate its behaviour. This allows extensions to customize the behaviour of GitClient.

Parameters:

scm - GitSCM object

git - GitClient

Returns:

GitClient to decorate

Throws:

IOException - on input or output error

InterruptedException - when interrupted

hudson.plugins.git.GitException - on git error

determineSupportForJGit

public void determineSupportForJGit(GitSCM scm,
                                    @NonNull
                                    org.jenkinsci.plugins.gitclient.UnsupportedCommand unsupportedCommand)

Called when support of JGit for a particular or multiple extensions is to be determined

Parameters:

scm - GitSCM object

unsupportedCommand - UnsupportedCommand object

decorateCloneCommand

public void decorateCloneCommand(GitSCM scm,
                                 Run<?,?> build,
                                 org.jenkinsci.plugins.gitclient.GitClient git,
                                 TaskListener listener,
                                 org.jenkinsci.plugins.gitclient.CloneCommand cmd)
                          throws IOException,
                                 InterruptedException,
                                 hudson.plugins.git.GitException

Called before a CloneCommand is executed to allow extensions to alter its behaviour.

Parameters:

scm - GitSCM object

build - run context

git - GitClient

listener - build log

cmd - clone command to be decorated

Throws:

IOException - on input or output error

InterruptedException - when interrupted

hudson.plugins.git.GitException - on git error

decorateCloneCommand

@Deprecated
public void decorateCloneCommand(GitSCM scm,
                                             AbstractBuild<?,?> build,
                                             org.jenkinsci.plugins.gitclient.GitClient git,
                                             BuildListener listener,
                                             org.jenkinsci.plugins.gitclient.CloneCommand cmd)
                                      throws IOException,
                                             InterruptedException,
                                             hudson.plugins.git.GitException

Deprecated.

Throws:

IOException

InterruptedException

hudson.plugins.git.GitException

decorateFetchCommand

@Deprecated
public void decorateFetchCommand(GitSCM scm,
                                             org.jenkinsci.plugins.gitclient.GitClient git,
                                             TaskListener listener,
                                             org.jenkinsci.plugins.gitclient.FetchCommand cmd)
                                      throws IOException,
                                             InterruptedException,
                                             hudson.plugins.git.GitException

Deprecated. use decorateCheckoutCommand(GitSCM, Run, GitClient, TaskListener, CheckoutCommand)

Called before a FetchCommand is executed to allow extensions to alter its behaviour.

Parameters:

scm - GitSCM object

git - GitClient

listener - build log

cmd - fetch command to be decorated

Throws:

IOException - on input or output error

InterruptedException - when interrupted

hudson.plugins.git.GitException - on git error

decorateFetchCommand

public void decorateFetchCommand(GitSCM scm,
                                 @CheckForNull
                                 Run<?,?> run,
                                 org.jenkinsci.plugins.gitclient.GitClient git,
                                 TaskListener listener,
                                 org.jenkinsci.plugins.gitclient.FetchCommand cmd)
                          throws IOException,
                                 InterruptedException,
                                 hudson.plugins.git.GitException

Called before a FetchCommand is executed to allow extensions to alter its behaviour.

Parameters:

scm - GitSCM object

run - Run when fetch is called for Run. null during Job polling.

git - GitClient

listener - build log

cmd - fetch command to be decorated

Throws:

IOException - on input or output error

InterruptedException - when interrupted

hudson.plugins.git.GitException - on git error

decorateMergeCommand

public void decorateMergeCommand(GitSCM scm,
                                 Run<?,?> build,
                                 org.jenkinsci.plugins.gitclient.GitClient git,
                                 TaskListener listener,
                                 org.jenkinsci.plugins.gitclient.MergeCommand cmd)
                          throws IOException,
                                 InterruptedException,
                                 hudson.plugins.git.GitException

Called before a MergeCommand is executed to allow extensions to alter its behaviour.

Parameters:

scm - GitSCM object

build - run context

git - GitClient

listener - build log

cmd - merge command to be decorated

Throws:

IOException - on input or output error

InterruptedException - when interrupted

hudson.plugins.git.GitException - on git error

decorateMergeCommand

@Deprecated
public void decorateMergeCommand(GitSCM scm,
                                             AbstractBuild<?,?> build,
                                             org.jenkinsci.plugins.gitclient.GitClient git,
                                             BuildListener listener,
                                             org.jenkinsci.plugins.gitclient.MergeCommand cmd)
                                      throws IOException,
                                             InterruptedException,
                                             hudson.plugins.git.GitException

Deprecated.

Throws:

IOException

InterruptedException

hudson.plugins.git.GitException

decorateCheckoutCommand

public void decorateCheckoutCommand(GitSCM scm,
                                    Run<?,?> build,
                                    org.jenkinsci.plugins.gitclient.GitClient git,
                                    TaskListener listener,
                                    org.jenkinsci.plugins.gitclient.CheckoutCommand cmd)
                             throws IOException,
                                    InterruptedException,
                                    hudson.plugins.git.GitException

Called before a CheckoutCommand is executed to allow extensions to alter its behaviour.

Parameters:

scm - GitSCM object

build - run context

git - GitClient

listener - build log

cmd - checkout command to be decorated

Throws:

IOException - on input or output error

InterruptedException - when interrupted

hudson.plugins.git.GitException - on git error

decorateCheckoutCommand

@Deprecated
public void decorateCheckoutCommand(GitSCM scm,
                                                AbstractBuild<?,?> build,
                                                org.jenkinsci.plugins.gitclient.GitClient git,
                                                BuildListener listener,
                                                org.jenkinsci.plugins.gitclient.CheckoutCommand cmd)
                                         throws IOException,
                                                InterruptedException,
                                                hudson.plugins.git.GitException

Deprecated.

Throws:

IOException

InterruptedException

hudson.plugins.git.GitException

populateEnvironmentVariables

public void populateEnvironmentVariables(GitSCM scm,
                                         Map<String,String> env)

Contribute additional environment variables for the Git invocation.

Parameters:

scm - GitSCM used as reference

env - environment variables to be added

getRequiredClient

public GitClientType getRequiredClient()

Let extension declare required GitClient implementation. git-plugin will then detect conflicts, and fallback to globally configured default git client

Returns:

git client type required for this extension

enableMultipleRevisionDetection

public boolean enableMultipleRevisionDetection()

Returns:

true to disable the scheduling of another build to catch up when multiple revisions are detected

getDescriptor

public GitSCMExtensionDescriptor getDescriptor()

Specified by:

getDescriptor in interface Describable<GitSCMExtension>

Overrides:

getDescriptor in class AbstractDescribableImpl<GitSCMExtension>