pl.project13.jgit

Class DescribeCommand

java.lang.Object

org.eclipse.jgit.api.GitCommand<DescribeResult>

pl.project13.jgit.DescribeCommand

All Implemented Interfaces:

Callable<DescribeResult>

public class DescribeCommand
extends org.eclipse.jgit.api.GitCommand<DescribeResult>

Implements git's

describe

command.

  usage: git describe [options] *
  or: git describe [options] --dirty
 

   --contains            find the tag that comes after the commit
   --debug               debug search strategy on stderr
   --all                 use any ref in .git/refs
   --tags                use any tag in .git/refs/tags
   --long                always use long format
   --abbrev[=]        use  digits to display SHA-1s
   --exact-match         only output exact matches
   --candidates       consider  most recent tags (default: 10)
   --match      only consider tags matching 
   --always              show abbreviated commit object as fallback
   --dirty[=]      append  on dirty working tree (default: "-dirty")
 

Author:

Konrad 'ktoso' Malawski

Field Summary

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

repo

Method Summary

Methods

Modifier and Type	Method and Description
DescribeCommand	abbrev(Integer n) --abbrev=N
DescribeCommand	always(boolean always) --always
DescribeCommand	apply(GitDescribeConfig config) Apply all configuration options passed in with .
DescribeResult	call()
DescribeCommand	dirty(String dirtyMarker) --dirty[=mark]
DescribeCommand	forceLongFormat(Boolean forceLongFormat) --long
DescribeCommand	match(String pattern) --match glob-pattern
static DescribeCommand	on(org.eclipse.jgit.lib.Repository repo) Creates a new describe command which interacts with a single repository
DescribeCommand	setVerbose(boolean verbose)
DescribeCommand	tags() Alias for tags(Boolean) with true value
DescribeCommand	tags(Boolean includeLightweightTagsInSearch) --tags
DescribeCommand	withLoggerBridge(LoggerBridge bridge)

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

Method Detail

on

@NotNull
public static DescribeCommand on(org.eclipse.jgit.lib.Repository repo)

Creates a new describe command which interacts with a single repository

Parameters:

repo - the Repository this command should interact with

setVerbose

@NotNull
public DescribeCommand setVerbose(boolean verbose)

withLoggerBridge

@NotNull
public DescribeCommand withLoggerBridge(LoggerBridge bridge)

always

@NotNull
public DescribeCommand always(boolean always)

--always

Show uniquely abbreviated commit object as fallback.

true

by default.

forceLongFormat

@NotNull
public DescribeCommand forceLongFormat(@Nullable
                                      Boolean forceLongFormat)

--long

Always output the long format (the tag, the number of commits and the abbreviated commit name) even when it matches a tag. This is useful when you want to see parts of the commit object name in "describe" output, even when the commit in question happens to be a tagged version. Instead of just emitting the tag name, it will describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2 that points at object deadbee....).

false

by default.

abbrev

@NotNull
public DescribeCommand abbrev(@Nullable
                             Integer n)

--abbrev=N

Instead of using the default 7 hexadecimal digits as the abbreviated object name, use N digits, or as many digits as needed to form a unique object name.

An of 0 will suppress long format, only showing the closest tag.

tags

@NotNull
public DescribeCommand tags(@Nullable
                           Boolean includeLightweightTagsInSearch)

--tags

Instead of using only the annotated tags, use any tag found in .git/refs/tags. This option enables matching a lightweight (non-annotated) tag.

Searching for lightweight tags is false by default.

Example:

    b6a73ed - (HEAD, master)
    d37a598 - (v1.0-fixed-stuff) - a lightweight tag (with no message)
    9597545 - (v1.0) - an annotated tag

  > git describe
    annotated-tag-2-gb6a73ed     # the nearest "annotated" tag is found

  > git describe --tags
    lightweight-tag-1-gb6a73ed   # the nearest tag (including lightweights) is found
 

Using only annotated tags to mark builds may be useful if you're using tags to help yourself with annotating things like "i'll get back to that" etc - you don't need such tags to be exposed. But if you want lightweight tags to be included in the search, enable this option.

tags

public DescribeCommand tags()

Alias for tags(Boolean) with true value

apply

@NotNull
public DescribeCommand apply(@Nullable
                            GitDescribeConfig config)

Apply all configuration options passed in with . If a setting is null, it will not be applied - so for abbrev for example, the default 7 would be used.

Returns:

itself, after applying the settings

dirty

@NotNull
public DescribeCommand dirty(@Nullable
                            String dirtyMarker)

--dirty[=mark]

Describe the working tree. It means describe HEAD and appends mark (

-dirty

by default) if the working tree is dirty.

Parameters:

dirtyMarker - the marker name to be appended to the describe output when the workspace is dirty

Returns:

itself, to allow fluent configuration

match

@NotNull
public DescribeCommand match(@Nullable
                            String pattern)

--match glob-pattern

Consider only those tags which match the given glob pattern.

Parameters:

pattern - the glob style pattern to match against the tag names

Returns:

itself, to allow fluent configuration

call

public DescribeResult call()
                    throws org.eclipse.jgit.api.errors.GitAPIException

Specified by:

call in interface Callable<DescribeResult>

Specified by:

call in class org.eclipse.jgit.api.GitCommand<DescribeResult>

Throws:

org.eclipse.jgit.api.errors.GitAPIException