Package org.eclipse.jgit.transport

Class RefSpec

  • All Implemented Interfaces:
    Serializable
    public class RefSpec
extends Object
implements Serializable
    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.

    See Also:
    Serialized Form

    • Field Detail

      • WILDCARD_SUFFIX

        public static final String WILDCARD_SUFFIX
        Suffix for wildcard ref spec component, that indicate matching all refs with specified prefix.
        See Also:
        Constant Field Values

    • Constructor Detail

      • RefSpec

        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.

      • RefSpec

        public RefSpec​(String spec,
               RefSpec.WildcardMode mode)
        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
        If the wildcard mode allows mismatches, then these ref specs are also valid:
        • refs/heads/*
        • refs/heads/*:refs/heads/master
        Parameters:
        spec - string describing the specification.
        mode - whether to allow a wildcard on one side without a wildcard on the other.
        Throws:
        IllegalArgumentException - the specification is invalid.
        Since:
        4.5

      • RefSpec

        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 describing the specification.
        Throws:
        IllegalArgumentException - the specification is invalid.

    • Method Detail

      • isWildcard

        public static boolean isWildcard​(String s)
        Check whether provided string is a wildcard ref spec component.
        Parameters:
        s - ref spec component - string to test. Can be null.
        Returns:
        true if provided string is a wildcard ref spec component.

      • isForceUpdate

        public boolean isForceUpdate()
        Check if this specification wants to forcefully update the destination.
        Returns:
        true if this specification asks for updates without merge tests.

      • setForceUpdate

        public RefSpec setForceUpdate​(boolean forceUpdate)
        Create a new RefSpec with a different force update setting.
        Parameters:
        forceUpdate - new value for force update in the returned instance.
        Returns:
        a new RefSpec with force update as specified.

      • isWildcard

        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:
        true if this specification could match more than one ref.

      • getSource

        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:
        name (or wildcard pattern) to match the source ref.

      • setSource

        public RefSpec setSource​(String source)
        Create a new RefSpec with a different source name setting.
        Parameters:
        source - new value for source in the returned instance.
        Returns:
        a new RefSpec with source as specified.
        Throws:
        IllegalStateException - There is already a destination configured, and the wildcard status of the existing destination disagrees with the wildcard status of the new source.

      • getDestination

        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:
        name (or wildcard) pattern to match the destination ref.

      • setDestination

        public RefSpec setDestination​(String destination)
        Create a new RefSpec with a different destination name setting.
        Parameters:
        destination - new value for destination in the returned instance.
        Returns:
        a new RefSpec with destination as specified.
        Throws:
        IllegalStateException - There is already a source configured, and the wildcard status of the existing source disagrees with the wildcard status of the new destination.

      • setSourceDestination

        public RefSpec setSourceDestination​(String source,
                                    String destination)
        Create a new RefSpec with a different source/destination name setting.
        Parameters:
        source - new value for source in the returned instance.
        destination - new value for destination in the returned instance.
        Returns:
        a new RefSpec with destination as specified.
        Throws:
        IllegalArgumentException - The wildcard status of the new source disagrees with the wildcard status of the new destination.

      • matchSource

        public boolean matchSource​(String r)
        Does this specification's source description match the ref name?
        Parameters:
        r - ref name that should be tested.
        Returns:
        true if the names match; false otherwise.

      • matchSource

        public boolean matchSource​(Ref r)
        Does this specification's source description match the ref?
        Parameters:
        r - ref whose name should be tested.
        Returns:
        true if the names match; false otherwise.

      • matchDestination

        public boolean matchDestination​(String r)
        Does this specification's destination description match the ref name?
        Parameters:
        r - ref name that should be tested.
        Returns:
        true if the names match; false otherwise.

      • matchDestination

        public boolean matchDestination​(Ref r)
        Does this specification's destination description match the ref?
        Parameters:
        r - ref whose name should be tested.
        Returns:
        true if the names match; false otherwise.

      • expandFromSource

        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 - a ref name that matched our source specification. Could be a wildcard also.
        Returns:
        a new specification expanded from provided ref name. Result specification is wildcard if and only if provided ref name is wildcard.
        Throws:
        IllegalStateException - when the RefSpec was constructed with wildcard mode that doesn't require matching wildcards.

      • expandFromSource

        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 - a ref that matched our source specification. Could be a wildcard also.
        Returns:
        a new specification expanded from provided ref name. Result specification is wildcard if and only if provided ref name is wildcard.
        Throws:
        IllegalStateException - when the RefSpec was constructed with wildcard mode that doesn't require matching wildcards.

      • expandFromDestination

        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 - a ref name that matched our destination specification. Could be a wildcard also.
        Returns:
        a new specification expanded from provided ref name. Result specification is wildcard if and only if provided ref name is wildcard.
        Throws:
        IllegalStateException - when the RefSpec was constructed with wildcard mode that doesn't require matching wildcards.

      • expandFromDestination

        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 - a ref that matched our destination specification.
        Returns:
        a new specification expanded from provided ref name. Result specification is wildcard if and only if provided ref name is wildcard.
        Throws:
        IllegalStateException - when the RefSpec was constructed with wildcard mode that doesn't require matching wildcards.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object