Package 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, FirstBuildChangelog, 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 Details

    • GitSCMExtension

      public GitSCMExtension()

  • Method Details

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