public interface

ScmCommandFactory

com.atlassian.stash.scm.ScmCommandFactory

Class Overview

Creates commands which provide basic SCM functionality such as creating repositories, retrieving commits and viewing diffs. Each command accepts a set of CommandParameters which are used to control the command's behaviour and output.

In general, commands fall into two categories:

  • Paged: Accept a PageRequest describing the page of output that should be returned and return an object graph when the command is executed
  • Streamed: Accept a callback to receive output and return Void (usually null) when the command is executed
Streaming commands are generally expected to handle their own paging, though there are some exceptions.

Note: The repository against which created commands will operate was specified when the factory was retrieved from the ScmService, and cannot be changed.

Summary

Public Methods
@Nonnull Command<List<Blame>> blame(BlameCommandParameters parameters, PageRequest pageRequest)
Retrieves blame (also sometimes referred to as annotations) for a file at a given revision.
@Nonnull Command<Page<Branch>> branches(BranchesCommandParameters parameters, PageRequest pageRequest)
Retrieves a page of branches ordered either alphabetically or by modification and optionally filtered.
@Nonnull Command<Page<Change>> changes(ChangesCommandParameters parameters, PageRequest pageRequest)
Retrieves a page of changes describing the modifications made between two revisions, optionally filtered by path.
@Nonnull Command<Void> changes(ChangesCommandParameters parameters, ChangeCallback callback)
Retrieves a Command which, when executed, will stream changes describing modifications made between two revisions, optionally filtered by path.
@Nonnull Command<Changeset> commit(CommitCommandParameters parameters)
Retrieves changeset details for the specified commit.
@Nonnull Command<Void> commits(CommitsCommandParameters parameters, ChangesetCallback callback)
Retrieves all descendant commits of any of the refs (commitHash, tagname, branchname) in refs.
@Nonnull Command<Page<Changeset>> commits(CommitsCommandParameters parameters, PageRequest pageRequest)
Retrieves a page of commits matching the specified parameters.
@Nonnull Command<Void> create()
Creates and initialises the repository, performing any initial configuration that is appropriate for the SCM.
@Nonnull Command<Branch> defaultBranch()
Retrieves a Command which will resolve the default branch for the specified repository when executed.
@Deprecated @Nonnull Command<Void> deleteBranch(String branch)
This method is deprecated. in 2.1 for removal in 3.0. Deleting branches is SCM-specific.
@Nonnull Command<Page<DetailedChangeset>> detailedCommits(DetailedCommitsCommandParameters parameters, PageRequest pageRequest)
@Nonnull Command<Void> diff(DiffCommandParameters parameters, DiffContentCallback callback)
@Nonnull Command<Void> directory(DirectoryCommandParameters parameters, ContentTreeCallback callback, PageRequest pageRequest)
@Nonnull Command<Void> file(FileCommandParameters parameters, FileContentCallback callback, PageRequest pageRequest)
@Nonnull Command<Void> fork(Repository fork)
Creates a fork of repository parent
@Nonnull Command<Void> heads(RefCallback callback)
@Nonnull Command<Branch> merge(MergeCommandParameters parameters)
Creates a command that, when executed, will merge the specified fromChangesetId into the specified toBranch.
@Nonnull Command<Void> rawFile(RawFileCommandParameters parameters, TypeAwareOutputSupplier outputSupplier)
Returns a Command that will, when executed, retrieve the content of the given file, try to detect its MIME type, obtain an java.io.OutputStream OutputStream from the provided TypeAwareOutputSupplier and copy all the content into it.
@Deprecated @Nonnull Command<Void> reparent(Repository newParent)
This method is deprecated. in 2.4 for removal in 3.0, with no replacement. API consumers should have no need to ever reparent a repository, and some SCM implementations may have no need for such a function. When a repository is deleted, if reparenting is necessary, the SCM should handle it internally automatically.
@Nonnull Command<Ref> resolveRef(String refId)
@Nonnull Command<Page<Tag>> tags(TagsCommandParameters parameters, PageRequest pageRequest)
Command<Void> traverseCommits(TraversalCallback callback)
Traverse the commit graph in topological order.
@Nonnull Command<ContentTreeNode.Type> type(TypeCommandParameters parameters)
@Nonnull Command<Void> updateDefaultBranch(String branchName)
Returns a Command which, when executed, will set the default branch for the specified repository to the named branch.

