Top Description Fields Constructors Methods
org.eclipse.jgit.revwalk

public Class RevCommit

extends RevObject
Class Inheritance
Known Direct Subclasses
org.eclipse.jgit.revwalk.RevCommitCG, org.eclipse.jgit.api.NameRevCommand.NameRevCommit, org.eclipse.jgit.blame.ReverseWalk.ReverseCommit, org.eclipse.jgit.revplot.PlotCommit, org.eclipse.jgit.revwalk.DepthWalk.Commit
Static Imports
org.eclipse.jgit.util.RawParseUtils.guessEncoding

A commit reference to a commit in the DAG. The state of the RevCommit isn't populated until the commit is parsed. The newly created RevCommit is unparsed and only has an objectId reference. Other states like parents, trees, commit ident, commit message, etc. are populated/available when the commit is parsed.

Field Summary

Modifier and TypeField and Description
protected byte[]
buffer

Raw unparsed commit body of the commit.

pack-priv int
pack-priv int
pack-priv static final RevCommit[]
protected RevCommit[]
parents

Avoid accessing this field directly.

private static final int
protected RevTree
tree

Tree reference of the commit.

Inherited from org.eclipse.jgit.revwalk.RevObject:
flagsPARSED

Constructor Summary

AccessConstructor and Description
protected
RevCommit(AnyObjectId
object name for the commit.
id
)

Create a new commit reference.

Method Summary

Modifier and TypeMethod and Description
public void
carry(RevFlag
the single flag value to carry back onto parents.
flag
)

Carry a RevFlag set on this commit to its parents.

pack-priv static void
carryFlags(RevCommit c, int carry)

private static FIFORevQueue
carryFlags1(RevCommit c, int carry, int depth)

private static void
private static FIFORevQueue
private static FIFORevQueue
defer(FIFORevQueue q, int carry, RevCommit[] pList, int i)

public final void
disposeBody()

Discard the message buffer to reduce memory usage.

public final PersonIdent

Returns:

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

Parse the author identity from the raw buffer.

public ChangedPathFilter

Returns:

the changed path filter
getChangedPathFilter
(RevWalk
A revwalk to load the commit graph (if available)
rw
)

Get the changed path filter of the commit.

public final PersonIdent

Returns:

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

Parse the committer identity from the raw buffer.

public final int

Returns:

commit time
getCommitTime
()

Time from the "committer " line of the buffer.

public final Charset

Returns:

the preferred encoding of getRawBuffer().
getEncoding
()

Determine the encoding of the commit message buffer.

public final String

Returns:

the preferred encoding of getRawBuffer(); or null.
getEncodingName
()

Determine the encoding of the commit message buffer.

public final String

Returns:

the first line of the decoded commit message as a string; never null.
getFirstMessageLine
()

Parse the commit message and return its first line, i.e., everything up to but not including the first newline, if any.

public final List<FooterLine>

Returns:

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

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

public final List<String>

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.
getFooterLines
(String
footer key to find values of, case-insensitive.
keyName
)

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

public final List<String>

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.
getFooterLines
(FooterKey
footer key to find values of, case-insensitive.
key
)

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

public final String

Returns:

decoded commit message as a string. Never null.
getFullMessage
()

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

pack-priv int

Returns:

the generation number
getGeneration
()

Get the distance of the commit from the root, as defined in org.eclipse.jgit.internal.storage.commitgraph.CommitGraph

Generation number is org.eclipse.jgit.lib.Constants#COMMIT_GENERATION_UNKNOWN when the commit is not in the commit-graph.

public RevCommit

Returns:

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

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

public int

Returns:

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

Get the number of parent commits listed in this commit.

public RevCommit[]

Returns:

the array of parents.
getParents
()

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

public final byte[]

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.
getRawBuffer
()

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

public final byte[]

Returns:

contents of the gpg signature; null if the commit was not signed.
getRawGpgSignature
()

Parse the gpg signature from the raw buffer.

public final String

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.
getShortMessage
()

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

public final RevTree

Returns:

tree of this commit.
getTree
()

Get a reference to this commit's tree.

public final int
getType()

