Package hudson.scm

Class SCM

  • All Implemented Interfaces:
    ExtensionPoint, Describable<SCM>
    Direct Known Subclasses:
    NullSCM
    @ExportedBean
public abstract class SCM
extends Object
implements Describable<SCM>, ExtensionPoint
    Captures the configuration information in it.

    To register a custom SCM implementation from a plugin, put Extension on your SCMDescriptor.

    Use the "project-changes" view to render change list to be displayed at the project level. The default implementation simply aggregates change lists from builds, but your SCM can provide different views. The view gets the "builds" variable which is a list of builds that are selected for the display.

    If you are interested in writing a subclass in a plugin, also take a look at "Writing an SCM plugin" wiki article.

    Author:
    Kohsuke Kawaguchi

    • Field Detail

      • TAG

        public static final Permission TAG
        Permission to create new tags.
        Since:
        1.171

    • Constructor Detail

      • SCM

        public SCM()

    • Method Detail

      • getApi

        public Api getApi()
        Expose SCM to the remote API.

      • getType

        @Exported
public String getType()
        Type of this SCM. Exposed so that the client of the remote API can tell what SCM this is.

      • supportsPolling

        public boolean supportsPolling()
        Returns true if this SCM supports poling.
        Since:
        1.105

      • requiresWorkspaceForPolling

        public boolean requiresWorkspaceForPolling()
        Returns true if this SCM requires a checked out workspace for doing polling.

        This flag affects the behavior of Hudson when a job lost its workspace (typically due to a agent outage.) If this method returns true and polling is configured, then that would usually trigger a new build.

        This flag also affects the mutual exclusion control between builds and polling. If this methods returns false, polling will continue asynchronously even when a build is in progress, but otherwise the polling activity is blocked if a build is currently using a workspace.

        The default implementation returns true.

        See issue JENKINS-1348 for more discussion of this feature.

        Since:
        1.196

      • processWorkspaceBeforeDeletion

        public boolean processWorkspaceBeforeDeletion​(@NonNull
                                              Job<?,​?> project,
                                              @NonNull
                                              FilePath workspace,
                                              @NonNull
                                              Node node)
                                       throws IOException,
                                              InterruptedException
        Called before a workspace is deleted on the given node, to provide SCM an opportunity to perform clean up.

        Hudson periodically scans through all the agents and removes old workspaces that are deemed unnecessary. This behavior is implemented in WorkspaceCleanupThread, and it is necessary to control the disk consumption on agents. If we don't do this, in a long run, all the agents will have workspaces for all the projects, which will be prohibitive in big Hudson.

        However, some SCM implementations require that the server be made aware of deletion of the local workspace, and this method provides an opportunity for SCMs to perform such a clean-up act.

        This call back is invoked after Hudson determines that a workspace is unnecessary, but before the actual recursive directory deletion happens.

        Note that this method does not guarantee that such a clean up will happen. For example, agents can be taken offline by being physically removed from the network, and in such a case there's no opportunity to perform this clean up.

        This method is also invoked when the project is deleted.

        Parameters:
        project - The project that owns this SCM. This is always the same object for a particular instance of SCM. Just passed in here so that SCM itself doesn't have to remember the value.
        workspace - The workspace which is about to be deleted. This can be a remote file path.
        node - The node that hosts the workspace. SCM can use this information to determine the course of action.
        Returns:
        true if SCM is OK to let Hudson proceed with deleting the workspace. False to veto the workspace deletion.
        Throws:
        IOException
        InterruptedException
        Since:
        1.568

      • getKey

        @NonNull