Public Methods

@Nonnull public Command<List<Blame>> blame (BlameCommandParameters parameters, PageRequest pageRequest)

Retrieves blame (also sometimes referred to as annotations) for a file at a given revision.

This command is paged somewhat differently than others, in that it does not return a Page and instead returns a List. The PageRequest provided determines the lines in the file for which blame is calculated, and only lines within the scope of the page request will be returned. However, because adjacent lines may be spanned by a single author, the number of distinct Blame objects returned will frequently be less than the limit.

Parameters
parameters parameters describing the file and revision used to calculate blame
pageRequest describes the set of lines in the file to calculate blame for
Returns
  • a command which, when executed, will return the calculated Blame for the specified file and revision for the requested set of lines
See Also

@Nonnull public Command<Page<Branch>> branches (BranchesCommandParameters parameters, PageRequest pageRequest)

Retrieves a page of branches ordered either alphabetically or by modification and optionally filtered.

When no explicit order is requested, the default ordering depends on whether a filter was provided:

Modification order retrieves branches based on the date of their most recent commit.

Parameters
parameters parameters describing desired order and filter text
pageRequest describes the set of branches to return
Returns
  • a command which, when executed, will return the requested page of branches
See Also

@Nonnull public Command<Page<Change>> changes (ChangesCommandParameters parameters, PageRequest pageRequest)

Retrieves a page of changes describing the modifications made between two revisions, optionally filtered by path.

If no explicit "since" revision is specified, it defaults to the parent of the "until" revision. If the "until" revision specifies a merge commit (a commit with multiple parents), no changes will be returned.

Note: Some changes, such as copies and moves, affect more than one path. When filtering by path, if both paths are not available the change's type may not be correctly detected by some SCMs.

Parameters
parameters parameters describing the revisions to compare and paths to filter by
pageRequest describes the set of changes to return
Returns
  • a command which, when executed, will return the requested page of changes
See Also

@Nonnull public Command<Void> changes (ChangesCommandParameters parameters, ChangeCallback callback)

Retrieves a Command which, when executed, will stream changes describing modifications made between two revisions, optionally filtered by path.

If no explicit "since" revision is specified, it defaults to the parent of the "until" revision. If the "until" revision specifies a merge commit (a commit with multiple parents), no changes will be returned.

Note: Some changes, such as copies and moves, affect more than one path. When filtering by path, if both paths are not available the change's type may not be correctly detected by some SCMs.

Parameters
parameters parameters describing the revisions to compare and paths to filter by
callback the callback to receive streamed changesets
Returns
  • a command which, when executed, will stream changes
See Also

@Nonnull public Command<Changeset> commit (CommitCommandParameters parameters)

Retrieves changeset details for the specified commit.

If a path is provided, the Changeset returned may not be for the specified commit. Instead, that commit is used as a starting point and details for the first commit in its ancestry which affects that path are returned.

Parameters
parameters parameters describing the commit to retrieve details for
Returns
  • a command which, when executed, will return changeset details for the specified commit
See Also

@Nonnull public Command<Void> commits (CommitsCommandParameters parameters, ChangesetCallback callback)

Retrieves all descendant commits of any of the refs (commitHash, tagname, branchname) in refs.

Parameters
parameters previous heads
callback the changeset callback that will be called for each of the matching commits.
Returns
  • a command to asynchronously retrieve the commits.

@Nonnull public Command<Page<Changeset>> commits (CommitsCommandParameters parameters, PageRequest pageRequest)

Retrieves a page of commits matching the specified parameters.

Parameters
parameters parameters describing which commits to retrive details for.
pageRequest describes the set of commits to return
Returns
  • a command to asynchronously retrieve the commits.

@Nonnull public Command<Void> create ()

Creates and initialises the repository, performing any initial configuration that is appropriate for the SCM.

