Top Description Inners Fields Constructors Methods
org.eclipse.jgit.transport

public Class RefSpec

extends Object
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable
Imports
java.io.Serializable, java.text.MessageFormat, java.util.Objects, org.eclipse.jgit.internal.JGitText, org.eclipse.jgit.lib.Constants, .Ref

Describes how refs in one repository copy into another repository.

A ref specification provides matching support and limited rules to rewrite a reference in one repository to another reference in another repository.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
RefSpec.WildcardMode

How strict to be about wildcards.

Field Summary

Modifier and TypeField and Description
private RefSpec.WildcardMode
allowMismatchedWildcards

Whether a wildcard is allowed on one side but not the other.

private String
dstName

Name of the ref(s) we would copy into.

private boolean
force

Does this specification ask for forced updated (rewind/reset)?

private boolean
matching

Is this the special ":" RefSpec?

private boolean
negative

Is this a negative refspec.

private static final long
private String
srcName

Name of the ref(s) we would copy from.

private boolean
wildcard

Is this specification actually a wildcard match?

public static final String
WILDCARD_SUFFIX

Suffix for wildcard ref spec component, that indicate matching all refs with specified prefix.

Constructor Summary

AccessConstructor and Description
public
RefSpec()

Construct an empty RefSpec.

public
RefSpec(String
string describing the specification.
spec
,
RefSpec.WildcardMode
whether to allow a wildcard on one side without a wildcard on the other.
mode
)

Parse a ref specification for use during transport operations.

public
RefSpec(String
string describing the specification.
spec
)

Parse a ref specification for use during transport operations.

private

Method Summary

Modifier and TypeMethod and Description
private static String
public boolean
equals(Object
the reference object with which to compare.
obj
)

Overrides java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

public RefSpec

Returns:

a new specification expanded from provided ref name. Result specification is wildcard if and only if provided ref name is wildcard.
expandFromDestination
(String
a ref name that matched our destination specification. Could be a wildcard also.
r
)

Expand this specification to exactly match a ref name.

public RefSpec

Returns:

a new specification expanded from provided ref name. Result specification is wildcard if and only if provided ref name is wildcard.
expandFromDestination
(Ref
a ref that matched our destination specification.
r
)

Expand this specification to exactly match a ref.

private RefSpec
public RefSpec

Returns:

a new specification expanded from provided ref name. Result specification is wildcard if and only if provided ref name is wildcard.
expandFromSource
(String
a ref name that matched our source specification. Could be a wildcard also.
r
)

Expand this specification to exactly match a ref name.

public RefSpec

Returns:

a new specification expanded from provided ref name. Result specification is wildcard if and only if provided ref name is wildcard.
expandFromSource
(Ref
a ref that matched our source specification. Could be a wildcard also.
r
)

Expand this specification to exactly match a ref.

private RefSpec
private static String
expandWildcard(String name, String patternA, String patternB)

public String

Returns:

name (or wildcard) pattern to match the destination ref.
getDestination
()

Get the destination ref description.

public String

Returns:

name (or wildcard pattern) to match the source ref.
getSource
()

Get the source ref description.

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.

public boolean

Returns:

true if this specification asks for updates without merge tests.
isForceUpdate
()

Check if this specification wants to forcefully update the destination.

public boolean

Returns:

whether this is a "matching" RefSpec
isMatching
()

Tells whether this RefSpec is the special "matching" RefSpec ":" for pushing.

public boolean

Returns:

true if this specification is negative.
isNegative
()

Check if this specification is a negative one.

private static boolean
private static boolean
public static boolean

Returns:

true if provided string is a wildcard ref spec component.
isWildcard
(String
ref spec component - string to test. Can be null.
s
)

Check whether provided string is a wildcard ref spec component.

public boolean

Returns:

true if this specification could match more than one ref.
isWildcard
()

Check if this specification is actually a wildcard pattern.

private boolean
match(String name, String s)

public boolean

Returns:

true if the names match; false otherwise.
matchDestination
(String
ref name that should be tested.
r
)

Does this specification's destination description match the ref name?

public boolean

Returns:

true if the names match; false otherwise.
matchDestination
(Ref
ref whose name should be tested.
r
)

