Package org.eclipse.jgit.api

Class DescribeCommand

java.lang.Object

org.eclipse.jgit.api.GitCommand<java.lang.String>

org.eclipse.jgit.api.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 Summary

Fields

Modifier and Type	Field	Description
private boolean	always	Whether to show a uniquely abbreviated commit hash as a fallback or not.
private boolean	longDesc	Whether to always use long output format or not.
private java.util.List<FileNameMatcher>	matchers	Pattern matchers to be applied to tags under consideration.
private int	maxCandidates	How many tags we'll consider as candidates.
private java.util.Comparator<Ref>	TAG_TIE_BREAKER
private RevCommit	target	Commit to describe.
private boolean	useTags	Whether to use all tags (incl.
private RevWalk	w

Fields inherited from class org.eclipse.jgit.api.GitCommand

repo

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	DescribeCommand(Repository repo)	Constructor for DescribeCommand.

Method Summary

Modifier and Type	Method	Description
java.lang.String	call()
private boolean	filterLightweightTags(Ref ref)	Whether we use lightweight tags or not for describe Candidates
private java.util.Optional<Ref>	getBestMatch(java.util.List<Ref> tags)
private ObjectId	getObjectIdFromRef(Ref r)
private java.lang.String	longDescription(Ref tag, int depth, ObjectId tip)
DescribeCommand	setAlways(boolean always)	Always describe the commit by eventually falling back to a uniquely abbreviated commit hash if no other name matches.
DescribeCommand	setLong(boolean longDesc)	Determine whether always to use the long format or not.
DescribeCommand	setMatch(java.lang.String... patterns)	Sets one or more glob(7) patterns that tags must match to be considered.
DescribeCommand	setTags(boolean tags)	Instead of using only the annotated tags, use any tag found in refs/tags namespace.
DescribeCommand	setTarget(java.lang.String rev)	Sets the commit to be described.
DescribeCommand	setTarget(ObjectId target)	Sets the commit to be described.

Methods inherited from class org.eclipse.jgit.api.GitCommand

checkCallable, getRepository, setCallable

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

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 java.util.List<FileNameMatcher> matchers

Pattern matchers to be applied to tags under consideration.

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.

setTarget

public DescribeCommand setTarget(java.lang.String rev)
                          throws java.io.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.

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

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

setMatch

public DescribeCommand setMatch(java.lang.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:

Git documentation about describe

getBestMatch

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

getObjectIdFromRef

private ObjectId getObjectIdFromRef(Ref r)
                             throws JGitInternalException

Throws:

JGitInternalException

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

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