Note: This command may be called exactly once for any repository. Subsequent executions will fail; they will not reinitialise the repository.

Returns
  • a command which, when executed, will create the repository and configure it

@Nonnull public Command<Branch> defaultBranch ()

Retrieves a Command which will resolve the default branch for the specified repository when executed.

The returned command may throw NoDefaultBranchException, when executed, if the specified repository does not have a resolvable default branch. This might happen, for example, on a new repository with no commits, or if the only commits to a repository have been to a branch other than the default branch.

Returns
  • a command which, when executed, will retrieve the default branch
Throws
NoDefaultBranchException if the repository does not have a resolvable default branch

@Deprecated @Nonnull public Command<Void> deleteBranch (String branch)

This method is deprecated.
in 2.1 for removal in 3.0. Deleting branches is SCM-specific.

Returns a Command which, when executed, will delete the specified branch.

Parameters
branch to be deleted
Returns
  • a command which, when executed, will delete the specified branch

@Nonnull public Command<Page<DetailedChangeset>> detailedCommits (DetailedCommitsCommandParameters parameters, PageRequest pageRequest)

@Nonnull public Command<Void> diff (DiffCommandParameters parameters, DiffContentCallback callback)

@Nonnull public Command<Void> directory (DirectoryCommandParameters parameters, ContentTreeCallback callback, PageRequest pageRequest)

@Nonnull public Command<Void> file (FileCommandParameters parameters, FileContentCallback callback, PageRequest pageRequest)

@Nonnull public Command<Void> fork (Repository fork)

Creates a fork of repository parent

Parameters
fork the fork

@Nonnull public Command<Void> heads (RefCallback callback)

@Nonnull public Command<Branch> merge (MergeCommandParameters parameters)

Creates a command that, when executed, will merge the specified fromChangesetId into the specified toBranch.

The provided fromChangesetId may be:

  • A 40-byte hash (Note: Short hashes are not supported)
  • A fully-qualified branch name
  • A short branch name
The provided toBranch, as the parameter name suggests, must be a branch name, either fully qualified or short; using a hash (full or short) is not supported.

Returns
  • a command to merge the specified branch into the target branch

@Nonnull public Command<Void> rawFile (RawFileCommandParameters parameters, TypeAwareOutputSupplier outputSupplier)

Returns a Command that will, when executed, retrieve the content of the given file, try to detect its MIME type, obtain an java.io.OutputStream OutputStream from the provided TypeAwareOutputSupplier and copy all the content into it.

Parameters
parameters parameters used to specify the path and version of the file to stream
outputSupplier the supplier which, when given a content type, will provide an output stream
Returns
  • a command which, when executed, will determine the file's type and then stream its data

@Deprecated @Nonnull public Command<Void> reparent (Repository newParent)

This method is deprecated.
in 2.4 for removal in 3.0, with no replacement. API consumers should have no need to ever reparent a repository, and some SCM implementations may have no need for such a function. When a repository is deleted, if reparenting is necessary, the SCM should handle it internally automatically.

Returns a Command that will, when executed, update the origin for the repository to reference the newParent.

Parameters
newParent the new parent which should be used as the repository's origin
Returns
  • a command which, when executed, will reparent the repository

@Nonnull public Command<Ref> resolveRef (String refId)

@Nonnull public Command<Page<Tag>> tags (TagsCommandParameters parameters, PageRequest pageRequest)

public Command<Void> traverseCommits (TraversalCallback callback)

Traverse the commit graph in topological order.

Parameters
callback the callback for traversing the commit graph
Returns
  • the command that will execute the traversal

@Nonnull public Command<ContentTreeNode.Type> type (TypeCommandParameters parameters)

@Nonnull public Command<Void> updateDefaultBranch (String branchName)

Returns a Command which, when executed, will set the default branch for the specified repository to the named branch. This operation may not be supported by all SCM implementations. Such implementations should throw an UnsupportedOperationException.

Parameters
branchName the branch to make the default
Returns
  • a command which will update the default branch
Throws
IllegalArgumentException Thrown if the provided branchName is null or blank.
UnsupportedOperationException Thrown if the underlying SCM does not support setting the default branch.