Implements abstract org.eclipse.jgit.revwalk.RevObject.getType.

Get Git object type.

pack-priv static boolean
hasLF(byte[] r, int b, int e)

public static RevCommit

Returns:

the parsed commit, in an isolated revision pool that is not available to the caller.
parse
(byte[]
the canonical formatted commit to be parsed.
raw
)

Parse a commit from its canonical format.

public static RevCommit

Returns:

the parsed commit, in an isolated revision pool that is not available to the caller.
parse
(RevWalk
the revision pool to allocate the commit within. The commit's tree and parent pointers will be obtained from this pool.
rw
,
byte[]
the canonical formatted commit to be parsed. This buffer will be retained by the returned RevCommit and must not be modified by the caller.
raw
)

Parse a commit from its canonical format.

pack-priv void
pack-priv void
parseCanonical(RevWalk walk, byte[] raw)

pack-priv void
public void
reset()

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

private static void
public String
toString()

Overrides org.eclipse.jgit.revwalk.RevObject.toString.

Returns a string representation of the object.

Inherited from org.eclipse.jgit.revwalk.RevObject:
addaddappendCoreFlagsgetIdhashasAllhasAnyremoveremove

Field Detail

bufferback to summary
protected byte[] buffer

Raw unparsed commit body of the commit. Populated only after parseCanonical(RevWalk, byte[]) with RevWalk#isRetainBody() enable or after parseBody(RevWalk) and parse(RevWalk, byte[]).

Since
6.5.1
commitTimeback to summary
pack-priv int commitTime
inDegreeback to summary
pack-priv int inDegree
NO_PARENTSback to summary
pack-priv static final RevCommit[] NO_PARENTS
parentsback to summary
protected RevCommit[] parents

Avoid accessing this field directly. Use method RevCommit#getParents() instead. RevCommit does not allow parents to be overridden and altering parent(s) is not supported.

Since
6.3
STACK_DEPTHback to summary
private static final int STACK_DEPTH
treeback to summary
protected RevTree tree

Tree reference of the commit.

Since
6.5

Constructor Detail

RevCommitback to summary
protected RevCommit(AnyObjectId id)

Create a new commit reference.

Parameters
id:AnyObjectId

object name for the commit.

Method Detail

carryback to summary
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:RevFlag

the single flag value to carry back onto parents.

carryFlagsback to summary
pack-priv static void carryFlags(RevCommit c, int carry)
carryFlags1back to summary
private static FIFORevQueue carryFlags1(RevCommit c, int carry, int depth)
carryOneStepback to summary
private static void carryOneStep(FIFORevQueue q, int carry, RevCommit c)
deferback to summary
private static FIFORevQueue defer(RevCommit c)
deferback to summary
private static FIFORevQueue defer(FIFORevQueue q, int carry, RevCommit[] pList, int i)
disposeBodyback to summary
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 org.eclipse.jgit.revwalk.RevWalk#parseBody(RevObject).

Since
4.0
getAuthorIdentback to summary
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 org.eclipse.jgit.util.RawParseUtils to scan the getRawBuffer() instead, as this will allow faster evaluation of commits.

Returns:PersonIdent

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

getChangedPathFilterback to summary
public ChangedPathFilter getChangedPathFilter(RevWalk rw)

Get the changed path filter of the commit.

This is null when there is no commit graph file, the commit is not in the commit graph file, or the commit graph file was generated without changed path filters.

Parameters
rw:RevWalk

A revwalk to load the commit graph (if available)

Returns:ChangedPathFilter

the changed path filter

Since
6.7
getCommitterIdentback to summary
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 org.eclipse.jgit.util.RawParseUtils to scan the getRawBuffer() instead, as this will allow faster evaluation of commits.

Returns:PersonIdent

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

getCommitTimeback to summary
public final int getCommitTime()

Time from the "committer " line of the buffer.

Returns:int

commit time

getEncodingback to summary
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:Charset

the preferred encoding of getRawBuffer().

Exceptions
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.
getEncodingNameback to summary
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:String

the preferred encoding of getRawBuffer(); or null.

Annotations
@Nullable
Since
4.2
getFirstMessageLineback to summary
public final String getFirstMessageLine()

