PluginCommandFactory

Retrieves a page of Blame, providing attribution for each line in the specified file, calculated from the specified starting commit.

Retrieves a page of branches.

Streams branches in the specified repository to the provided BranchCallback callback.

Retrieves a page of changes between two commits.

If the ChangesCommandParameters#getSinceId() sinceId is not specified, the first ancestor of the ChangesCommandParameters#getUntilId() untilId must be used automatically. If the until commit is the first commit in the repository, and has no ancestors, each file included in that commit should be returned as newly added.

Streams changes between two commits to the provided ChangeCallback callback.

If the ChangesCommandParameters#getSinceId() sinceId is not specified, the first ancestor of the ChangesCommandParameters#getUntilId() untilId must be used automatically. If the until commit is the first commit in the repository, and has no ancestors, each file included in that commit should be streamed as newly added.

Retrieves a page of changesets given a set of ChangesetsCommandParameters#getCommitIds commit IDs, where each changeset includes the first page of changes between a requested commit and its first parent.

Retrieves the requested commit or, if a path was also supplied, retrieves the first commit to modify that path prior to the requested commit. If the requested commit modified the path, it will be returned.

Streams commits which match the provided CommitsCommandParameters paramters to the provided callback.

Implementors: SCMs are required to support this operation. However, they are not required to support CommitsCommandParameters#getSecondaryRepository() secondary repositories unless they offer ScmFeature#CROSS_REPOSITORY cross-repository support. If a secondary repository is provided and cross- repository operations are not supported, implementations should throw an UnsupportedOperationException.

Retrieves a page of commits which match the provided CommitsCommandParameters paramters.

Implementors: SCMs are required to support this operation. However, they are not required to support CommitsCommandParameters#getSecondaryRepository() secondary repositories unless they offer ScmFeature#CROSS_REPOSITORY cross-repository support. If a secondary repository is provided and cross- repository operations are not supported, implementations should throw an UnsupportedOperationException.

Retrieves the common ancestor for the provided commits

Creates and initializes the repository on disk, performing any SCM-specific configuration that is appropriate for new repositories. repository does not exist on disk when this method is called. The SCM is expected to create it with contents that are appropriate for an empty, new repository.

Retrieves the default Branch for the specified repository.

Each repository in an SCM is required to have a default branch. However, that branch is not actually required to exist within the repository. If the default branch does not exist, the returned command must throw NoDefaultBranchException; it may not return null.

Deletes the repository, allowing the underlying SCM to carry out any special processing necessary to clean up repository storage.

Note: By the time this method is called, the repository has already been deleted from the database, and the associated database transaction has been committed.

Warning: This method is irreversible. It should never be called by a plugin. It is intended solely for use by the system.

Streams the diff between two commits to the provided DiffContentCallback callback.

If the DiffCommandParameters#getSinceId() sinceId is not specified, the diff must be calculated to the first ancestor of the DiffCommandParameters#getUntilId() untilId. If the until commit is the first commit in the repository, and has no ancestors, content for each file included in that commit should be streamed as newly added.

Diff implementations are required to honor the following settings:

• DiffCommandParameters#getContextLines() context line count
• DiffCommandParameters#getMaxLineLength() line length
• DiffCommandParameters#getMaxLines() line count

Streams a directory listing for the requested path at the specified commit.

When a DirectoryCommandParameters#isRecursive() recursive listing is requested, implementations must only stream non-directory entries. If the SCM tracks empty directories, they must be omitted.

For non-recursive listings, implementations are encouraged to collapse subdirectories which only have a single entry. For example, consider the following directory structure:

 src/
   main/
     java/
       com/
         example/
           MyClass.java
     resources/
 pom.xml
 

