com.atlassian.bitbucket.scm.git

Enum GitRefPattern

java.lang.Object

java.lang.Enum<GitRefPattern>

com.atlassian.bitbucket.scm.git.GitRefPattern

All Implemented Interfaces:

Serializable, Comparable<GitRefPattern>

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 Summary

Enum Constants

Enum Constant and Description
HEADS Ref pattern denoting local branches.
PULL_REQUESTS Ref pattern denoting open pull requests.
REMOTES Ref pattern denoting remote branches (agnostic of remote name).
TAGS Ref pattern denoting tags.

Method Summary

Modifier and Type	Method and Description
protected String	defaultSort() Retrieves the default sort flag, to be applied to refs when no more-specific sort is desired (or makes sense).
String[]	getComponents() Retrieves the components that make up this pattern's path.
String	getPath() Retrieves the path under the .git directory containing all refs for this pattern.
String	getRefspec() Retrieves a non-force refspec for this pattern.
String	getRefspec(boolean force) Retrieves a refspec for this pattern.
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.
String	qualify(String ref) Qualifies the provided ref according this pattern.
String	sort(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.
String	unqualify(String ref) Unqualifies the provided ref according to this pattern.
static GitRefPattern	valueOf(String name) Returns the enum constant of this type with the specified name.
static GitRefPattern[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

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 Detail

values

public static GitRefPattern[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (GitRefPattern c : GitRefPattern.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static GitRefPattern valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (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 type 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