ChangesetsBetweenRequest

This class is deprecated.
in 3.7 for removal in 5.0. All things "changeset" are being renamed to "commit", the more common term for the data they represent. Due to the significant number of touchpoints, the deprecated classes and interfaces will be left in for an entire major release cycle, rather than being removed in 4.0. CommitsBetweenRequest replaces this request.

Class Overview

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

The easiest way to understand changesets "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 changesets "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 changesets have been added when a pull request is rescoped, excluding the previous from ref and the current to ref yields the just the added changesets
• Include "FB1" and "C", exclude "feature-B": No changesets
  • This is the logical negation of the previous example. When a pull request is rebased, this could be used to determine which changesets were removed from the pull request by showing changesets that used to be reachable from "FB1" but are no longer reachable from "FB3" or "C"

The first two examples demonstrate how the selected changesets vary, given the same set of possible changesets, depending on which commits are included and excluded. As might be expected, excluding changeset 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 changesets between two repositories. When a secondary repository is specified its commits will be made available in the primary repository, which allows retrieving the changesets that have been added on a branch in a fork, for example, when opening a pull request back to its origin.

Warning: Retrieving changesets between repositories may be expensive. Additionally, when referring to changesets 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 directly.

Summary

Nested Classes
class	ChangesetsBetweenRequest.Builder

Public Methods
@Nonnull Set<String>	getExcludes() Retrieves changesets, which may be identified by branch or tag name or by hash, which should be excluded from the results.
@Nonnull Set<String>	getIncludes() Retrieves changesets, which may be identified by branch or tag name or by hash, which should be included in the results.
@Nonnull Set<String>	getLoadAttributes() Retrieves the names of index attributes to load, when loading pages of changesets.
@Nonnull Set<String>	getPaths() Retrieves paths, which may identify directories or files within the repository, which are used to limit returned changesets.
@Nonnull Repository	getRepository() Retrieves the primary repository.
@Nullable Repository	getSecondaryRepository() When retrieving changesets between repositories, retrieves the secondary repository.

[Expand] Inherited Methods
From class java.lang.Object Object clone() boolean equals(Object arg0) void finalize() final Class<?> getClass() int hashCode() final void notify() final void notifyAll() String toString() final void wait() final void wait(long arg0, int arg1) final void wait(long arg0)