• new SimplePath("src"), or
• new SimplePath("src/main"

A listing at "src/main", in addition to streaming new SimplePath("resources") may stream either of the following values:

• new SimplePath("java"), or
• new SimplePath("java/com/example/MyClass.java")

If DirectoryCommandParameters#isWithSizes() file sizes are requested, SCMs which can efficiently include them should do so. If the SCM's internal representation for directory data makes file sizes expensive to retrieve (such as requiring the entire file to be streamed and its bytes counted, in the worst case), the SCM should omit size data even if it is requested.

Streams lines from the requested path at the specified commit, for non-binary files.

When the command is executed, if the requested path identifies a binary file, such as an image or PDF, the SCM should call onBinary().

For SCMs which support multiple file encodings:

• If the encoding is recorded in the SCM's metadata, it should be used
• Otherwise, the SCM should perform its own best-effort encoding detection

 <dependency>
     <groupId>com.atlassian.bitbucket.server</groupId>
     <artifactId>bitbucket-scm-common</artifactId>
     <scope>provided</scope>
 </dependency>
 

Implementations are required to honor FileCommandParameters#getMaxLineLength() max line lengths. If any line in a file exceeds that length, it must be truncated to constrain memory usage.

If FileCommandParameters#isAnnotated() annotations are requested, the implementation must compute the blame(Repository, BlameCommandParameters, PageRequest) for each line on the requested page and, after streaming those lines, offer the blame to the callback.

Streams all of the heads in the specified repository.

Implementors: A "head" in this context is any type of ref that would normally be retrieved by the SCM. At a minimum, this should be every branch and every tag in the repository. If the SCM has additional standard refs, they should be included. If the SCM supports optional or nonstandard ref namespaces, any refs stored there should not be included.

Streams the raw bytes for the requested file at the specified commit to OutputStream returned by the provided TypeAwareOutputSupplier supplier.

Prior to streaming bytes, SCM implementations are required to perform best-effort MIME type detection on the file, and to pass the detected type to the supplier. The Java java.net.URLConnection URLConnection class offers some static methods to facilitate such detection. ContentDetectionUtils.detectContentType(BufferedInputStream, String) may also be useful. It may be accessed from the following Maven dependency:

 <dependency>
     <groupId>com.atlassian.bitbucket.server</groupId>
     <artifactId>bitbucket-scm-common</artifactId>
     <scope>provided</scope>
 </dependency>
 

Resolves the specified ResolveRefCommandParameters#getRefId() refId, which may be a:

• branch name
• tag name
• commit hash

If a hash is provided, it may only be resolved to a branch or tag if it identifies the tip commit. If the hash identifies a commit that is not the tip of a branch or tag, the returned command must return null.

When a hash or name is provided and resolves to multiple branches, tags or a combination of both, SCM implementors are encouraged to choose a tag over a branch, and to return the "first" branch or tag alphabetically. However, this is not enforced and is not considered part of the contract.

If the parameters specify a ResolveRefCommandParameters#getType() ref type, the provided ID must only be resolved against refs of that type. If a ref of a different type matches, it may not be returned. Implementations are encouraged to optimize their lookups when a type is provided.

Resolves one or more branches, tags and/or refs.

Implementations may only resolve ResolveRefsCommandParameters#getBranchIds() branch IDs and ResolveRefsCommandParameters#getTagIds() tag IDs against branches and Tag tags, respectively. If a ref a different type matches, it may not be returned.

ResolveRefsCommandParameters#getRefIds Ref IDs may be resolved against refs of any type. When an ID resolves to multiple branches, tags or a combination of both, SCM implementors are encouraged to choose a tag over a branch, and to return the "first" branch or tag alphabetically. However, this is not enforced, and is not considered part of the contract.

Streams Tag tags in the specified repository to the provided TagCallback callback.

Retrieves a page of tags.

Streams all of the commits in the repository reachable from any branch or tag in topological order. Topological order means no parent is output before all of its descendants have been output. It does not require that descendants be streamed in date order, but SCMs may optionally do so (so long as topological order is retained).

Retrieves the type for the requested path at the specified commit. The same path may have different types at different commits as the repository's contents change.

The command may not return null for any reason. If the specified commit does not exist in the repository, the returned command must throw NoSuchCommitException. If the requested path does not exist in the specified commit, the returned command must throw NoSuchPathException.