Does this specification's destination description match the ref?

public boolean

Returns:

true if the names match; false otherwise.
matchSource
(String
ref name that should be tested.
r
)

Does this specification's source description match the ref name?

public boolean

Returns:

true if the names match; false otherwise.
matchSource
(Ref
ref whose name should be tested.
r
)

Does this specification's source description match the ref?

public RefSpec

Returns:

a new RefSpec with destination as specified.
setDestination
(String
new value for destination in the returned instance.
destination
)

Create a new RefSpec with a different destination name setting.

public RefSpec

Returns:

a new RefSpec with force update as specified.
setForceUpdate
(boolean
new value for force update in the returned instance.
forceUpdate
)

Create a new RefSpec with a different force update setting.

public RefSpec

Returns:

a new RefSpec with source as specified.
setSource
(String
new value for source in the returned instance.
source
)

Create a new RefSpec with a different source name setting.

public RefSpec

Returns:

a new RefSpec with destination as specified.
setSourceDestination
(String
new value for source in the returned instance.
source
,
String
new value for destination in the returned instance.
destination
)

Create a new RefSpec with a different source/destination name setting.

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

allowMismatchedWildcardsback to summary
private RefSpec.WildcardMode allowMismatchedWildcards

Whether a wildcard is allowed on one side but not the other.

dstNameback to summary
private String dstName

Name of the ref(s) we would copy into.

forceback to summary
private boolean force

Does this specification ask for forced updated (rewind/reset)?

matchingback to summary
private boolean matching

Is this the special ":" RefSpec?

negativeback to summary
private boolean negative

Is this a negative refspec.

serialVersionUIDback to summary
private static final long serialVersionUID
srcNameback to summary
private String srcName

Name of the ref(s) we would copy from.

wildcardback to summary
private boolean wildcard

Is this specification actually a wildcard match?

WILDCARD_SUFFIXback to summary
public static final String WILDCARD_SUFFIX

Suffix for wildcard ref spec component, that indicate matching all refs with specified prefix.

Constructor Detail

RefSpecback to summary
public RefSpec()

Construct an empty RefSpec.

A newly created empty RefSpec is not suitable for use in most applications, as at least one field must be set to match a source name.

RefSpecback to summary
public RefSpec(String spec, RefSpec.WildcardMode mode)

Parse a ref specification for use during transport operations.

RefSpecs can be regular or negative, regular RefSpecs indicate what to include in transport operations while negative RefSpecs indicate what to exclude in fetch.

Negative RefSpecs can't be force, must have only source or destination. Wildcard patterns are also supported in negative RefSpecs but they can not go with WildcardMode.REQUIRE_MATCH because they are natually one to many mappings.

