Module org.eclipse.jgit

Package org.eclipse.jgit.api

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 Summary

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
String	call()
DescribeCommand	setAbbrev(int abbrev)	Sets the prefix length to use when abbreviating an object SHA-1.
DescribeCommand	setAll(boolean all)	Instead of using only the annotated tags, use any ref found in refs/ namespace.
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(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(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

Constructor Detail

DescribeCommand

protected DescribeCommand(Repository repo)

Constructor for DescribeCommand.

Parameters:

repo - the Repository

Method Detail

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:

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

setAbbrev

public DescribeCommand setAbbrev(int abbrev)

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

Parameters:

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

Returns:

this

Since:

6.1

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:

Git documentation about describe

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