@ExportedBean public abstract class SCM extends Object implements Describable<SCM>, ExtensionPoint
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.
ExtensionPoint.LegacyInstancesAreScopedToHudson
Modifier and Type | Field and Description |
---|---|
static PermissionGroup |
PERMISSIONS |
static Permission |
TAG
Permission to create new tags.
|
Constructor and Description |
---|
SCM() |
Modifier and Type | Method and Description |
---|---|
SCMRevisionState |
_calcRevisionsFromBuild(AbstractBuild<?,?> build,
Launcher launcher,
TaskListener listener)
Deprecated.
|
static List<SCMDescriptor<?>> |
_for(AbstractProject project)
Deprecated.
|
static List<SCMDescriptor<?>> |
_for(Job project)
Determines which kinds of SCMs are applicable to a given project.
|
static DescriptorExtensionList<SCM,SCMDescriptor<?>> |
all()
Returns all the registered
SCMDescriptor s. |
void |
buildEnvironment(Run<?,?> build,
Map<String,String> env)
Adds environmental variables for the builds to the given map.
|
void |
buildEnvVars(AbstractBuild<?,?> build,
Map<String,String> env)
Deprecated.
in favor of
buildEnvironment(Run, Map) . |
SCMRevisionState |
calcRevisionsFromBuild(AbstractBuild<?,?> build,
Launcher launcher,
TaskListener listener)
Deprecated.
|
SCMRevisionState |
calcRevisionsFromBuild(Run<?,?> build,
FilePath workspace,
Launcher launcher,
TaskListener listener)
Calculates the
SCMRevisionState that represents the state of the workspace of the given build. |
boolean |
checkout(AbstractBuild<?,?> build,
Launcher launcher,
FilePath workspace,
BuildListener listener,
File changelogFile)
Deprecated.
|
void |
checkout(Run<?,?> build,
Launcher launcher,
FilePath workspace,
TaskListener listener,
File changelogFile,
SCMRevisionState baseline)
Obtains a fresh workspace of the module(s) into the specified directory
of the specified machine.
|
protected PollingResult |
compareRemoteRevisionWith(AbstractProject<?,?> project,
Launcher launcher,
FilePath workspace,
TaskListener listener,
SCMRevisionState baseline)
Deprecated.
|
PollingResult |
compareRemoteRevisionWith(Job<?,?> project,
Launcher launcher,
FilePath workspace,
TaskListener listener,
SCMRevisionState baseline)
Compares the current state of the remote repository against the given baseline
SCMRevisionState . |
abstract ChangeLogParser |
createChangeLogParser()
The returned object will be used to parse
changelog.xml . |
protected boolean |
createEmptyChangeLog(File changelogFile,
BuildListener listener,
String rootTag)
Deprecated.
|
protected void |
createEmptyChangeLog(File changelogFile,
TaskListener listener,
String rootTag) |
Api |
getApi()
Expose
SCM to the remote API. |
RepositoryBrowser<?> |
getBrowser()
Returns the
RepositoryBrowser for files
controlled by this SCM . |
SCMDescriptor<?> |
getDescriptor()
Gets the descriptor for this instance.
|
RepositoryBrowser<?> |
getEffectiveBrowser()
Returns the applicable
RepositoryBrowser for files
controlled by this SCM . |
String |
getKey()
Should create a key by which this SCM configuration might be distinguished from others in the same project.
|
FilePath |
getModuleRoot(FilePath workspace)
Deprecated.
since 1.382
Use/override
getModuleRoot(FilePath, AbstractBuild) instead. |
FilePath |
getModuleRoot(FilePath workspace,
AbstractBuild build)
Gets the top directory of the checked out module.
|
FilePath[] |
getModuleRoots(FilePath workspace)
Deprecated.
as of 1.382.
Use/derive from
getModuleRoots(FilePath, AbstractBuild) instead. |
FilePath[] |
getModuleRoots(FilePath workspace,
AbstractBuild build)
Gets the top directories of all the checked out modules.
|
String |
getType()
Type of this SCM.
|
RepositoryBrowser<?> |
guessBrowser()
Try to guess how a repository browser should be configured, based on URLs and the like.
|
protected String |
nullify(String s) |
PollingResult |
poll(AbstractProject<?,?> project,
Launcher launcher,
FilePath workspace,
TaskListener listener,
SCMRevisionState baseline)
Convenience method for the caller to handle the backward compatibility between pre 1.345 SCMs.
|
boolean |
pollChanges(AbstractProject<?,?> project,
Launcher launcher,
FilePath workspace,
TaskListener listener)
Deprecated.
as of 1.345
Override
calcRevisionsFromBuild(AbstractBuild, Launcher, TaskListener) and
compareRemoteRevisionWith(AbstractProject, Launcher, FilePath, TaskListener, SCMRevisionState) for implementation.
The implementation is now separated in two pieces, one that computes the revision of the current workspace,
and the other that computes the revision of the remote repository.
Call poll(AbstractProject, Launcher, FilePath, TaskListener, SCMRevisionState) for use instead. |
void |
postCheckout(AbstractBuild<?,?> build,
Launcher launcher,
FilePath workspace,
BuildListener listener)
Deprecated.
|
void |
postCheckout(Run<?,?> build,
Launcher launcher,
FilePath workspace,
TaskListener listener)
Get a chance to do operations after the workspace i checked out and the changelog is written.
|
boolean |
processWorkspaceBeforeDeletion(AbstractProject<?,?> project,
FilePath workspace,
Node node)
Deprecated.
|
boolean |
processWorkspaceBeforeDeletion(Job<?,?> project,
FilePath workspace,
Node node)
Called before a workspace is deleted on the given node, to provide SCM an opportunity to perform clean up.
|
boolean |
requiresWorkspaceForPolling()
Returns true if this SCM requires a checked out workspace for doing polling.
|
boolean |
supportsPolling()
Returns true if this SCM supports
poling . |
public static final PermissionGroup PERMISSIONS
public static final Permission TAG
@CheckForNull public RepositoryBrowser<?> getBrowser()
RepositoryBrowser
for files
controlled by this SCM
.getEffectiveBrowser()
@Exported public String getType()
@Exported(name="browser") @CheckForNull public final RepositoryBrowser<?> getEffectiveBrowser()
RepositoryBrowser
for files
controlled by this SCM
.guessBrowser()
public boolean supportsPolling()
poling
.public boolean requiresWorkspaceForPolling()
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.
public boolean processWorkspaceBeforeDeletion(@NonNull Job<?,?> project, @NonNull FilePath workspace, @NonNull Node node) throws IOException, InterruptedException
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.
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.SCM
is OK to let Hudson proceed with deleting the workspace.
False to veto the workspace deletion.IOException
InterruptedException
@Deprecated public boolean processWorkspaceBeforeDeletion(AbstractProject<?,?> project, FilePath workspace, Node node) throws IOException, InterruptedException
IOException
InterruptedException
@Deprecated public boolean pollChanges(AbstractProject<?,?> project, Launcher launcher, FilePath workspace, TaskListener listener) throws IOException, InterruptedException
calcRevisionsFromBuild(AbstractBuild, Launcher, TaskListener)
and
compareRemoteRevisionWith(AbstractProject, Launcher, FilePath, TaskListener, SCMRevisionState)
for implementation.
The implementation is now separated in two pieces, one that computes the revision of the current workspace,
and the other that computes the revision of the remote repository.
Call poll(AbstractProject, Launcher, FilePath, TaskListener, SCMRevisionState)
for use instead.
If the SCM doesn't implement polling, have the supportsPolling()
method
return false.
project
- The project to check for updateslauncher
- Abstraction of the machine where the polling will take place. If SCM declares
that the polling doesn't require a workspace, this parameter is null.workspace
- The workspace directory that contains baseline files. If SCM declares
that the polling doesn't require a workspace, this parameter is null.listener
- Logs during the polling should be sent here.InterruptedException
- interruption is usually caused by the user aborting the computation.
this exception should be simply propagated all the way up.IOException
supportsPolling()
@CheckForNull public SCMRevisionState calcRevisionsFromBuild(@NonNull Run<?,?> build, @Nullable FilePath workspace, @Nullable Launcher launcher, @NonNull TaskListener listener) throws IOException, InterruptedException
SCMRevisionState
that represents the state of the workspace of the given build.
The returned object is then fed into the
compareRemoteRevisionWith(AbstractProject, Launcher, FilePath, TaskListener, SCMRevisionState)
method
as the baseline SCMRevisionState
to determine if the build is necessary.
This method is called after source code is checked out for the given build (that is, after
checkout(Run, Launcher, FilePath, TaskListener, File, SCMRevisionState)
has finished successfully.)
The obtained object is added to the build as an Action
for later retrieval. As an optimization,
SCM
implementation can choose to compute SCMRevisionState
and add it as an action
during check out, in which case this method will not called.
build
- The calculated SCMRevisionState
is for the files checked out in this build.
If requiresWorkspaceForPolling()
returns true, Hudson makes sure that the workspace of this
build is available and accessible by the callee.workspace
- the location of the checkout; normally not null, since this will normally be called immediately after checkout,
though could be null if data is being loaded from a very old version of Jenkins and the SCM declares that it does not require a workspace for pollinglauncher
- Abstraction of the machine where the polling will take place. Nullness matches that of workspace
.listener
- Logs during the polling should be sent here.InterruptedException
- interruption is usually caused by the user aborting the computation.
this exception should be simply propagated all the way up.IOException
@Deprecated public SCMRevisionState calcRevisionsFromBuild(AbstractBuild<?,?> build, Launcher launcher, TaskListener listener) throws IOException, InterruptedException
IOException
InterruptedException
@Deprecated public SCMRevisionState _calcRevisionsFromBuild(AbstractBuild<?,?> build, Launcher launcher, TaskListener listener) throws IOException, InterruptedException
IOException
InterruptedException
public PollingResult compareRemoteRevisionWith(@NonNull Job<?,?> project, @Nullable Launcher launcher, @Nullable FilePath workspace, @NonNull TaskListener listener, @NonNull SCMRevisionState baseline) throws IOException, InterruptedException
SCMRevisionState
.
Conceptually, the act of polling is to take two states of the repository and to compare them to see if there's any difference. In practice, however, comparing two arbitrary repository states is an expensive operation, so in this abstraction, we chose to mix (1) the act of building up a repository state and (2) the act of comparing it with the earlier state, so that SCM implementations can implement this more easily.
Multiple invocations of this method may happen over time to make sure that the remote repository is "quiet" before Hudson schedules a new build.
project
- The project to check for updateslauncher
- Abstraction of the machine where the polling will take place. If SCM declares
that the polling doesn't require a workspace, this parameter is null.workspace
- The workspace directory that contains baseline files. If SCM declares
that the polling doesn't require a workspace, this parameter is null.listener
- Logs during the polling should be sent here.baseline
- The baseline of the comparison. This object is the return value from earlier
compareRemoteRevisionWith(AbstractProject, Launcher, FilePath, TaskListener, SCMRevisionState)
or
calcRevisionsFromBuild(AbstractBuild, Launcher, TaskListener)
.PollingResult
value type.
PollingResult.baseline
should be the value of the baseline parameter, PollingResult.remote
is the current state of the remote repository (this object only needs to be understandable to the future
invocations of this method),
and PollingResult.change
that indicates the degree of changes found during the comparison.InterruptedException
- interruption is usually caused by the user aborting the computation.
this exception should be simply propagated all the way up.IOException
@Deprecated protected PollingResult compareRemoteRevisionWith(AbstractProject<?,?> project, Launcher launcher, FilePath workspace, TaskListener listener, SCMRevisionState baseline) throws IOException, InterruptedException
IOException
InterruptedException
public final PollingResult poll(AbstractProject<?,?> project, Launcher launcher, FilePath workspace, TaskListener listener, SCMRevisionState baseline) throws IOException, InterruptedException
IOException
InterruptedException
@NonNull public String getKey()
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.
getType()
public void checkout(@NonNull Run<?,?> build, @NonNull Launcher launcher, @NonNull FilePath workspace, @NonNull TaskListener listener, @CheckForNull File changelogFile, @CheckForNull SCMRevisionState baseline) throws IOException, InterruptedException
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.
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 availableInterruptedException
- 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 failureIOException
@Deprecated public boolean checkout(AbstractBuild<?,?> build, Launcher launcher, FilePath workspace, BuildListener listener, @NonNull File changelogFile) throws IOException, InterruptedException
IOException
InterruptedException
public void postCheckout(@NonNull Run<?,?> build, @NonNull Launcher launcher, @NonNull FilePath workspace, @NonNull TaskListener listener) throws IOException, InterruptedException
IOException
InterruptedException
@Deprecated public void postCheckout(AbstractBuild<?,?> build, Launcher launcher, FilePath workspace, BuildListener listener) throws IOException, InterruptedException
IOException
InterruptedException
public void buildEnvironment(@NonNull Run<?,?> build, @NonNull Map<String,String> env)
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.
@Deprecated public void buildEnvVars(AbstractBuild<?,?> build, Map<String,String> env)
buildEnvironment(Run, Map)
.public FilePath getModuleRoot(FilePath workspace, AbstractBuild build)
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.
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.@Deprecated public FilePath getModuleRoot(FilePath workspace)
getModuleRoot(FilePath, AbstractBuild)
instead.public FilePath[] getModuleRoots(FilePath workspace, AbstractBuild build)
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)
.
workspace
- The workspace root directorybuild
- 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.@Deprecated public FilePath[] getModuleRoots(FilePath workspace)
getModuleRoots(FilePath, AbstractBuild)
instead.public abstract ChangeLogParser createChangeLogParser()
changelog.xml
.public SCMDescriptor<?> getDescriptor()
Describable
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.)
getDescriptor
in interface Describable<SCM>
@Deprecated protected final boolean createEmptyChangeLog(File changelogFile, BuildListener listener, String rootTag)
protected final void createEmptyChangeLog(@NonNull File changelogFile, @NonNull TaskListener listener, @NonNull String rootTag) throws IOException
IOException
public static DescriptorExtensionList<SCM,SCMDescriptor<?>> all()
SCMDescriptor
s.public static List<SCMDescriptor<?>> _for(@CheckForNull Job project)
project
- a project on which we might be configuring SCM, or null if unknownSCMDescriptor.isApplicable(Job)
to it, also filtered by TopLevelItemDescriptor.isApplicable(hudson.model.Descriptor)
;
or simply all()
if there is no project@Deprecated public static List<SCMDescriptor<?>> _for(AbstractProject project)
@CheckForNull public RepositoryBrowser<?> guessBrowser()
getBrowser()
has not been explicitly configured.getEffectiveBrowser()
, or nullCopyright © 2004–2022. All rights reserved.