Specifications are typically one of the following forms:

  • refs/heads/master
  • refs/heads/master:refs/remotes/origin/master
  • refs/heads/*:refs/remotes/origin/*
  • +refs/heads/master
  • +refs/heads/master:refs/remotes/origin/master
  • +refs/heads/*:refs/remotes/origin/*
  • +refs/pull/*/head:refs/remotes/origin/pr/*
  • :refs/heads/master
If the wildcard mode allows mismatches, then these ref specs are also valid:
  • refs/heads/*
  • refs/heads/*:refs/heads/master
Negative specifications are usually like:
  • ^:refs/heads/master
  • ^refs/heads/*
Parameters
spec:String

string describing the specification.

mode:RefSpec.WildcardMode

whether to allow a wildcard on one side without a wildcard on the other.

Exceptions
IllegalArgumentException:
the specification is invalid.
Since
4.5
RefSpecback to summary
public RefSpec(String spec)

Parse a ref specification for use during transport operations.

Specifications are typically one of the following forms:

  • refs/heads/master
  • refs/heads/master:refs/remotes/origin/master
  • refs/heads/*:refs/remotes/origin/*
  • +refs/heads/master
  • +refs/heads/master:refs/remotes/origin/master
  • +refs/heads/*:refs/remotes/origin/*
  • +refs/pull/*/head:refs/remotes/origin/pr/*
  • :refs/heads/master
Parameters
spec:String

string describing the specification.

Exceptions
IllegalArgumentException:
the specification is invalid.
RefSpecback to summary
private RefSpec(RefSpec p)

Method Detail

checkValidback to summary
private static String checkValid(String spec)
equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
obj:Object

the reference object with which to compare.

Returns:boolean

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
expandFromDestinationback to summary
public RefSpec expandFromDestination(String r)

Expand this specification to exactly match a ref name.

Callers must first verify the passed ref name matches this specification, otherwise expansion results may be unpredictable.

Parameters
r:String

a ref name that matched our destination specification. Could be a wildcard also.

Returns:RefSpec

a new specification expanded from provided ref name. Result specification is wildcard if and only if provided ref name is wildcard.

Exceptions
IllegalStateException:
when the RefSpec was constructed with wildcard mode that doesn't require matching wildcards.
expandFromDestinationback to summary
public RefSpec expandFromDestination(Ref r)

Expand this specification to exactly match a ref.

Callers must first verify the passed ref matches this specification, otherwise expansion results may be unpredictable.

Parameters
r:Ref

a ref that matched our destination specification.

Returns:RefSpec

a new specification expanded from provided ref name. Result specification is wildcard if and only if provided ref name is wildcard.

Exceptions
IllegalStateException:
when the RefSpec was constructed with wildcard mode that doesn't require matching wildcards.
expandFromDstImpback to summary
private RefSpec expandFromDstImp(String name)
expandFromSourceback to summary
public RefSpec expandFromSource(String r)

Expand this specification to exactly match a ref name.

Callers must first verify the passed ref name matches this specification, otherwise expansion results may be unpredictable.

Parameters
r:String

a ref name that matched our source specification. Could be a wildcard also.

Returns:RefSpec

a new specification expanded from provided ref name. Result specification is wildcard if and only if provided ref name is wildcard.

Exceptions
IllegalStateException:
when the RefSpec was constructed with wildcard mode that doesn't require matching wildcards.
expandFromSourceback to summary
public RefSpec expandFromSource(Ref r)

Expand this specification to exactly match a ref.

Callers must first verify the passed ref matches this specification, otherwise expansion results may be unpredictable.

Parameters
r:Ref

a ref that matched our source specification. Could be a wildcard also.

Returns:RefSpec

a new specification expanded from provided ref name. Result specification is wildcard if and only if provided ref name is wildcard.

Exceptions
IllegalStateException:
when the RefSpec was constructed with wildcard mode that doesn't require matching wildcards.
expandFromSourceImpback to summary
private RefSpec expandFromSourceImp(String name)
expandWildcardback to summary
private static String expandWildcard(String name, String patternA, String patternB)
getDestinationback to summary
public String getDestination()

Get the destination ref description.

During a fetch this is the local tracking branch that will be updated with the new ObjectId after fetching is complete. During a push this is the remote ref that will be updated by the remote's receive-pack process.

If null during a fetch no tracking branch should be updated and the ObjectId should be stored transiently in order to prepare a merge.

If null during a push, use getSource() instead.

Returns:String

name (or wildcard) pattern to match the destination ref.

getSourceback to summary
public String getSource()

Get the source ref description.

During a fetch this is the name of the ref on the remote repository we are fetching from. During a push this is the name of the ref on the local repository we are pushing out from.

Returns:String

name (or wildcard pattern) to match the source ref.

hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object

Annotations
@Override
isForceUpdateback to summary
public boolean isForceUpdate()

Check if this specification wants to forcefully update the destination.

Returns:boolean

true if this specification asks for updates without merge tests.

isMatchingback to summary
public boolean isMatching()

Tells whether this RefSpec is the special "matching" RefSpec ":" for pushing.

Returns:boolean

whether this is a "matching" RefSpec

Since
6.1
isNegativeback to summary
public boolean isNegative()

Check if this specification is a negative one.

Returns:boolean

true if this specification is negative.

Since
6.2
isNullOrEmptyback to summary
private static boolean isNullOrEmpty(String refName)
isValidback to summary
private static boolean isValid(String s)
isWildcardback to summary
public static boolean isWildcard(String s)

Check whether provided string is a wildcard ref spec component.

Parameters
s:String

ref spec component - string to test. Can be null.

Returns:boolean

true if provided string is a wildcard ref spec component.

isWildcardback to summary
public boolean isWildcard()

Check if this specification is actually a wildcard pattern.

If this is a wildcard pattern then the source and destination names returned by getSource() and getDestination() will not be actual ref names, but instead will be patterns.

Returns:boolean

true if this specification could match more than one ref.

matchback to summary
private boolean match(String name, String s)
matchDestinationback to summary
public boolean matchDestination(String r)

Does this specification's destination description match the ref name?

Parameters
r:String

ref name that should be tested.

Returns:boolean

true if the names match; false otherwise.

matchDestinationback to summary
public boolean matchDestination(Ref r)

Does this specification's destination description match the ref?

Parameters
r:Ref

ref whose name should be tested.

Returns:boolean

true if the names match; false otherwise.

matchSourceback to summary
public boolean matchSource(String r)

Does this specification's source description match the ref name?

Parameters
r:String

ref name that should be tested.

Returns:boolean

true if the names match; false otherwise.

matchSourceback to summary
public boolean matchSource(Ref r)

Does this specification's source description match the ref?

Parameters
r:Ref

ref whose name should be tested.

Returns:boolean

true if the names match; false otherwise.

setDestinationback to summary
public RefSpec setDestination(String destination)

Create a new RefSpec with a different destination name setting.

Parameters
destination:String

new value for destination in the returned instance.

Returns:RefSpec

a new RefSpec with destination as specified.

Exceptions
IllegalStateException:
There is already a source configured, and the wildcard status of the existing source disagrees with the wildcard status of the new destination.
setForceUpdateback to summary
public RefSpec setForceUpdate(boolean forceUpdate)

Create a new RefSpec with a different force update setting.

Parameters
forceUpdate:boolean

new value for force update in the returned instance.

Returns:RefSpec

a new RefSpec with force update as specified.

setSourceback to summary
public RefSpec setSource(String source)

Create a new RefSpec with a different source name setting.

Parameters
source:String

new value for source in the returned instance.

Returns:RefSpec

a new RefSpec with source as specified.

Exceptions
IllegalStateException:
There is already a destination configured, and the wildcard status of the existing destination disagrees with the wildcard status of the new source.
setSourceDestinationback to summary
public RefSpec setSourceDestination(String source, String destination)

Create a new RefSpec with a different source/destination name setting.

Parameters
source:String

new value for source in the returned instance.

destination:String

new value for destination in the returned instance.

Returns:RefSpec

a new RefSpec with destination as specified.

Exceptions
IllegalArgumentException:
The wildcard status of the new source disagrees with the wildcard status of the new destination.
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations
@Override
org.eclipse.jgit.transport back to summary

public final Enum RefSpec.WildcardMode

extends Enum<RefSpec.WildcardMode>
Class Inheritance

How strict to be about wildcards.
Since
4.5

Field Summary

Modifier and TypeField and Description
public static final RefSpec.WildcardMode
ALLOW_MISMATCH

Allow refspecs with an asterisk on only one side.

public static final RefSpec.WildcardMode
REQUIRE_MATCH

Reject refspecs with an asterisk on the source side and not the destination side or vice versa.

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public static RefSpec.WildcardMode
public static RefSpec.WildcardMode[]
Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

ALLOW_MISMATCHback to summary
public static final RefSpec.WildcardMode ALLOW_MISMATCH

Allow refspecs with an asterisk on only one side. This can create a many-to-one mapping between source and destination refs, so expandFromSource and expandFromDestination are not usable in this mode.

REQUIRE_MATCHback to summary
public static final RefSpec.WildcardMode REQUIRE_MATCH

Reject refspecs with an asterisk on the source side and not the destination side or vice versa. This is the mode used by FetchCommand and PushCommand to create a one-to-one mapping between source and destination refs.

Constructor Detail

WildcardModeback to summary
private WildcardMode()

Method Detail

valueOfback to summary
public static RefSpec.WildcardMode valueOf(String name)
valuesback to summary
public static RefSpec.WildcardMode[] values()