Package com.atlassian.bitbucket.scm.git

Enum Class GitRefPattern

java.lang.Object
java.lang.Enum<GitRefPattern>
com.atlassian.bitbucket.scm.git.GitRefPattern
All Implemented Interfaces:
Serializable, Comparable<GitRefPattern>, Constable
public enum GitRefPattern extends Enum<GitRefPattern>
Enumeration of standard git ref patterns, with additional logic to help apply standard git precedence and to produce both qualified and unqualified refs for given input.

  • Enum Constant Details

    • HEADS

      public static final GitRefPattern HEADS
      Ref pattern denoting local branches.

    • PULL_REQUESTS

      public static final GitRefPattern PULL_REQUESTS
      Ref pattern denoting open pull requests.

    • REMOTES

      public static final GitRefPattern REMOTES
      Ref pattern denoting remote branches (agnostic of remote name).

    • TAGS

      public static final GitRefPattern TAGS
      Ref pattern denoting tags.

  • Method Details

    • values

      public static GitRefPattern[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static GitRefPattern valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null

    • getComponents

      @Nonnull public String[] getComponents()
      Retrieves the components that make up this pattern's path.
      Returns:
      the path components for this pattern

    • getPath

      @Nonnull public String getPath()
      Retrieves the path under the .git directory containing all refs for this pattern.

      Note: Paths returned from this method will always end with a trailing /.

      Returns:
      the ref path for this pattern

    • getRefspec

      @Nonnull public String getRefspec()
      Retrieves a non-force refspec for this pattern. The refspec is structured so that all refs that match this pattern on the remote will update refs of the same pattern locally. For example, for HEADS, the refspec will be refs/heads/*:refs/heads/*.
      Returns:
      a refspec for refs matching this pattern

    • getRefspec

      @Nonnull public String getRefspec(boolean force)
      Retrieves a refspec for this pattern. optionally including a leading + to allow forced updates. The refspec is structured so that all refs that match this pattern on the remote will update refs of the same pattern locally. For example, for HEADS, the refspec will be +refs/heads/*:refs/heads/* if force is true, and refs/heads/*:refs/heads/* otherwise.
      Parameters:
      force - true for a forced update
      Returns:
      a refspec for refs matching this pattern, optionally allowing forced updates

    • getSearchOrder

      @Nonnull public List<String> getSearchOrder(@Nonnull String ref)
      Applies the git precedence ordering for the provided ref, constrained by this pattern, to produce an ordered list of search candidates. That means that where the git precedence would search across branches and tags and remotes, the returned list only searches within a given type, such as tags, but it contains paths under the .git directory in the same order git would search them.
      Parameters:
      ref - the ref for which to build a search order
      Returns:
      a list of possible locations for matching the provided ref, in order of their precedence in git
      Throws:
      IllegalArgumentException - if the provided ref is empty or blank
      NullPointerException - if the provided ref is null

    • qualify

      @Nonnull public String qualify(@Nonnull String ref)
      Qualifies the provided ref according this pattern. The returned value is suitable for use as a ref's ID.

      Note: The implementation of this method attempts to detect when a fully- or partially-qualified ref is passed and further qualify the ref as appropriate. However, this may result in incorrect output when qualifying a ref that looks fully- or partially-qualified but actually isn't. For example, qualifying a ref like "refs/heads/master" will produce the same string, from the HEADS pattern, which is wrong if the branch's display name was actually "refs/heads/master", meaning the qualified ref is actually "refs/heads/refs/heads/master".

      Parameters:
      ref - the ref to qualify, which may be fully- or partially-qualified
      Returns:
      a fully qualified ref according to this pattern
      Throws:
      IllegalArgumentException - if the provided ref is empty or blank
      NullPointerException - if the provided ref is null

    • sort

      public String sort(@Nullable com.atlassian.bitbucket.repository.RefOrder order)
      Retrieves a flag that may be provided to the git rev-list --sort= option to sort refs in the specified order.
      Parameters:
      order - the order to apply to refs
      Returns:
      a git rev-list --sort= flag for producing the specified order

    • unqualify

      @Nonnull public String unqualify(@Nonnull String ref)
      Unqualifies the provided ref according to this pattern. The returned value is suitable for use as a ref's display ID.

      This process is the logical negation of qualifying a ref. It removes the path for this pattern from the provided ref if it is present. If the provided ref is partially-qualified, the partial qualification is removed.

      Examples, using the HEADS pattern:

      • "refs/heads/master" -> "master"
      • "heads/master" -> "master"
      • "master" -> "master"
      • "refs/tags/some-tag" -> "refs/tags/some-tag"
      Note that, in the second example, the partial qualifier "heads" was removed. Also note that in the last example, which is a qualified tag, the provided ref is returned unchanged.

      As with qualifying a ref, unqualifying a ref may produce incorrect results when provided a ref that looks fully- or partially-qualified but actually isn't. For example, if the head in the second example above was actually "heads/master" (meaning its fully-qualified name would be "refs/heads/heads/master"), the unqualified name "master" would be incorrect.

      Parameters:
      ref - the ref to unqualify, which may be fully- or partially-qualified
      Returns:
      an unqualified ref according to this pattern
      Throws:
      IllegalArgumentException - if the provided ref is empty or blank
      NullPointerException - if the provided ref is null

    • defaultSort

      protected String defaultSort()
      Retrieves the default sort flag, to be applied to refs when no more-specific sort is desired (or makes sense).
      Returns:
      the default sort