public enum

GitRefPattern

extends Enum<E extends Enum<E>>
java.lang.Object
   ↳ java.lang.Enum<E extends java.lang.Enum<E>>
     ↳ com.atlassian.bitbucket.scm.git.GitRefPattern

Class Overview

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.

Summary

Enum Values
GitRefPattern  HEADS  Ref pattern denoting local branches. 
GitRefPattern  PULL_REQUESTS  Ref pattern denoting open pull requests. 
GitRefPattern  REMOTES  Ref pattern denoting remote branches (agnostic of remote name). 
GitRefPattern  TAGS  Ref pattern denoting tags. 
Public Methods
@Nonnull String[] getComponents()
Retrieves the components that make up this pattern's path.
@Nonnull String getPath()
Retrieves the path under the .git directory containing all refs for this pattern.
@Nonnull String getRefspec(boolean force)
Retrieves a refspec for this pattern.
@Nonnull String getRefspec()
Retrieves a non-force refspec for this pattern.
@Nonnull List<String> getSearchOrder(String ref)
Applies the git precedence ordering for the provided ref, constrained by this pattern, to produce an ordered list of search candidates.
@Nonnull String qualify(String ref)
Qualifies the provided ref according this pattern.
String sort(RefOrder order)
Retrieves a flag that may be provided to the git rev-list --sort= option to sort refs in the specified order.
@Nonnull String unqualify(String ref)
Unqualifies the provided ref according to this pattern.
static GitRefPattern valueOf(String name)
final static GitRefPattern[] values()
Protected Methods
String defaultSort()
Retrieves the default sort flag, to be applied to refs when no more-specific sort is desired (or makes sense).
[Expand]
Inherited Methods
From class java.lang.Enum
From class java.lang.Object
From interface java.lang.Comparable

Enum Values

public static final GitRefPattern HEADS

Ref pattern denoting local branches.

public static final GitRefPattern PULL_REQUESTS

Ref pattern denoting open pull requests.

public static final GitRefPattern REMOTES

Ref pattern denoting remote branches (agnostic of remote name).

public static final GitRefPattern TAGS

Ref pattern denoting tags.

Public Methods

@Nonnull public String[] getComponents ()

Retrieves the components that make up this pattern's path.

Returns
  • the path components for this pattern

@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

@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.

Returns
  • a refspec for refs matching this pattern, optionally allowing forced updates

@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

@Nonnull public List<String> getSearchOrder (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

@Nonnull public String qualify (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

public String sort (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

@Nonnull public String unqualify (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

public static GitRefPattern valueOf (String name)

public static final GitRefPattern[] values ()

Protected Methods

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