Class DescribeCommand

java.lang.Object
org.eclipse.jgit.api.GitCommand<String>
org.eclipse.jgit.api.DescribeCommand
All Implemented Interfaces:
Callable<String>

public class DescribeCommand extends GitCommand<String>
Given a commit, show the most recent tag that is reachable from a commit.
Since:
3.2
  • Field Details

    • w

      private final RevWalk w
    • 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 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 Comparator<Ref> TAG_TIE_BREAKER
  • Constructor Details

    • DescribeCommand

      protected DescribeCommand(Repository repo)
      Constructor for DescribeCommand.
      Parameters:
      repo - the Repository
  • Method Details

    • setTarget

      public DescribeCommand setTarget(ObjectId target) throws 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.
      IOException - a pack file or loose object could not be read.
    • setTarget

      public DescribeCommand setTarget(String rev) throws IOException, RefNotFoundException
      Sets the commit to be described.
      Parameters:
      rev - Commit ID, tag, branch, ref, etc. See Repository.resolve(String) for allowed syntax.
      Returns:
      this
      Throws:
      IncorrectObjectTypeException - the supplied id is not a commit or an annotated tag.
      RefNotFoundException - the given rev didn't resolve to any object.
      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:
    • 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 String longDescription(Ref tag, int depth, ObjectId tip) throws IOException
      Throws:
      IOException
    • setMatch

      public DescribeCommand setMatch(String... patterns) throws InvalidPatternException
      Sets one or more glob(7) patterns that tags must match to be considered. If multiple patterns are provided, tags only need match one of them.
      Parameters:
      patterns - the glob(7) pattern or patterns
      Returns:
      this
      Throws:
      InvalidPatternException - if the pattern passed in was invalid.
      Since:
      4.9
      See Also:
    • getBestMatch

      private Optional<Ref> getBestMatch(List<Ref> tags)
    • getObjectIdFromRef

      private ObjectId getObjectIdFromRef(Ref r) throws JGitInternalException
      Throws:
      JGitInternalException
    • call

      public 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 Callable<String>
      Specified by:
      call in class GitCommand<String>
      Throws:
      GitAPIException
    • formatRefName

      private String formatRefName(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