Parse the commit message and return its first line, i.e., everything up to but not including the first newline, if any.

Returns:String

the first line of the decoded commit message as a string; never null.

Since
7.2
getFooterLinesback to summary
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. The Value may be split over multiple lines with each subsequent line starting with at least one whitespace. 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:List<FooterLine>

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

getFooterLinesback to summary
public final List<String> getFooterLines(String keyName)

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

Parameters
keyName:String

footer key to find values of, case-insensitive.

Returns:List<String>

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()
getFooterLinesback to summary
public final List<String> getFooterLines(FooterKey key)

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

Parameters
key:FooterKey

footer key to find values of, case-insensitive.

Returns:List<String>

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()
getFullMessageback to summary
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:String

decoded commit message as a string. Never null.

getGenerationback to summary
pack-priv int getGeneration()

Get the distance of the commit from the root, as defined in org.eclipse.jgit.internal.storage.commitgraph.CommitGraph

Generation number is org.eclipse.jgit.lib.Constants#COMMIT_GENERATION_UNKNOWN when the commit is not in the commit-graph. If a commit-graph file was written by a version of Git that did not compute generation numbers, then those commits in commit-graph will have generation number represented by org.eclipse.jgit.lib.Constants#COMMIT_GENERATION_NOT_COMPUTED.

Returns:int

the generation number

Since
6.5
getParentback to summary
public RevCommit getParent(int nth)

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

Parameters
nth:int

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

Returns:RevCommit

the specified parent.

Exceptions
ArrayIndexOutOfBoundsException:
an invalid parent index was specified.
getParentCountback to summary
public int getParentCount()

Get the number of parent commits listed in this commit.

Returns:int

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

getParentsback to summary
public 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:RevCommit[]

the array of parents.

getRawBufferback to summary
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:byte[]

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.

getRawGpgSignatureback to summary
public final byte[] getRawGpgSignature()

Parse the gpg signature from the raw buffer.

This method parses and returns the raw content of the gpgsig lines. This method is fairly expensive and produces a new byte[] instance on each invocation. Callers should invoke this method only if they are certain they will need, and should cache the return value for as long as necessary to use all information from it.

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

Returns:byte[]

contents of the gpg signature; null if the commit was not signed.

Since
5.1
getShortMessageback to summary
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:String

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.

getTreeback to summary
public final RevTree getTree()

Get a reference to this commit's tree.

Returns:RevTree

tree of this commit.

getTypeback to summary
public final int getType()

Implements abstract org.eclipse.jgit.revwalk.RevObject.getType.

Doc from org.eclipse.jgit.revwalk.RevObject.getType.

Get Git object type. See org.eclipse.jgit.lib.Constants.

Returns:int

object type

Annotations
@Override
hasLFback to summary
pack-priv static boolean hasLF(byte[] r, int b, int e)
parseback to summary
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 org.eclipse.jgit.revwalk.RevWalk#parseCommit(AnyObjectId) to obtain a RevCommit from an existing repository.

Parameters
raw:byte[]

the canonical formatted commit to be parsed.

Returns:RevCommit

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

parseback to summary
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:RevWalk

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

raw:byte[]

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:RevCommit

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

Exceptions
IOException:
in case of RevWalk initialization fails
parseBodyback to summary
pack-priv void parseBody(RevWalk walk) throws MissingObjectException, IncorrectObjectTypeException, IOException

Implements abstract org.eclipse.jgit.revwalk.RevObject.parseBody.

Annotations
@Override
parseCanonicalback to summary
pack-priv void parseCanonical(RevWalk walk, byte[] raw) throws IOException
parseHeadersback to summary
pack-priv void parseHeaders(RevWalk walk) throws MissingObjectException, IncorrectObjectTypeException, IOException

Implements abstract org.eclipse.jgit.revwalk.RevObject.parseHeaders.

Annotations
@Override
resetback to summary
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.

slowCarryFlagsback to summary
private static void slowCarryFlags(FIFORevQueue q, int carry)
toStringback to summary
public String toString()

Overrides org.eclipse.jgit.revwalk.RevObject.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations
@Override