Interface CommitService
-
Method Summary
Modifier and TypeMethodDescriptiongetChanges
(ChangesRequest request, PageRequest pageRequest) Retrieves a page ofchanges
between two commits.getChangesets
(ChangesetsRequest request, PageRequest pageRequest) Retrieves changesets for each of the requestedChangesetsRequest.getCommitIds()
commits}, including the first page of changes between each commit and its first parent.getCommit
(CommitRequest request) Retrieves a commit based on te providedrequest
.getCommits
(CommitsRequest request, PageRequest pageRequest) Retrieves a page of commits, starting from a given branch, tag or commit, optionally filtered to only return commits which modify one or more paths.getCommitsBetween
(CommitsBetweenRequest request, PageRequest pageRequest) Retrieves a page of commits between theincluded commits
and theexcluded commits
.getCommonAncestor
(CommonAncestorRequest request) Retrieves the common ancestor for the provided commitsRetrieve the diff stats summary for the specifiedrequest
.getDiscussion
(CommitDiscussionRequest request) Retrieve acommit discussion
matching the provided request.void
streamChanges
(ChangesRequest request, ChangeCallback callback) void
streamCommits
(BulkCommitsRequest request, BulkCommitCallback callback) Stream an arbitrary set of commits from an arbitrary number of repositories.void
streamCommits
(CommitsRequest request, CommitCallback callback) Streams commits, starting from a given branch, tag or commit, optionally filtered to only include commits which modify one or more paths.void
streamCommitsBetween
(CommitsBetweenRequest request, CommitCallback callback) Streams commits between theincluded commits
and theexcluded commits
.void
streamDiff
(DiffRequest request, DiffContentCallback callback) Streams diff output for the specifiedpaths
at the specified commit.void
streamDiff
(DiffRequest request, TypeAwareOutputSupplier outputSupplier) Streams diff output for the specifiedrequest
.void
streamLastModified
(LastModifiedRequest request, LastModifiedCallback callback) void
traverse
(TraversalRequest request, TraversalCallback callback) Traverse the graph of commits in topological order, optionally supplying included commits to start from and excluded commits to ignore.
-
Method Details
-
getChanges
Retrieves a page ofchanges
between two commits. If thesince
commit is not specified, theuntil
commit's first parent is used.Note: The implementation will apply a hard cap (
page.max.changes
) and it is not possible to request subsequent content when that cap is exceeded.- Parameters:
request
- describes the two commits to retrieve changes between and the repository which contains both commitspageRequest
- the start and limit for the page being requested- Returns:
- a page of changes within the repository between the specified IDs
-
getChangesets
@Nonnull Page<Changeset> getChangesets(@Nonnull ChangesetsRequest request, @Nonnull PageRequest pageRequest) Retrieves changesets for each of the requestedChangesetsRequest.getCommitIds()
commits}, including the first page of changes between each commit and its first parent.If the
page size
is less than the size of the collection of IDs, a subset of the collection will be returned. Otherwise, changesets for all IDs in the requested collection are returned.- Parameters:
request
- request parameters, specifying the repository and the desired commitspageRequest
- the start and limit of the page being request- Returns:
- a page containing changesets for a subset of the requested IDs
- Throws:
NoSuchCommitException
- ifignoreMissing
is not set and any of the requested commits cannot be found
-
getCommit
Retrieves a commit based on te providedrequest
.If only a
commit ID
is specified, that commit will be returned if it exists. If apath
is also provided, the first commit starting from the specified commit ID which modifies that path is returned. If the specified commit does not exist, or if no commit in the ancestry of that commit modifies the specified path, aNoSuchCommitException
is thrown.When retrieving a commit,
extra properties
can also be loaded. Properties are metadata associated with commits byCommitIndexer
s. Until 4.0, the extra properties requested also control the attributes that are loaded. Attributes will be removed in 4.0.- Parameters:
request
- describes the commit to retrieve, and the repository to retrieve it from- Returns:
- the first commit matching the request within the specified repository
- Throws:
NoSuchCommitException
- if no matching commit can be found
-
getCommits
Retrieves a page of commits, starting from a given branch, tag or commit, optionally filtered to only return commits which modify one or more paths. Commits are returned starting from (and including) the specifiedCommitsRequest.getCommitId()
, unless one or morepaths
are provided. Then the first commit returned, if any are returned, will be the first commit in the ancestry of the specified starting commit which modifies at least one of the specified files.This service call may be used to:
- Retrieve pages of commits on a given branch or tag
- Retrieve pages of ancestors starting from a given commit
- Retrieve pages of commits where at least one file from a specified set of files has been modified
When retrieving commits,
extra properties
can also be loaded. Properties are metadata associated with commits byCommitIndexer
s. Until 4.0, the extra properties requested also control the attributes that are loaded. Attributes will be removed in 4.0.Note: If any of the provided paths is renamed at some point in its history, commits will not follow the path across the rename. In other words, only commits for exact paths provided will be included.
- Parameters:
request
- describes the commits to retrieve, and the repository to retrieve them frompageRequest
- the start and limit for the page being requested- Returns:
- a page of commits, which may be empty but will never be
null
-
getCommitsBetween
@Nonnull Page<Commit> getCommitsBetween(@Nonnull CommitsBetweenRequest request, @Nonnull PageRequest pageRequest) Retrieves a page of commits between theincluded commits
and theexcluded commits
. Included and excluded commits may be specified by branch or tag name or by commit ID. The commits returned are those which are reachable an included commit and not reachable from any excluded commit. While this may imply an ancestral relationship between included and excluded IDs, that is not strictly required. When the IDs are unrelated, all commits reachable from the included commits are candidates for the returned page, and excluded commits are effectively ignored. One or more paths may be provided to further narrow the results, restricting the returned commits to only which modify one or more of the specified paths.Which commits are included and which are excluded is important here. Consider the following example:
- Branch "feature-A" was created from "master" when "master" was at commit A
- Commits FA1, FA2 and FA3 were created on the "feature-A" branch
- Commits B and C were made on "master" after the branch was created
---- A ---- B ---- C \ \ FA1 ---- FA2 ---- FA3
If "master" is excluded and "feature-A" is included, commits FA1, FA2 and FA3 will be returned because they are reachable from "feature-A" but not from "master". If the two IDs were reversed, commits B and C would be returned, because they are reachable from "master" but not from "feature-A". This approach of swapping includes and excludes can be used to determine how two branches have diverged over time.When retrieving commits,
extra properties
can also be loaded. Properties are metadata associated with commits byCommitIndexer
s. Until 4.0, the extra properties requested also control the attributes that are loaded. Attributes will be removed in 4.0.Warning: Commits specified using branch or tag names will be resolved against the primary
repository
. When retrieving commits between repositories, commits in thesecondary repository
may only be specified by commit ID. This means requesting a page like this will not work:
The returned page will always be empty because "master" was resolved on both sides using the same repository, producing the same commit to include and exclude. This also demonstrates that excludes take precedence over includes, as one might expect.CommitsBetweenRequest request = new CommitsBetweenRequest.Builder(repository) .exclude("master") .include("master") .secondaryRepository(forkOfRepository) .build(); Page<Commit> page = commitService.getCommitsBetween(request, PageUtils.newRequest(0, 25));
- Parameters:
request
- describes the commits to include/exclude, paths to filter by and which repository, or repositories, contain the commitspageRequest
- the start and limit for the page being requested- Returns:
- a page containing 0 or more commits reachable from any included commit and not reachable from any excluded ones
-
getCommonAncestor
Retrieves the common ancestor for the provided commits- Parameters:
request
- request describing which common ancestor to retrieve- Returns:
- the common ancestor of the provided commits, or
Optional.empty()
if the provided commits do not have a common ancestor - Since:
- 5.0
-
getDiffStatsSummary
Retrieve the diff stats summary for the specifiedrequest
.The stats summary include the total number of modified files, added lines, and deleted lines.
- Parameters:
request
- the repository, starting and terminating commits, paths to filter by and other properties describing the diff- Returns:
- the diff stats summary for the specified request
- Since:
- 9.1
-
getDiscussion
Retrieve acommit discussion
matching the provided request.Note: Nullability actually depends on the provided request.
- Parameters:
request
- the request describing the discussion to retrieve or create- Returns:
- the retrieved discussion, which may be
null
depending on the request - Since:
- 5.0
-
streamChanges
Streams changes between theuntil
andsince
commits. If thesince
commit is not specified, theuntil
commit's first parent is used automatically.Note: The implementation will apply a hard cap (
page.max.changes
) and it is not possible to request subsequent content when that cap is exceeded.- Parameters:
request
- describes the two commits to retrieve changes between and the repository which contains both commitscallback
- a callback to receive the changes
-
streamCommits
Stream an arbitrary set of commits from an arbitrary number of repositories. The calling user is required to have access to all of therepositories
from which commits are being requested or an exception will be thrown.Due to the bulk nature of this method, it is required that full
IDs
be used to identify the commits to be streamed. Short IDs, includingdisplay IDs
, will not work. To load commits using a short ID, search first using theCommitIndex
, which does accept short IDs, and then use this method to resolve fullCommit
s for any matches the index returns.Note: Commits may not be passed to the callback in the order they are requested.
- Parameters:
request
- the request, specifying which commits to retrieve and from which repositoriescallback
- a callback to receive the commits- Since:
- 5.8
-
streamCommits
Streams commits, starting from a given branch, tag or commit, optionally filtered to only include commits which modify one or more paths. Commits are streamed starting from (and including) the specifiedCommitsRequest.getCommitId()
, unless one or morepaths
are provided. Then the first commit streamed, if any are, will be the first commit in the ancestry of the specified starting commit which modifies at least one of the specified files.This service call may be used to:
- Stream the commits on a given branch or tag
- Stream ancestors starting from a given commit
- Stream commits where at least one file from a specified set of files has been modified
When streaming commits,
extra properties
can also be loaded. Properties are metadata associated with commits byCommitIndexer
s. Until 4.0, the extra properties requested also control the attributes that are loaded. Attributes will be removed in 4.0.Note: If any of the provided paths is renamed at some point in its history, commits will not follow the path across the rename. In other words, only commits for exact paths provided will be included.
- Parameters:
request
- describes the commits to stream, and the repository to stream them fromcallback
- a callback to receive the commits
-
streamCommitsBetween
Streams commits between theincluded commits
and theexcluded commits
.This method promises to call
CommitCallback.onStart(CommitContext)
on the supplied callback exactly once, followed by zero or more calls toCommitCallback.onCommit(Commit)
, one for each commit to be streamed (untilonCommit(...)
returnsfalse
or there are no more commits), followed by exactly one call toCommitCallback.onEnd(CommitSummary)
.See
getCommitsBetween(...)
for a description of the semantics of the commits returned.- Parameters:
request
- describes the commits to include/exclude, paths to filter by and which repository, or repositories, contain the commitscallback
- a callback to receive the commits
-
streamDiff
Streams diff output for the specifiedpaths
at the specified commit.Note: This interface is currently not paged. The implementation will apply a hard cap (
page.max.diff.lines
) and it is not possible to request subsequent content when that cap is exceeded.- Parameters:
request
- the repository, starting and terminating commits, and paths to filter bycallback
- a callback to receive the diff details
-
streamDiff
Streams diff output for the specifiedrequest
.- Parameters:
request
- the repository, starting and terminating commitsoutputSupplier
- a supplier which will provide an output stream- Since:
- 6.7
-
streamLastModified
void streamLastModified(@Nonnull LastModifiedRequest request, @Nonnull LastModifiedCallback callback) Streams the last modification for files under the requestedpath
, starting from the specifiedcommit
.The
commit ID
serves as a starting point. For any files under the requested path, commits are traversed from that starting point until the most recent commit to directly modify each file is found. Because the exact number of commits which must be traversed is unknown, this operation may be very expensive.- Parameters:
request
- the repository, path and starting commitcallback
- a callback to receive last modification data- Since:
- 4.6
-
traverse
Traverse the graph of commits in topological order, optionally supplying included commits to start from and excluded commits to ignore.- Parameters:
request
- the traversal request describing the repository and the commits to include and excludecallback
- a callback to receive the traversed commits
-