Top Description Fields Constructors Methods
org.eclipse.jgit.api

public Class DescribeCommand

extends GitCommand<String>
Class Inheritance
Static Imports
org.eclipse.jgit.lib.Constants.R_REFS, .Constants.R_TAGS, .TypedConfigGetter.UNSET_INT
Given a commit, show the most recent tag that is reachable from a commit.
Since
3.2

Field Summary

Modifier and TypeField and Description
private int
abbrev

The prefix length to use when abbreviating a commit hash.

private boolean
always

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

private List<FileNameMatcher>
excludeMatchers

Pattern matchers to be applied to tags for exclusion.

private boolean
longDesc

Whether to always use long output format or not.

private List<FileNameMatcher>
matchers

Pattern matchers to be applied to tags under consideration.

private int
maxCandidates

How many tags we'll consider as candidates.

private final Comparator<Ref>
TAG_TIE_BREAKER

private RevCommit
target

Commit to describe.

private boolean
useAll

Whether to use all refs in the refs/ namespace

private boolean
useTags

Whether to use all tags (incl.

private final RevWalk
w

Inherited from org.eclipse.jgit.api.GitCommand:
repo

Constructor Summary

AccessConstructor and Description
protected
DescribeCommand(Repository
the org.eclipse.jgit.lib.Repository
repo)

Constructor for DescribeCommand.

Method Summary

Modifier and TypeMethod and Description
public String
call()

Implements abstract org.eclipse.jgit.api.GitCommand.call.

Implements java.util.concurrent.Callable.call.

Computes a result, or throws an exception if unable to do so.

private boolean

Returns:

true if it should be used for describe or not regarding org.eclipse.jgit.api.DescribeCommand#useTags
filterLightweightTags(Ref
reference under inspection
ref)

Whether we use lightweight tags or not for describe Candidates

private String

Returns:

the tag name with its prefix removed
formatRefName(String
the name of the tag
name)

Removes the refs/ or refs/tags prefix from tag names

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

private ObjectId
getObjectIdFromRef(Ref r)

private String
longDescription(Ref tag, int depth, ObjectId tip)

public DescribeCommand

Returns:

this
setAbbrev(int
minimum length of the abbreviated string. Must be in the range [4, 40].
abbrev)

Sets the prefix length to use when abbreviating an object SHA-1.

public DescribeCommand

Returns:

this
setAll(boolean
true enables matching any ref found in refs/ like setting option --all in c git
all)

Instead of using only the annotated tags, use any ref found in refs/ namespace.

public DescribeCommand

Returns:

this
setAlways(boolean
true enables falling back to a uniquely abbreviated commit hash
always)

Always describe the commit by eventually falling back to a uniquely abbreviated commit hash if no other name matches.

public DescribeCommand

Returns:

this
setExclude(String...
the glob(7) pattern or patterns
patterns)

Sets one or more glob(7) patterns that tags must not match to be considered.

public DescribeCommand

Returns:

this
setLong(boolean
true if always the long format should be used.
longDesc)

Determine whether always to use the long format or not.

public DescribeCommand

Returns:

this
setMatch(String...
the glob(7) pattern or patterns
patterns)

Sets one or more glob(7) patterns that tags must match to be considered.

public DescribeCommand

Returns:

this
setTags(boolean
true enables matching lightweight (non-annotated) tags like setting option --tags in c git
tags)

Instead of using only the annotated tags, use any tag found in refs/tags namespace.

public DescribeCommand

Returns:

this
setTarget(ObjectId
A non-null object ID to be described.
target)

Sets the commit to be described.

public DescribeCommand

Returns:

this
setTarget(String
Commit ID, tag, branch, ref, etc. See org.eclipse.jgit.lib.Repository#resolve(String) for allowed syntax.
rev)

Sets the commit to be described.

Inherited from org.eclipse.jgit.api.GitCommand:
checkCallablegetRepositorysetCallable

Field Detail

abbrevback to summary
private int abbrev

The prefix length to use when abbreviating a commit hash.

alwaysback to summary
private boolean always

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

excludeMatchersback to summary
private List<FileNameMatcher> excludeMatchers

Pattern matchers to be applied to tags for exclusion.

longDescback to summary
private boolean longDesc

Whether to always use long output format or not.

matchersback to summary
private List<FileNameMatcher> matchers

Pattern matchers to be applied to tags under consideration.

maxCandidatesback to summary
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.

TAG_TIE_BREAKERback to summary
private final Comparator<Ref> TAG_TIE_BREAKER
targetback to summary
private RevCommit target

Commit to describe.

useAllback to summary
private boolean useAll

Whether to use all refs in the refs/ namespace

useTagsback to summary
private boolean useTags

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

wback to summary
private final RevWalk w

Constructor Detail

DescribeCommandback to summary
protected DescribeCommand(Repository repo)

Constructor for DescribeCommand.

Parameters
repo:Repository

the org.eclipse.jgit.lib.Repository

Method Detail

callback to summary
public String call() throws GitAPIException

Implements abstract org.eclipse.jgit.api.GitCommand.call.

Implements java.util.concurrent.Callable.call.

Doc from org.eclipse.jgit.api.GitCommand.call.

Computes a result, or throws an exception if unable to do so.

Execute the command

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

Returns:String

Doc from java.util.concurrent.Callable.call.

computed result

Annotations
@Override
filterLightweightTagsback to summary
private boolean filterLightweightTags(Ref ref)

Whether we use lightweight tags or not for describe Candidates

Parameters
ref:Ref

reference under inspection

Returns:boolean

true if it should be used for describe or not regarding org.eclipse.jgit.api.DescribeCommand#useTags

Annotations
@SuppressWarnings:null
formatRefNameback to summary
private String formatRefName(String name)

Removes the refs/ or refs/tags prefix from tag names

Parameters
name:String

the name of the tag

Returns:String

the tag name with its prefix removed

getBestMatchback to summary
private Optional<Ref> getBestMatch(List<Ref> tags)
getObjectIdFromRefback to summary
private ObjectId getObjectIdFromRef(Ref r) throws JGitInternalException
longDescriptionback to summary
private String longDescription(Ref tag, int depth, ObjectId tip) throws IOException
setAbbrevback to summary
public DescribeCommand setAbbrev(int abbrev)

Sets the prefix length to use when abbreviating an object SHA-1.

Parameters
abbrev:int

minimum length of the abbreviated string. Must be in the range [4, 40].

Returns:DescribeCommand

this

Since
6.1
setAllback to summary
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:boolean

true enables matching any ref found in refs/ like setting option --all in c git

Returns:DescribeCommand

this

Since
5.10
setAlwaysback to summary
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:boolean

true enables falling back to a uniquely abbreviated commit hash

Returns:DescribeCommand

this

Since
5.4
setExcludeback to summary
public DescribeCommand setExclude(String... patterns) throws InvalidPatternException

Sets one or more glob(7) patterns that tags must not match to be considered. If multiple patterns are provided, they will all be applied.

Parameters
patterns:String[]

the glob(7) pattern or patterns

Returns:DescribeCommand

this

Exceptions
InvalidPatternException:
if the pattern passed in was invalid.
Since
7.2
See Also
Git documentation about describe
setLongback to summary
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:boolean

true if always the long format should be used.

Returns:DescribeCommand

this

Since
4.0
See Also
Git documentation about describe
setMatchback to summary
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:String[]

the glob(7) pattern or patterns

Returns:DescribeCommand

this

Exceptions
InvalidPatternException:
if the pattern passed in was invalid.
Since
4.9
See Also
Git documentation about describe
setTagsback to summary
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:boolean

true enables matching lightweight (non-annotated) tags like setting option --tags in c git

Returns:DescribeCommand

this

Since
5.0
setTargetback to summary
public DescribeCommand setTarget(ObjectId target) throws IOException

Sets the commit to be described.

Parameters
target:ObjectId

A non-null object ID to be described.

Returns:DescribeCommand

this

Exceptions
IOException:
a pack file or loose object could not be read.
MissingObjectException:
the supplied commit does not exist.
IncorrectObjectTypeException:
the supplied id is not a commit or an annotated tag.
setTargetback to summary
public DescribeCommand setTarget(String rev) throws IOException, RefNotFoundException

Sets the commit to be described.

Parameters
rev:String

Commit ID, tag, branch, ref, etc. See org.eclipse.jgit.lib.Repository#resolve(String) for allowed syntax.

Returns:DescribeCommand

this

Exceptions
IOException:
a pack file or loose object could not be read.
RefNotFoundException:
the given rev didn't resolve to any object.
IncorrectObjectTypeException:
the supplied id is not a commit or an annotated tag.