org.eclipse.jgit.blame
Class BlameGenerator

java.lang.Object
  extended by org.eclipse.jgit.blame.BlameGenerator

public class BlameGenerator
extends Object

Generate author information for lines based on introduction to the file.

Applications that want a simple one-shot computation of blame for a file should use computeBlameResult() to prepare the entire result in one method call. This may block for significant time as the history of the repository must be traversed until information is gathered for every line.

Applications that want more incremental update behavior may use either the raw next() streaming approach supported by this class, or construct a BlameResult using BlameResult.create(BlameGenerator) and incrementally construct the result with BlameResult.computeNext().

This class is not thread-safe.

An instance of BlameGenerator can only be used once. To blame multiple files the application must create a new BlameGenerator.

During blame processing there are two files involved:

The blame algorithm is implemented by initially assigning responsibility for all lines of the result to the starting commit. A difference against the commit's ancestor is computed, and responsibility is passed to the ancestor commit for any lines that are common. The starting commit is blamed only for the lines that do not appear in the ancestor, if any. The loop repeats using the ancestor, until there are no more lines to acquire information on, or the file's creation point is discovered in history.


Constructor Summary
BlameGenerator(Repository repository, String path)
          Create a blame generator for the repository and path
 
Method Summary
 BlameResult computeBlameResult()
          Execute the generator in a blocking fashion until all data is ready.
 int getRegionLength()
           
 RenameDetector getRenameDetector()
          Obtain the RenameDetector if setFollowFileRenames(true).
 int getRenameScore()
           
 Repository getRepository()
           
 RawText getResultContents()
           
 int getResultEnd()
           
 String getResultPath()
           
 int getResultStart()
           
 PersonIdent getSourceAuthor()
           
 RevCommit getSourceCommit()
          Get the revision blamed for the current region.
 PersonIdent getSourceCommitter()
           
 RawText getSourceContents()
           
 int getSourceEnd()
           
 String getSourcePath()
           
 int getSourceStart()
           
 boolean next()
          Step the blame algorithm one iteration.
 BlameGenerator push(String description, AnyObjectId id)
          Push a candidate object onto the generator's traversal stack.
 BlameGenerator push(String description, byte[] contents)
          Push a candidate blob onto the generator's traversal stack.
 BlameGenerator push(String description, RawText contents)
          Push a candidate blob onto the generator's traversal stack.
 void release()
          Release the current blame session.
 BlameGenerator reverse(AnyObjectId start, AnyObjectId end)
          Configure the generator to compute reverse blame (history of deletes).
 BlameGenerator reverse(AnyObjectId start, Collection<? extends ObjectId> end)
          Configure the generator to compute reverse blame (history of deletes).
 BlameGenerator setDiffAlgorithm(DiffAlgorithm algorithm)
          Difference algorithm to use when comparing revisions.
 BlameGenerator setFollowFileRenames(boolean follow)
          Enable (or disable) following file renames, on by default.
 BlameGenerator setTextComparator(RawTextComparator comparator)
          Text comparator to use when comparing revisions.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BlameGenerator

public BlameGenerator(Repository repository,
                      String path)
Create a blame generator for the repository and path

Parameters:
repository - repository to access revision data from.
path - initial path of the file to start scanning.
Method Detail

getRepository

public Repository getRepository()
Returns:
repository being scanned for revision history.

getResultPath

public String getResultPath()
Returns:
path file path being processed.

setDiffAlgorithm

public BlameGenerator setDiffAlgorithm(DiffAlgorithm algorithm)
Difference algorithm to use when comparing revisions.

Parameters:
algorithm -
Returns:
this

setTextComparator

public BlameGenerator setTextComparator(RawTextComparator comparator)
Text comparator to use when comparing revisions.

Parameters:
comparator -
Returns:
this

setFollowFileRenames

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 - enable following.
Returns:
this

getRenameDetector

public RenameDetector getRenameDetector()
Obtain the RenameDetector if setFollowFileRenames(true).

Returns:
the rename detector, allowing the application to configure its settings for rename score and breaking behavior.

push

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 - description of the blob revision, such as "Working Tree".
contents - contents of the file.
Returns:
this
Throws:
IOException - the repository cannot be read.

push

public BlameGenerator push(String description,
                           RawText 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 - description of the blob revision, such as "Working Tree".
contents - contents of the file.
Returns:
this
Throws:
IOException - the repository cannot be read.

push

public BlameGenerator push(String description,
                           AnyObjectId id)
                    throws IOException
Push a candidate object 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 - description of the blob revision, such as "Working Tree".
id - may be a commit or a blob.
Returns:
this
Throws:
IOException - the repository cannot be read.

reverse

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 BlameResult as it filters these duplicate sources and only remembers the first (oldest) deletion.

Parameters:
start - oldest commit to traverse from. The result file will be loaded from this commit's tree.
end - most recent commit to stop traversal at. Usually an active branch tip, tag, or HEAD.
Returns:
this
Throws:
IOException - the repository cannot be read.

reverse

public BlameGenerator reverse(AnyObjectId start,
                              Collection<? extends ObjectId> 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 BlameResult as it filters these duplicate sources and only remembers the first (oldest) deletion.

Parameters:
start - oldest commit to traverse from. The result file will be loaded from this commit's tree.
end - most recent commits to stop traversal at. Usually an active branch tip, tag, or HEAD.
Returns:
this
Throws:
IOException - the repository cannot be read.

computeBlameResult

public BlameResult computeBlameResult()
                               throws IOException
Execute the generator in a blocking fashion until all data is ready.

Returns:
the complete result. Null if no file exists for the given path.
Throws:
IOException - the repository cannot be read.

next

public boolean next()
             throws IOException
Step the blame algorithm one iteration.

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.
Throws:
IOException - repository cannot be read.

getSourceCommit

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:
current revision being blamed.

getSourceAuthor

public PersonIdent getSourceAuthor()
Returns:
current author being blamed.

getSourceCommitter

public PersonIdent getSourceCommitter()
Returns:
current committer being blamed.

getSourcePath

public String getSourcePath()
Returns:
path of the file being blamed.

getRenameScore

public int getRenameScore()
Returns:
rename score if a rename occurred in getSourceCommit().

getSourceStart

public int getSourceStart()
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().

getSourceEnd

public int getSourceEnd()
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().

getResultStart

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

getResultEnd

public int getResultEnd()
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().

getRegionLength

public int getRegionLength()
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().

getSourceContents

public RawText getSourceContents()
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.

getResultContents

public RawText getResultContents()
                          throws IOException
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.
Throws:
IOException - repository cannot be read.
IllegalStateException - next() has already been invoked.

release

public void release()
Release the current blame session.



Copyright © 2012. All Rights Reserved.