JGit 7.2.0.202503040940-r · org.eclipse.jgit.blame.BlameGenerator

Modifier and Type	Class and Description
public static class	BlameGenerator.Stats Stats about the work done by the generator

Modifier and Type	Field and Description
private final BlameCache	blameCache
private DiffAlgorithm	diffAlgorithm
private final MutableObjectId	idBuf
private Candidate	outCandidate Blame is currently assigned to this source.
private Region	outRegion
private Candidate	queue Potential candidates, sorted by commit time descending.
private ObjectReader	reader
private int	remaining Number of lines that still need to be discovered.
private RenameDetector	renameDetector
private final Repository	repository
private final PathFilter	resultPath
private RevWalk	revPool Revision pool used to acquire commits from.
private RevFlag	SEEN Indicates the commit was put into the queue at least once.
private final BlameGenerator.Stats	stats
private RawTextComparator	textComparator
private TreeWalk	treeWalk
private boolean	useCache Blame in reverse order needs the source lines, but we don't have them in the cache.

Access	Constructor and Description
public	BlameGenerator(Repository repository to access revision data from. repository, String initial path of the file to start scanning (relative to the repository). path) Create a blame generator for the repository and path (relative to repository)
public	BlameGenerator(Repository repository to access revision data from. repository, String initial path of the file to start scanning (relative to the repository). path, BlameCache previously calculated blames. This generator will not populate it, just consume it. blameCache) Create a blame generator for the repository and path (relative to repository)

Method Summary

