Package org.eclipse.jgit.api

Class DescribeCommand

  • All Implemented Interfaces:
    java.util.concurrent.Callable<java.lang.String>
    public class DescribeCommand
extends GitCommand<java.lang.String>
    Given a commit, show the most recent tag that is reachable from a commit.
    Since:
    3.2

    • Field Detail

      • target

        private RevCommit target
        Commit to describe.

      • maxCandidates

        private int maxCandidates
        How many tags we'll consider as candidates. This can only go up to the number of flags JGit can support in a walk, which is 24.

      • longDesc

        private boolean longDesc
        Whether to always use long output format or not.

      • matchers

        private java.util.List<FileNameMatcher> matchers
        Pattern matchers to be applied to tags under consideration.

      • useAll

        private boolean useAll
        Whether to use all refs in the refs/ namespace

      • useTags

        private boolean useTags
        Whether to use all tags (incl. lightweight) or not.

      • always

        private boolean always
        Whether to show a uniquely abbreviated commit hash as a fallback or not.

      • TAG_TIE_BREAKER

        private final java.util.Comparator<Ref> TAG_TIE_BREAKER

    • Constructor Detail

      • DescribeCommand

        protected DescribeCommand​(Repository repo)
        Constructor for DescribeCommand.
        Parameters:
        repo - the Repository

    • Method Detail

      • setTarget

        public DescribeCommand setTarget​(ObjectId target)
                          throws java.io.IOException
        Sets the commit to be described.
        Parameters:
        target - A non-null object ID to be described.
        Returns:
        this
        Throws:
        MissingObjectException - the supplied commit does not exist.
        IncorrectObjectTypeException - the supplied id is not a commit or an annotated tag.
        java.io.IOException - a pack file or loose object could not be read.

      • setLong

        public DescribeCommand setLong​(boolean longDesc)
        Determine whether always to use the long format or not. When set to true the long format is used even the commit matches a tag.
        Parameters:
        longDesc - true if always the long format should be used.
        Returns:
        this
        Since:
        4.0
        See Also:
        Git documentation about describe

      • setAll

        public DescribeCommand setAll​(boolean all)
        Instead of using only the annotated tags, use any ref found in refs/ namespace. This option enables matching any known branch, remote-tracking branch, or lightweight tag.
        Parameters:
        all - true enables matching any ref found in refs/ like setting option --all in c git
        Returns:
        this
        Since:
        5.10

      • setTags

        public DescribeCommand setTags​(boolean tags)
        Instead of using only the annotated tags, use any tag found in refs/tags namespace. This option enables matching lightweight (non-annotated) tags or not.
        Parameters:
        tags - true enables matching lightweight (non-annotated) tags like setting option --tags in c git
        Returns:
        this
        Since:
        5.0

      • setAlways

        public DescribeCommand setAlways​(boolean always)
        Always describe the commit by eventually falling back to a uniquely abbreviated commit hash if no other name matches.
        Parameters:
        always - true enables falling back to a uniquely abbreviated commit hash
        Returns:
        this
        Since:
        5.4

      • longDescription

        private java.lang.String longDescription​(Ref tag,
                                         int depth,
                                         ObjectId tip)
                                  throws java.io.IOException
        Throws:
        java.io.IOException

      • getBestMatch

        private java.util.Optional<Ref> getBestMatch​(java.util.List<Ref> tags)

      • call

        public java.lang.String call()
                      throws GitAPIException

        Execute the command

        Describes the specified commit. Target defaults to HEAD if no commit was set explicitly.

        Specified by:
        call in interface java.util.concurrent.Callable<java.lang.String>
        Specified by:
        call in class GitCommand<java.lang.String>
        Throws:
        GitAPIException

      • formatRefName

        private java.lang.String formatRefName​(java.lang.String name)
        Removes the refs/ or refs/tags prefix from tag names
        Parameters:
        name - the name of the tag
        Returns:
        the tag name with its prefix removed

      • filterLightweightTags

        private boolean filterLightweightTags​(Ref ref)
        Whether we use lightweight tags or not for describe Candidates
        Parameters:
        ref - reference under inspection
        Returns:
        true if it should be used for describe or not regarding useTags