com.atlassian.bitbucket.commit

Class CommitsBetweenRequest

java.lang.Object

com.atlassian.bitbucket.commit.AbstractCommitsRequest

com.atlassian.bitbucket.commit.CommitsBetweenRequest

public class CommitsBetweenRequest
extends AbstractCommitsRequest

Defines a request to retrieve commits "between" sets of included and excluded commits, potentially filtering by paths.

The easiest way to understand commits "between" is with an illustration:

 "feature-B"               FB1 -- FB2 -- FB3
                           /      /
                          /      /
 "master"    ---- A ---- B ---- C
                   \
                    \
 "feature-A"        FA1 -- FA2 -- FA3
 

Given the graph above, here are some examples of the commits "between" various points:

• Include "FA3", exclude "C": "FA1", "FA2", "FA3"
  • "FA3" also references "A", but, since "A" is reachable from "C", it is excluded from the results
  • This might be used to list the commits that have been added on a feature branch and not yet merged
• Include "master", exclude "feature-A": "B", "C"
  • "feature-A" is resolved to "FA-3", excluding "FA2", "FA1" and "A", while "master" is resolved to "C" and includes "B"
  • This might be used to list commits added on an upstream branch after a feature branch was created which have not yet been merged into the feature branch
• Include "feature-B", exclude "FB1" and "C": "FB2", "FB3"
  • "feature-B" is resolved to "FB3", which includes "FB2" and "FB1" as well as "A", "B" and "C" from "master". Excluding "C" drops "A" and "B" as well
  • This might be used, for example, to determine which commits have been added when a pull request is rescoped, excluding the previous from ref and the current to ref yields the just the added commits
• Include "FB1" and "C", exclude "feature-B": No commits
  • This is the logical negation of the previous example. When a pull request is rebased, this could be used to determine which commits were removed from the pull request by showing commits that used to be reachable from "FB1" but are no longer reachable from "FB3" or "C"

The first two examples demonstrate how the selected commits vary, given the same set of possible commits, depending on which commits are included and excluded. As might be expected, excluding a commit takes precedence over including it. The second two examples show how using multiple includes and excludes can be used to determine how a pull request has been changed by a rescope event.

Also useful when dealing with pull requests is the ability to determine the commits between two repositories. When a secondary repository is specified its commits will be made available in the primary repository, which allows retrieving the commits that have been added on a branch in a fork, for example, when opening a pull request back to its origin. When a secondary repository is specified, it must be from the same hierarchy as the primary repository or an exception will be thrown while building the request.

Warning: Retrieving commits between repositories may be expensive. Additionally, when referring to commits in the secondary repository, includes and excludes must be specified by hash. Branch and tag names are always resolved using the primary repository, which may lead to unexpected results.

Note: Once built, a request is immutable. None of the returned collections may be modified.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CommitsBetweenRequest.Builder

Nested classes/interfaces inherited from class com.atlassian.bitbucket.commit.AbstractCommitsRequest

AbstractCommitsRequest.AbstractCommitsRequestBuilder<B extends AbstractCommitsRequest.AbstractCommitsRequestBuilder<B>>

Field Summary

Fields inherited from class com.atlassian.bitbucket.commit.AbstractCommitsRequest

UNLIMITED_MESSAGE_LENGTH

Method Summary

Modifier and Type	Method and Description
Set<String>	getExcludes() Retrieves commits, which may be identified by branch or tag name or by hash, which should be excluded from the results.
Set<String>	getIncludes() Retrieves commits, which may be identified by branch or tag name or by hash, which should be included in the results.
Repository	getSecondaryRepository() When retrieving commits between repositories, retrieves the secondary repository.

Methods inherited from class com.atlassian.bitbucket.commit.AbstractCommitsRequest

getMaxMessageLength, getMerges, getOrder, getPaths, getPropertyKeys, getRepository, isFollowingRenames, isIgnoringMissing

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getExcludes

@Nonnull
public Set<String> getExcludes()

Retrieves commits, which may be identified by branch or tag name or by hash, which should be excluded from the results.

Note: Branch and tag names are always resolved against the primary repository.

Returns:

a set containing zero or more commits to exclude

getIncludes

@Nonnull
public Set<String> getIncludes()

Retrieves commits, which may be identified by branch or tag name or by hash, which should be included in the results. When a commit is both included and excluded, it is excluded.

Note: Branch and tag names are always resolved against the primary repository.

Returns:

a set containing one or more commits to include

getSecondaryRepository

@Nullable
public Repository getSecondaryRepository()

When retrieving commits between repositories, retrieves the secondary repository. Commits in this repository may only be identified by hash. Any branch or tag names used will always be resolved using the primary repository.

Returns:

a secondary repository whose commits should be considered