public String getKey()
        Should create a key by which this SCM configuration might be distinguished from others in the same project. Should be invariable across builds but otherwise as distinctive as possible.

        Could include information such as the relative paths used in getModuleRoots(FilePath, AbstractBuild), and/or configured repository URLs and branch names, and/or labels set for this purpose by the user.

        The result may be used for various purposes, but it may be long and/or include URL-unsafe characters, so to use in a URL path component you may need to first wrap it in Util.getDigestOf(String) or otherwise encode it.

        Returns:
        by default, just getType()
        Since:
        1.568

      • checkout

        public void checkout​(@NonNull
                     Run<?,​?> build,
                     @NonNull
                     Launcher launcher,
                     @NonNull
                     FilePath workspace,
                     @NonNull
                     TaskListener listener,
                     @CheckForNull
                     File changelogFile,
                     @CheckForNull
                     SCMRevisionState baseline)
              throws IOException,
                     InterruptedException
        Obtains a fresh workspace of the module(s) into the specified directory of the specified machine.

        The "update" operation can be performed instead of a fresh checkout if feasible.

        This operation should also capture the information necessary to tag the workspace later.

        Parameters:
        launcher - Abstracts away the machine that the files will be checked out.
        workspace - a directory to check out the source code. May contain left-over from the previous build.
        changelogFile - Upon a successful return, this file should capture the changelog. When there's no change, this file should contain an empty entry. See createEmptyChangeLog(File, TaskListener, String). May be null, in which case no changelog was requested.
        baseline - version from the previous build to use for changelog creation, if requested and available
        Throws:
        InterruptedException - interruption is usually caused by the user aborting the build. this exception will cause the build to be aborted.
        AbortException - in case of a routine failure
        IOException
        Since:
        1.568

      • buildEnvironment

        public void buildEnvironment​(@NonNull
                             Run<?,​?> build,
                             @NonNull
                             Map<String,​String> env)
        Adds environmental variables for the builds to the given map.

        This can be used to propagate information from SCM to builds (for example, SVN revision number.)

        This method is invoked whenever someone does AbstractBuild.getEnvironment(TaskListener), via buildEnvVars(AbstractBuild, Map), which can be before/after your checkout method is invoked. So if you are going to provide information about check out (like SVN revision number that was checked out), be prepared for the possibility that the check out hasn't happened yet.

        Since:
        2.60

      • getModuleRoot

        public FilePath getModuleRoot​(FilePath workspace,
                              AbstractBuild build)
        Gets the top directory of the checked out module.

        Often SCMs have to create a directory inside a workspace, which creates directory layout like this: 

        
 workspace  <- workspace root
  +- xyz    <- directory checked out by SCM
      +- CVS
      +- build.xml  <- user file

        Many builders, like Ant or Maven, works off the specific user file at the top of the checked out module (in the above case, that would be xyz/build.xml), yet the builder doesn't know the "xyz" part; that comes from SCM.

        Collaboration between Builder and SCM allows Hudson to find build.xml without asking the user to enter "xyz" again.

        This method is for this purpose. It takes the workspace root as a parameter, and expected to return the directory that was checked out from SCM.

        If this SCM is configured to create a directory, try to return that directory so that builders can work seamlessly.

        If SCM doesn't need to create any directory inside workspace, or in any other tricky cases, it should revert to the default implementation, which is to just return the parameter.

        Parameters:
        workspace - The workspace root directory.
        build - The build for which the module root is desired. This parameter is null when existing legacy code calls deprecated getModuleRoot(FilePath). Handle this situation gracefully if your can, but otherwise you can just fail with an exception, too.
        Since:
        1.382

      • getModuleRoots

        public FilePath[] getModuleRoots​(FilePath workspace,
                                 AbstractBuild build)
        Gets the top directories of all the checked out modules.

        Some SCMs support checking out multiple modules inside a workspace, which creates directory layout like this: 

        
 workspace  <- workspace root
  +- xyz    <- directory checked out by SCM
      +- .svn
      +- build.xml  <- user file
  +- abc    <- second module from different SCM root
      +- .svn
      +- build.xml  <- user file
        This method takes the workspace root as a parameter, and is expected to return all the module roots that were checked out from SCM.

        For normal SCMs, the array will be of length 1 and it's contents will be identical to calling getModuleRoot(FilePath, AbstractBuild).

        Parameters:
        workspace - The workspace root directory
        build - The build for which the module roots are desired. This parameter is null when existing legacy code calls deprecated getModuleRoot(FilePath). Handle this situation gracefully if your can, but otherwise you can just fail with an exception, too.
        Returns:
        An array of all module roots.
        Since:
        1.382

      • createChangeLogParser

        public abstract ChangeLogParser createChangeLogParser()
        The returned object will be used to parse changelog.xml.

      • getDescriptor

        public SCMDescriptor<?> getDescriptor()
        Description copied from interface: Describable
        Gets the descriptor for this instance.

        Descriptor is a singleton for every concrete Describable implementation, so if a.getClass() == b.getClass() then by default a.getDescriptor() == b.getDescriptor() as well. (In rare cases a single implementation class may be used for instances with distinct descriptors.)

        Specified by:
        getDescriptor in interface Describable<SCM>

      • guessBrowser

        @CheckForNull
public RepositoryBrowser<?> guessBrowser()
        Try to guess how a repository browser should be configured, based on URLs and the like. Used when getBrowser() has not been explicitly configured.
        Returns:
        a reasonable default value for getEffectiveBrowser(), or null
        Since:
        1.568