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 and Description
protected	DescribeCommand(Repository repo)

Method Summary

Modifier and Type	Method and Description
String	call() Describes the specified commit.
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	setTarget(ObjectId target) Sets the commit to be described.
DescribeCommand	setTarget(String rev) 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)

Parameters:

repo -

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

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

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>

Returns:

if there's a tag that points to the commit being described, this tag name is returned. Otherwise additional suffix is added to the nearest tag, just like git-describe(1).

If none of the ancestors of the commit being described has any tags at all, then this method returns null, indicating that there's no way to describe this tag.

Throws:

GitAPIException - or subclass thereof when an error occurs