org.eclipse.jgit.revwalk

Class RevCommit

java.lang.Object

org.eclipse.jgit.lib.AnyObjectId

org.eclipse.jgit.lib.ObjectId

org.eclipse.jgit.lib.ObjectIdOwnerMap.Entry

org.eclipse.jgit.revwalk.RevObject

org.eclipse.jgit.revwalk.RevCommit

All Implemented Interfaces:

Serializable, Comparable<AnyObjectId>

Direct Known Subclasses:

DepthWalk.Commit, PlotCommit

public class RevCommit
extends RevObject

A commit reference to a commit in the DAG.

See Also:

Serialized Form

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RevCommit(AnyObjectId id) Create a new commit reference.

Method Summary

Modifier and Type	Method and Description
void	carry(RevFlag flag) Carry a RevFlag set on this commit to its parents.
void	disposeBody() Discard the message buffer to reduce memory usage.
PersonIdent	getAuthorIdent() Parse the author identity from the raw buffer.
PersonIdent	getCommitterIdent() Parse the committer identity from the raw buffer.
int	getCommitTime() Time from the "committer " line of the buffer.
Charset	getEncoding() Determine the encoding of the commit message buffer.
String	getEncodingName() Determine the encoding of the commit message buffer.
List<FooterLine>	getFooterLines() Parse the footer lines (e.g.
List<String>	getFooterLines(FooterKey keyName) Get the values of all footer lines with the given key.
List<String>	getFooterLines(String keyName) Get the values of all footer lines with the given key.
String	getFullMessage() Parse the complete commit message and decode it to a string.
RevCommit	getParent(int nth) Get the nth parent from this commit's parent list.
int	getParentCount() Get the number of parent commits listed in this commit.
RevCommit[]	getParents() Obtain an array of all parents (NOTE - THIS IS NOT A COPY).
byte[]	getRawBuffer() Obtain the raw unparsed commit body (NOTE - THIS IS NOT A COPY).
String	getShortMessage() Parse the commit message and return the first "line" of it.
RevTree	getTree() Get a reference to this commit's tree.
int	getType() Get Git object type.
static RevCommit	parse(byte[] raw) Parse a commit from its canonical format.
static RevCommit	parse(RevWalk rw, byte[] raw) Parse a commit from its canonical format.
void	reset() Reset this commit to allow another RevWalk with the same instances.
String	toString()

Methods inherited from class org.eclipse.jgit.revwalk.RevObject

add, add, appendCoreFlags, getId, has, hasAll, hasAny, remove, remove

Methods inherited from class org.eclipse.jgit.lib.ObjectId

equals, fromRaw, fromRaw, fromRaw, fromRaw, fromString, fromString, isId, toObjectId, toString, zeroId

Methods inherited from class org.eclipse.jgit.lib.AnyObjectId

abbreviate, compareTo, compareTo, compareTo, copy, copyRawTo, copyRawTo, copyRawTo, copyRawTo, copyTo, copyTo, copyTo, copyTo, copyTo, copyTo, equals, equals, equals, getByte, getFirstByte, getName, hashCode, name, startsWith

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

RevCommit

protected RevCommit(AnyObjectId id)

Create a new commit reference.

Parameters:

id - object name for the commit.

Method Detail

parse

public static RevCommit parse(byte[] raw)

Parse a commit from its canonical format. This method constructs a temporary revision pool, parses the commit as supplied, and returns it to the caller. Since the commit was built inside of a private revision pool its parent pointers will be initialized, but will not have their headers loaded. Applications are discouraged from using this API. Callers usually need more than one commit. Use RevWalk.parseCommit(AnyObjectId) to obtain a RevCommit from an existing repository.

Parameters:

raw - the canonical formatted commit to be parsed.

Returns:

the parsed commit, in an isolated revision pool that is not available to the caller.

parse

public static RevCommit parse(RevWalk rw,
                              byte[] raw)
                       throws IOException

Parse a commit from its canonical format.

This method inserts the commit directly into the caller supplied revision pool, making it appear as though the commit exists in the repository, even if it doesn't. The repository under the pool is not affected.

The body of the commit (message, author, committer) is always retained in the returned RevCommit, even if the supplied RevWalk has been configured with setRetainBody(false).

Parameters:

rw - the revision pool to allocate the commit within. The commit's tree and parent pointers will be obtained from this pool.

raw - the canonical formatted commit to be parsed. This buffer will be retained by the returned RevCommit and must not be modified by the caller.

Returns:

the parsed commit, in an isolated revision pool that is not available to the caller.

Throws:

IOException - in case of RevWalk initialization fails

getType

public final int getType()

Description copied from class: RevObject

Get Git object type. See Constants.

Specified by:

getType in class RevObject

Returns:

object type

carry

public void carry(RevFlag flag)

Carry a RevFlag set on this commit to its parents.

If this commit is parsed, has parents, and has the supplied flag set on it we automatically add it to the parents, grand-parents, and so on until an unparsed commit or a commit with no parents is discovered. This permits applications to force a flag through the history chain when necessary.

Parameters:

flag - the single flag value to carry back onto parents.

getCommitTime

public final int getCommitTime()

Time from the "committer " line of the buffer.

Returns:

time, expressed as seconds since the epoch.

getTree

public final RevTree getTree()

Get a reference to this commit's tree.

Returns:

tree of this commit.

getParentCount

public final int getParentCount()

Get the number of parent commits listed in this commit.

Returns:

number of parents; always a positive value but can be 0.

getParent

public final RevCommit getParent(int nth)

Get the nth parent from this commit's parent list.

Parameters:

nth - parent index to obtain. Must be in the range 0 through getParentCount()-1.

Returns:

the specified parent.

Throws:

ArrayIndexOutOfBoundsException - an invalid parent index was specified.

getParents

public final RevCommit[] getParents()

Obtain an array of all parents (NOTE - THIS IS NOT A COPY).

This method is exposed only to provide very fast, efficient access to this commit's parent list. Applications relying on this list should be very careful to ensure they do not modify its contents during their use of it.

Returns:

the array of parents.

getRawBuffer

public final byte[] getRawBuffer()

Obtain the raw unparsed commit body (NOTE - THIS IS NOT A COPY).

This method is exposed only to provide very fast, efficient access to this commit's message buffer within a RevFilter. Applications relying on this buffer should be very careful to ensure they do not modify its contents during their use of it.

Returns:

the raw unparsed commit body. This is NOT A COPY. Altering the contents of this buffer may alter the walker's knowledge of this commit, and the results it produces.

getAuthorIdent

public final PersonIdent getAuthorIdent()

Parse the author identity from the raw buffer.

This method parses and returns the content of the author line, after taking the commit's character set into account and decoding the author name and email address. This method is fairly expensive and produces a new PersonIdent instance on each invocation. Callers should invoke this method only if they are certain they will be outputting the result, and should cache the return value for as long as necessary to use all information from it.

RevFilter implementations should try to use RawParseUtils to scan the getRawBuffer() instead, as this will allow faster evaluation of commits.

Returns:

identity of the author (name, email) and the time the commit was made by the author; null if no author line was found.

getCommitterIdent

public final PersonIdent getCommitterIdent()

Parse the committer identity from the raw buffer.

This method parses and returns the content of the committer line, after taking the commit's character set into account and decoding the committer name and email address. This method is fairly expensive and produces a new PersonIdent instance on each invocation. Callers should invoke this method only if they are certain they will be outputting the result, and should cache the return value for as long as necessary to use all information from it.

RevFilter implementations should try to use RawParseUtils to scan the getRawBuffer() instead, as this will allow faster evaluation of commits.

Returns:

identity of the committer (name, email) and the time the commit was made by the committer; null if no committer line was found.

getFullMessage

public final String getFullMessage()

Parse the complete commit message and decode it to a string.

This method parses and returns the message portion of the commit buffer, after taking the commit's character set into account and decoding the buffer using that character set. This method is a fairly expensive operation and produces a new string on each invocation.

Returns:

decoded commit message as a string. Never null.

getShortMessage

public final String getShortMessage()

Parse the commit message and return the first "line" of it.

The first line is everything up to the first pair of LFs. This is the "oneline" format, suitable for output in a single line display.

This method parses and returns the message portion of the commit buffer, after taking the commit's character set into account and decoding the buffer using that character set. This method is a fairly expensive operation and produces a new string on each invocation.

Returns:

decoded commit message as a string. Never null. The returned string does not contain any LFs, even if the first paragraph spanned multiple lines. Embedded LFs are converted to spaces.

getEncodingName

@Nullable
public final String getEncodingName()

Determine the encoding of the commit message buffer.

Locates the "encoding" header (if present) and returns its value. Due to corruption in the wild this may be an invalid encoding name that is not recognized by any character encoding library.

If no encoding header is present, null.

Returns:

the preferred encoding of getRawBuffer(); or null.

Since:

4.2

getEncoding

public final Charset getEncoding()

Determine the encoding of the commit message buffer.

Locates the "encoding" header (if present) and then returns the proper character set to apply to this buffer to evaluate its contents as character data.

If no encoding header is present UTF-8 is assumed.

Returns:

the preferred encoding of getRawBuffer().

Throws:

IllegalCharsetNameException - if the character set requested by the encoding header is malformed and unsupportable.

UnsupportedCharsetException - if the JRE does not support the character set requested by the encoding header.

getFooterLines

public final List<FooterLine> getFooterLines()

Parse the footer lines (e.g. "Signed-off-by") for machine processing.

This method splits all of the footer lines out of the last paragraph of the commit message, providing each line as a key-value pair, ordered by the order of the line's appearance in the commit message itself.

A footer line's key must match the pattern ^[A-Za-z0-9-]+:, while the value is free-form, but must not contain an LF. Very common keys seen in the wild are:

• Signed-off-by (agrees to Developer Certificate of Origin)
• Acked-by (thinks change looks sane in context)
• Reported-by (originally found the issue this change fixes)
• Tested-by (validated change fixes the issue for them)
• CC, Cc (copy on all email related to this change)
• Bug (link to project's bug tracking system)

Returns:

ordered list of footer lines; empty list if no footers found.

getFooterLines

public final List<String> getFooterLines(String keyName)

Get the values of all footer lines with the given key.

Parameters:

keyName - footer key to find values of, case insensitive.

Returns:

values of footers with key of keyName, ordered by their order of appearance. Duplicates may be returned if the same footer appeared more than once. Empty list if no footers appear with the specified key, or there are no footers at all.

See Also:

getFooterLines()

getFooterLines

public final List<String> getFooterLines(FooterKey keyName)

Get the values of all footer lines with the given key.

Parameters:

keyName - footer key to find values of, case insensitive.

Returns:

values of footers with key of keyName, ordered by their order of appearance. Duplicates may be returned if the same footer appeared more than once. Empty list if no footers appear with the specified key, or there are no footers at all.

See Also:

getFooterLines()

reset

public void reset()

Reset this commit to allow another RevWalk with the same instances.

Subclasses must call super.reset() to ensure the basic information can be correctly cleared out.

disposeBody

public final void disposeBody()

Discard the message buffer to reduce memory usage.

After discarding the memory usage of the RevCommit is reduced to only the getTree() and getParents() pointers and the time in getCommitTime(). Accessing other properties such as getAuthorIdent(), getCommitterIdent() or either message function requires reloading the buffer by invoking RevWalk.parseBody(RevObject).

Since:

4.0

toString

public String toString()

Overrides:

toString in class RevObject