Modifier and Type	Method and Description
private boolean	blameEntireRegionOnParent(Candidate n, RevCommit parent)
public void	close() Implements java.lang.AutoCloseable.close. Closes this resource, relinquishing any underlying resources.
public BlameResult	Returns: the complete result. Null if no file exists for the given path. computeBlameResult() Execute the generator in a blocking fashion until all data is ready.
private boolean	done()
private boolean	find(RevCommit commit, PathFilter path)
private DiffEntry	findRename(RevCommit parent, RevCommit commit, PathFilter path)
private static byte[]	getBytes(String path, InputStream in, long maxLength)
private List<RevCommit>	getHeads(Repository repo, ObjectId head)
public int	Returns: number of lines in the current region being blamed to `getSourceCommit()`. This is always the value of the expression `getResultEnd() - getResultStart()`, but also `getSourceEnd() - getSourceStart()`. getRegionLength() Get number of lines in the current region being blamed to `getSourceCommit()`
public RenameDetector	Returns: the rename detector, or `null` if `setFollowFileRenames(false)`. getRenameDetector() Obtain the RenameDetector, allowing the application to configure its settings for rename score and breaking behavior.
public int	Returns: rename score if a rename occurred in `getSourceCommit` getRenameScore() Get rename score
public Repository	Returns: repository being scanned for revision history getRepository() Get repository
public RawText	Returns: complete file contents of the result file blame is annotating. This value is accessible only after being configured and only immediately before the first call to `next()`. Returns null if the path does not exist. getResultContents() Get complete file contents of the result file blame is annotating
public int	Returns: one past the range of the result that `getSourceCommit()` has been blamed for providing. Line numbers use 0 based indexing. Because a source cannot be blamed for an empty region of the result, `getResultEnd()` is always at least one larger than `getResultStart()`. getResultEnd() Get one past the range of the result that `getSourceCommit()` has been blamed for providing
public String	Returns: path file path being processed getResultPath() Get result path
public int	Returns: first line of the result that `getSourceCommit()` has been blamed for providing. Line numbers use 0 based indexing. getResultStart() Get first line of the result that `getSourceCommit()` has been blamed for providing
public PersonIdent	Returns: current author being blamed getSourceAuthor() Get source author
public RevCommit	Returns: current revision being blamed. getSourceCommit() Get the revision blamed for the current region.
public PersonIdent	Returns: current committer being blamed getSourceCommitter() Get source committer
public RawText	Returns: complete contents of the source file blamed for the current output region. This is the contents of `getSourcePath()` within `getSourceCommit()`. The source contents is temporarily available as an artifact of the blame algorithm. Most applications will want the result contents for display to users. getSourceContents() Get complete contents of the source file blamed for the current output region
public int	Returns: one past the range of the source data that has been blamed for the current region. This is line number of where the region was added during `getSourceCommit()` in file `getSourcePath()`. getSourceEnd() Get one past the range of the source data that has been blamed for the current region This value is not reliable when the generator is reusing cached values.
public String	Returns: path of the file being blamed getSourcePath() Get source path
public int	Returns: first line of the source data that has been blamed for the current region. This is line number of where the region was added during `getSourceCommit()` in file `getSourcePath()`. getSourceStart() Get first line of the source data that has been blamed for the current region This value is not reliable when the generator is reusing cached values.
public BlameGenerator.Stats	Returns: the stats of this generator getStats() Stats about this generator
private void	initRevPool(boolean reverse)
private static final boolean	isFile(int rawMode)
private static boolean	isRename(DiffEntry ent)
public RevFlag	Returns: the newly allocated flag. newFlag(String unique name of the flag in the blame context. name) Allocate a new RevFlag for use by the caller.
public boolean	Returns: true if the generator has found a region's source. The getSource* and `getResultStart()`, `getResultEnd()` methods can be used to inspect the region found. False if there are no more regions to describe. next() Step the blame algorithm one iteration.
private Candidate	pop()
public BlameGenerator	Returns: `this` prepareHead() Pushes HEAD, index, and working tree as appropriate for blaming the file given in the constructor `BlameGenerator(Repository, String)` against HEAD.
private boolean	processMerge(Candidate n)
private boolean	processOne(Candidate n)
public BlameGenerator	Returns: `this` push(String description of the blob revision, such as "Working Tree". description, byte[] contents of the file. contents) Push a candidate blob onto the generator's traversal stack.
public BlameGenerator	Returns: `this` push(String description of the blob revision, such as "Working Tree". description, RawText contents of the file. contents) Push a candidate blob onto the generator's traversal stack.
public BlameGenerator	Returns: `this` push(String description of the blob revision, such as "Working Tree". description, AnyObjectId may be a commit or a blob. id) Push a candidate object onto the generator's traversal stack.
private void	push(Candidate.BlobCandidate toInsert)
private void	push(Candidate toInsert)
private boolean	result(Candidate n)
public BlameGenerator	Returns: `this` reverse(AnyObjectId oldest commit to traverse from. The result file will be loaded from this commit's tree. start, AnyObjectId most recent commit to stop traversal at. Usually an active branch tip, tag, or HEAD. end) Configure the generator to compute reverse blame (history of deletes).
public BlameGenerator	Returns: `this` reverse(AnyObjectId oldest commit to traverse from. The result file will be loaded from this commit's tree. start, Collection<? extends ObjectId> most recent commits to stop traversal at. Usually an active branch tip, tag, or HEAD. end) Configure the generator to compute reverse blame (history of deletes).
private boolean	reverseResult(Candidate parent, Candidate source)
public BlameGenerator	Returns: `this` setDiffAlgorithm(DiffAlgorithm a `org.eclipse.jgit.diff.DiffAlgorithm` algorithm) Difference algorithm to use when comparing revisions.
public BlameGenerator	Returns: `this` setFollowFileRenames(boolean enable following. follow) Enable (or disable) following file renames, on by default.
public BlameGenerator	Returns: `this` setTextComparator(RawTextComparator a `org.eclipse.jgit.diff.RawTextComparator` comparator) Text comparator to use when comparing revisions.
public void	setUseCache(boolean should this generator use the cache. useCache) Enable/disable the use of cache (if present).
private boolean	split(Candidate parent, Candidate source)
private boolean	splitBlameWithParent(Candidate n, RevCommit parent)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

blameCache	back to summary
private final BlameCache blameCache

diffAlgorithm	back to summary
private DiffAlgorithm diffAlgorithm

idBuf	back to summary
private final MutableObjectId idBuf

outCandidate	back to summary
private Candidate outCandidate Blame is currently assigned to this source.

outRegion	back to summary
private Region outRegion

queue	back to summary
private Candidate queue Potential candidates, sorted by commit time descending.

reader	back to summary
private ObjectReader reader

remaining	back to summary
private int remaining Number of lines that still need to be discovered.

renameDetector	back to summary
private RenameDetector renameDetector

repository	back to summary
private final Repository repository

resultPath	back to summary
private final PathFilter resultPath

revPool	back to summary
private RevWalk revPool Revision pool used to acquire commits from.

SEEN	back to summary
private RevFlag SEEN Indicates the commit was put into the queue at least once.

stats	back to summary
private final BlameGenerator.Stats stats

textComparator	back to summary
private RawTextComparator textComparator

treeWalk	back to summary
private TreeWalk treeWalk

useCache	back to summary
private boolean useCache Blame in reverse order needs the source lines, but we don't have them in the cache. We need to ignore the cache in that case.

BlameGenerator	back to summary
public BlameGenerator(Repository repository, String path) Create a blame generator for the repository and path (relative to repository) Parameters repository:Repository repository to access revision data from. path:String initial path of the file to start scanning (relative to the repository).

BlameGenerator	back to summary
public BlameGenerator(Repository repository, String path, BlameCache blameCache) Create a blame generator for the repository and path (relative to repository) Parameters repository:Repository repository to access revision data from. path:String initial path of the file to start scanning (relative to the repository). blameCache:BlameCache previously calculated blames. This generator will not populate it, just consume it. Since 7.2

Method Detail

blameEntireRegionOnParent	back to summary
private boolean blameEntireRegionOnParent(Candidate n, RevCommit parent)

close back to summary

close	back to summary
public void close() Implements java.lang.AutoCloseable.close. Doc from java.lang.AutoCloseable.close. Closes this resource, relinquishing any underlying resources. This method is invoked automatically on objects managed by the `try`-with-resources statement. Release the current blame session. Annotations @Override Since 4.0

public void close()

Implements java.lang.AutoCloseable.close.

Doc from java.lang.AutoCloseable.close.

Closes this resource, relinquishing any underlying resources. This method is invoked automatically on objects managed by the try-with-resources statement.

Release the current blame session.

Annotations

@Override

Since

4.0

computeBlameResult	back to summary
public BlameResult computeBlameResult() throws IOException Execute the generator in a blocking fashion until all data is ready. Returns:BlameResult the complete result. Null if no file exists for the given path. Exceptions IOException: the repository cannot be read.

computeBlameResult

back to summary

public BlameResult computeBlameResult() throws IOException

Execute the generator in a blocking fashion until all data is ready.

Returns:BlameResult

the complete result. Null if no file exists for the given path.

Exceptions

IOException:: the repository cannot be read.

done	back to summary
private boolean done()

find	back to summary
private boolean find(RevCommit commit, PathFilter path) throws IOException

findRename	back to summary
private DiffEntry findRename(RevCommit parent, RevCommit commit, PathFilter path) throws IOException

getBytes	back to summary
private static byte[] getBytes(String path, InputStream in, long maxLength) throws IOException

getHeads	back to summary
private List<RevCommit> getHeads(Repository repo, ObjectId head) throws NoWorkTreeException, IOException

getRegionLength back to summary

getRegionLength	back to summary
public int getRegionLength() Get number of lines in the current region being blamed to `getSourceCommit()` Returns:int number of lines in the current region being blamed to `getSourceCommit()`. This is always the value of the expression `getResultEnd() - getResultStart()`, but also `getSourceEnd() - getSourceStart()`.

public int getRegionLength()

Get number of lines in the current region being blamed to getSourceCommit()

Returns:int: number of lines in the current region being blamed to getSourceCommit(). This is always the value of the expression getResultEnd() - getResultStart(), but also getSourceEnd() - getSourceStart().

getRenameDetector back to summary

getRenameDetector	back to summary
public RenameDetector getRenameDetector() Obtain the RenameDetector, allowing the application to configure its settings for rename score and breaking behavior. Returns:RenameDetector the rename detector, or `null` if `setFollowFileRenames(false)`. Annotations @Nullable

public RenameDetector getRenameDetector()

Obtain the RenameDetector, allowing the application to configure its settings for rename score and breaking behavior.

Returns:RenameDetector

the rename detector, or null if setFollowFileRenames(false).

Annotations

@Nullable

getRenameScore back to summary

getRenameScore	back to summary
public int getRenameScore() Get rename score Returns:int rename score if a rename occurred in `getSourceCommit`

public int getRenameScore()

Get rename score

Returns:int: rename score if a rename occurred in getSourceCommit

getRepository	back to summary
public Repository getRepository() Get repository Returns:Repository repository being scanned for revision history

getRepository

back to summary

public Repository getRepository()

Get repository

Returns:Repository: repository being scanned for revision history

getResultContents back to summary

getResultContents	back to summary
public RawText getResultContents() throws IOException Get complete file contents of the result file blame is annotating Returns:RawText complete file contents of the result file blame is annotating. This value is accessible only after being configured and only immediately before the first call to `next()`. Returns null if the path does not exist. Exceptions IOException: repository cannot be read. IllegalStateException: `next()` has already been invoked.

public RawText getResultContents() throws IOException

Get complete file contents of the result file blame is annotating

Returns:RawText

complete file contents of the result file blame is annotating. This value is accessible only after being configured and only immediately before the first call to next(). Returns null if the path does not exist.

Exceptions

IOException:: repository cannot be read.
IllegalStateException:: next() has already been invoked.

getResultEnd back to summary

getResultEnd	back to summary
public int getResultEnd() Get one past the range of the result that `getSourceCommit()` has been blamed for providing Returns:int one past the range of the result that `getSourceCommit()` has been blamed for providing. Line numbers use 0 based indexing. Because a source cannot be blamed for an empty region of the result, `getResultEnd()` is always at least one larger than `getResultStart()`.

public int getResultEnd()

Get one past the range of the result that getSourceCommit() has been blamed for providing

Returns:int: one past the range of the result that getSourceCommit() has been blamed for providing. Line numbers use 0 based indexing. Because a source cannot be blamed for an empty region of the result, getResultEnd() is always at least one larger than getResultStart().

getResultPath	back to summary
public String getResultPath() Get result path Returns:String path file path being processed

getResultPath

back to summary

public String getResultPath()

Get result path

Returns:String: path file path being processed

getResultStart back to summary

getResultStart	back to summary
public int getResultStart() Get first line of the result that `getSourceCommit()` has been blamed for providing Returns:int first line of the result that `getSourceCommit()` has been blamed for providing. Line numbers use 0 based indexing.

public int getResultStart()

Get first line of the result that getSourceCommit() has been blamed for providing

Returns:int: first line of the result that getSourceCommit() has been blamed for providing. Line numbers use 0 based indexing.

getSourceAuthor	back to summary
public PersonIdent getSourceAuthor() Get source author Returns:PersonIdent current author being blamed

getSourceAuthor

back to summary

public PersonIdent getSourceAuthor()

Get source author

Returns:PersonIdent: current author being blamed

getSourceCommit	back to summary
public RevCommit getSourceCommit() Get the revision blamed for the current region. The source commit may be null if the line was blamed to an uncommitted revision, such as the working tree copy, or during a reverse blame if the line survives to the end revision (e.g. the branch tip). Returns:RevCommit current revision being blamed.

getSourceCommit

back to summary

public RevCommit getSourceCommit()

Get the revision blamed for the current region.

The source commit may be null if the line was blamed to an uncommitted revision, such as the working tree copy, or during a reverse blame if the line survives to the end revision (e.g. the branch tip).

Returns:RevCommit: current revision being blamed.

getSourceCommitter	back to summary
public PersonIdent getSourceCommitter() Get source committer Returns:PersonIdent current committer being blamed

getSourceCommitter

back to summary

public PersonIdent getSourceCommitter()

Get source committer

Returns:PersonIdent: current committer being blamed

getSourceContents back to summary

getSourceContents	back to summary
public RawText getSourceContents() Get complete contents of the source file blamed for the current output region Returns:RawText complete contents of the source file blamed for the current output region. This is the contents of `getSourcePath()` within `getSourceCommit()`. The source contents is temporarily available as an artifact of the blame algorithm. Most applications will want the result contents for display to users.

public RawText getSourceContents()

Get complete contents of the source file blamed for the current output region

Returns:RawText: complete contents of the source file blamed for the current output region. This is the contents of getSourcePath() within getSourceCommit(). The source contents is temporarily available as an artifact of the blame algorithm. Most applications will want the result contents for display to users.

getSourceEnd back to summary

getSourceEnd	back to summary
public int getSourceEnd() Get one past the range of the source data that has been blamed for the current region This value is not reliable when the generator is reusing cached values. Cache doesn't keep the source lines, the returned value is based on the result and can be off if the region moved in previous commits. Returns:int one past the range of the source data that has been blamed for the current region. This is line number of where the region was added during `getSourceCommit()` in file `getSourcePath()`.

public int getSourceEnd()

Get one past the range of the source data that has been blamed for the current region

This value is not reliable when the generator is reusing cached values. Cache doesn't keep the source lines, the returned value is based on the result and can be off if the region moved in previous commits.

Returns:int: one past the range of the source data that has been blamed for the current region. This is line number of where the region was added during getSourceCommit() in file getSourcePath().

getSourcePath	back to summary
public String getSourcePath() Get source path Returns:String path of the file being blamed

getSourcePath

back to summary

public String getSourcePath()

Get source path

Returns:String: path of the file being blamed

getSourceStart back to summary

getSourceStart	back to summary
public int getSourceStart() Get first line of the source data that has been blamed for the current region This value is not reliable when the generator is reusing cached values. Cache doesn't keep the source lines, the returned value is based on the result and can be off if the region moved in previous commits. Returns:int first line of the source data that has been blamed for the current region. This is line number of where the region was added during `getSourceCommit()` in file `getSourcePath()`.

public int getSourceStart()

Get first line of the source data that has been blamed for the current region

Returns:int: first line of the source data that has been blamed for the current region. This is line number of where the region was added during getSourceCommit() in file getSourcePath().

getStats	back to summary
public BlameGenerator.Stats getStats() Stats about this generator Returns:BlameGenerator.Stats the stats of this generator Since 7.2

getStats

back to summary

public BlameGenerator.Stats getStats()

Stats about this generator

Returns:BlameGenerator.Stats: the stats of this generator
Since: 7.2

initRevPool	back to summary
private void initRevPool(boolean reverse)

isFile	back to summary
private static final boolean isFile(int rawMode)

isRename	back to summary
private static boolean isRename(DiffEntry ent)

newFlag

back to summary

public RevFlag newFlag(String name)

Allocate a new RevFlag for use by the caller.

Parameters

name:String: unique name of the flag in the blame context.

Returns:RevFlag

the newly allocated flag.

Since

3.4

next back to summary

public boolean next() throws IOException

Step the blame algorithm one iteration.

Returns:boolean

true if the generator has found a region's source. The getSource* and getResultStart(), getResultEnd() methods can be used to inspect the region found. False if there are no more regions to describe.

Exceptions

IOException:: repository cannot be read.

pop	back to summary
private Candidate pop()

prepareHead back to summary

public BlameGenerator prepareHead() throws NoHeadException, IOException

Pushes HEAD, index, and working tree as appropriate for blaming the file given in the constructor BlameGenerator(Repository, String) against HEAD. Includes special handling in case the file is in conflict state from an unresolved merge conflict.

Returns:BlameGenerator

this

Exceptions

NoHeadException:: if the repository has no HEAD
IOException:: if an error occurs

Since

5.6

processMerge	back to summary
private boolean processMerge(Candidate n) throws IOException

processOne	back to summary
private boolean processOne(Candidate n) throws IOException

push back to summary

public BlameGenerator push(String description, byte[] contents) throws IOException

Push a candidate blob onto the generator's traversal stack.

Candidates should be pushed in history order from oldest-to-newest. Applications should push the starting commit first, then the index revision (if the index is interesting), and finally the working tree copy (if the working tree is interesting).

Parameters

description:String: description of the blob revision, such as "Working Tree".
contents:byte[]: contents of the file.

Returns:BlameGenerator

this

Exceptions

IOException:: the repository cannot be read.

push back to summary

public BlameGenerator push(String description, RawText contents) throws IOException

Push a candidate blob onto the generator's traversal stack.

Parameters

description:String: description of the blob revision, such as "Working Tree".
contents:RawText: contents of the file.

Returns:BlameGenerator

this

Exceptions

IOException:: the repository cannot be read.

push back to summary

public BlameGenerator push(String description, AnyObjectId id) throws IOException

Push a candidate object onto the generator's traversal stack.

Parameters

description:String: description of the blob revision, such as "Working Tree".
id:AnyObjectId: may be a commit or a blob.

Returns:BlameGenerator

this

Exceptions

IOException:: the repository cannot be read.

push	back to summary
private void push(Candidate.BlobCandidate toInsert)

push	back to summary
private void push(Candidate toInsert)

result	back to summary
private boolean result(Candidate n) throws IOException

reverse back to summary

public BlameGenerator reverse(AnyObjectId start, AnyObjectId end) throws IOException

Configure the generator to compute reverse blame (history of deletes).

This method is expensive as it immediately runs a RevWalk over the history spanning the expression start..end (end being more recent than start) and then performs the equivalent operation as push(String, AnyObjectId) to begin blame traversal from the commit named by start walking forwards through history until end blaming line deletions.

A reverse blame may produce multiple sources for the same result line, each of these is a descendant commit that removed the line, typically this occurs when the same deletion appears in multiple side branches such as due to a cherry-pick. Applications relying on reverse should use org.eclipse.jgit.blame.BlameResult as it filters these duplicate sources and only remembers the first (oldest) deletion.

Parameters

start:AnyObjectId: oldest commit to traverse from. The result file will be loaded from this commit's tree.
end:AnyObjectId: most recent commit to stop traversal at. Usually an active branch tip, tag, or HEAD.

Returns:BlameGenerator

this

Exceptions

IOException:: the repository cannot be read.

reverse back to summary

public BlameGenerator reverse(AnyObjectId start, Collection<? extends ObjectId> end) throws IOException

Configure the generator to compute reverse blame (history of deletes).

Parameters

start:AnyObjectId: oldest commit to traverse from. The result file will be loaded from this commit's tree.
end:Collection<? extends ObjectId>: most recent commits to stop traversal at. Usually an active branch tip, tag, or HEAD.

Returns:BlameGenerator

this

Exceptions

IOException:: the repository cannot be read.

reverseResult	back to summary
private boolean reverseResult(Candidate parent, Candidate source) throws IOException

setDiffAlgorithm back to summary

public BlameGenerator setDiffAlgorithm(DiffAlgorithm algorithm)

Difference algorithm to use when comparing revisions.

Parameters

algorithm:DiffAlgorithm: a org.eclipse.jgit.diff.DiffAlgorithm

Returns:BlameGenerator

this

setFollowFileRenames back to summary

public BlameGenerator setFollowFileRenames(boolean follow)

Enable (or disable) following file renames, on by default.

If true renames are followed using the standard FollowFilter behavior used by RevWalk (which matches git log --follow in the C implementation). This is not the same as copy/move detection as implemented by the C implementation's of git blame -M -C.

Parameters

follow:boolean: enable following.

Returns:BlameGenerator

this

setTextComparator back to summary

public BlameGenerator setTextComparator(RawTextComparator comparator)

Text comparator to use when comparing revisions.

Parameters

comparator:RawTextComparator: a org.eclipse.jgit.diff.RawTextComparator

Returns:BlameGenerator

this

setUseCache

back to summary

public void setUseCache(boolean useCache)

Enable/disable the use of cache (if present). Enabled by default.

If caller need source line numbers, the generator cannot use the cache (source lines are not there). Use this method to disable the cache in that case.

Parameters

useCache:boolean: should this generator use the cache.

Since

7.2

split	back to summary
private boolean split(Candidate parent, Candidate source) throws IOException

splitBlameWithParent	back to summary
private boolean splitBlameWithParent(Candidate n, RevCommit parent) throws IOException

public Class BlameGenerator

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public Class BlameGenerator.Stats

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

Modifier and Type	Field and Description
private boolean	cacheHit
private int	candidatesVisited Candidates taken from the queue

Modifier and Type	Method and Description
public int	Returns: number of candidates taken from the queue getCandidatesVisited() Number of candidates taken from the queue The generator could signal it's done without exhausting all candidates if there is no more remaining lines or the last visited candidate is found in the cache.
public boolean	Returns: true if we used results from the cache isCacheHit() The generator found a blamed version in the cache