org.eclipse.jgit.diff

## Class DiffFormatter

- java.lang.Object
- - org.eclipse.jgit.diff.DiffFormatter

Direct Known Subclasses:
  PatchIdDiffFormatter

    public class DiffFormatter
    extends Object

Format a Git style patch script.

### Constructor Summary

Constructors
Constructor and Description
`DiffFormatter(OutputStream out)` Create a new formatter with a default level of context.

### Method Summary

Methods
`void` `flush()` Flush the underlying output stream of this formatter.
`void` `format(AbstractTreeIterator a, AbstractTreeIterator b)` Format the differences between two trees.
`void` `format(AnyObjectId a, AnyObjectId b)` Format the differences between two trees.
`void` `format(DiffEntry ent)` Format a patch script for one file entry.
`void` `format(EditList edits, RawText a, RawText b)` Formats a list of edits in unified diff format
`void` `format(FileHeader head, RawText a, RawText b)` Format a patch script, reusing a previously parsed FileHeader.
`void` `format(List<? extends DiffEntry> entries)` Format a patch script from a list of difference entries.
`void` `format(RevTree a, RevTree b)` Format the differences between two trees.
`protected void` `formatGitDiffFirstHeaderLine(ByteArrayOutputStream o, DiffEntry.ChangeType type, String oldPath, String newPath)` Output the first header line
`protected void` `formatIndexLine(OutputStream o, DiffEntry ent)`
`String` `getNewPrefix()` Get the prefix applied in front of new file paths.
`String` `getOldPrefix()` Get the prefix applied in front of old file paths.
`protected OutputStream` `getOutputStream()`
`TreeFilter` `getPathFilter()`
`RenameDetector` `getRenameDetector()`
`boolean` `isDetectRenames()`
`void` `release()` Release the internal ObjectReader state.
`List<DiffEntry>` `scan(AbstractTreeIterator a, AbstractTreeIterator b)` Determine the differences between two trees.
`List<DiffEntry>` `scan(AnyObjectId a, AnyObjectId b)` Determine the differences between two trees.
`List<DiffEntry>` `scan(RevTree a, RevTree b)` Determine the differences between two trees.
`void` `setAbbreviationLength(int count)` Change the number of digits to show in an ObjectId.
`void` `setBinaryFileThreshold(int threshold)` Set maximum file size for text files.
`void` `setContext(int lineCount)` Change the number of lines of context to display.
`void` `setDetectRenames(boolean on)` Enable or disable rename detection.
`void` `setDiffAlgorithm(DiffAlgorithm alg)` Set the algorithm that constructs difference output.
`void` `setDiffComparator(RawTextComparator cmp)` Set the line equivalence function for text file differences.
`void` `setNewPrefix(String prefix)` Set the prefix applied in front of new file paths.
`void` `setOldPrefix(String prefix)` Set the prefix applied in front of old file paths.
`void` `setPathFilter(TreeFilter filter)` Set the filter to produce only specific paths.
`void` `setProgressMonitor(ProgressMonitor pm)` Set the progress monitor for long running rename detection.
`void` `setRepository(Repository repository)` Set the repository the formatter can load object contents from.
`FileHeader` `toFileHeader(DiffEntry ent)` Creates a `FileHeader` representing the given `DiffEntry`
`protected void` `writeAddedLine(RawText text, int line)` Output an added line.
`protected void` `writeContextLine(RawText text, int line)` Output a line of context (unmodified line).
`protected void` `writeHunkHeader(int aStartLine, int aEndLine, int bStartLine, int bEndLine)` Output a hunk header
`protected void` `writeLine(char prefix, RawText text, int cur)` Write a standard patch script line.
`protected void` `writeRemovedLine(RawText text, int line)` Output a removed line

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### DiffFormatter

    public DiffFormatter(OutputStream out)

Create a new formatter with a default level of context.

Parameters:
  `out` - the stream the formatter will write line data to. This stream should have buffering arranged by the caller, as many small writes are performed to it.

### Method Detail

#### getOutputStream

    protected OutputStream getOutputStream()

Returns:
  the stream we are outputting data to.

#### setRepository

    public void setRepository(Repository repository)

Set the repository the formatter can load object contents from. Once a repository has been set, the formatter must be released to ensure the internal ObjectReader is able to release its resources.

Parameters:
  `repository` - source repository holding referenced objects.

#### setContext

    public void setContext(int lineCount)

Change the number of lines of context to display.

Parameters:
  `lineCount` - number of lines of context to see before the first modification and after the last modification within a hunk of the modified file.

#### setAbbreviationLength

    public void setAbbreviationLength(int count)

Change the number of digits to show in an ObjectId.

Parameters:
  `count` - number of digits to show in an ObjectId.

#### setDiffAlgorithm

    public void setDiffAlgorithm(DiffAlgorithm alg)

Set the algorithm that constructs difference output.

Parameters:
  `alg` - the algorithm to produce text file differences.
See Also:
  `HistogramDiff`

#### setDiffComparator

    public void setDiffComparator(RawTextComparator cmp)

Set the line equivalence function for text file differences.

Parameters:
  `cmp` - The equivalence function used to determine if two lines of text are identical. The function can be changed to ignore various types of whitespace.
See Also:
  `RawTextComparator.DEFAULT`, `RawTextComparator.WS_IGNORE_ALL`, `RawTextComparator.WS_IGNORE_CHANGE`, `RawTextComparator.WS_IGNORE_LEADING`, `RawTextComparator.WS_IGNORE_TRAILING`

#### setBinaryFileThreshold

    public void setBinaryFileThreshold(int threshold)

Set maximum file size for text files. Files larger than this size will be treated as though they are binary and not text. Default is .

Parameters:
  `threshold` - the limit, in bytes. Files larger than this size will be assumed to be binary, even if they aren't.

#### setOldPrefix

    public void setOldPrefix(String prefix)

Set the prefix applied in front of old file paths.

Parameters:
  `prefix` - the prefix in front of old paths. Typically this is the standard string `"a/"`, but may be any prefix desired by the caller. Must not be null. Use the empty string to have no prefix at all.

#### getOldPrefix

    public String getOldPrefix()

Get the prefix applied in front of old file paths.

Returns:
  the prefix
Since:
  2.0

#### setNewPrefix

    public void setNewPrefix(String prefix)

Set the prefix applied in front of new file paths.

Parameters:
  `prefix` - the prefix in front of new paths. Typically this is the standard string `"b/"`, but may be any prefix desired by the caller. Must not be null. Use the empty string to have no prefix at all.

#### getNewPrefix

    public String getNewPrefix()

Get the prefix applied in front of new file paths.

Returns:
  the prefix
Since:
  2.0

#### isDetectRenames

    public boolean isDetectRenames()

Returns:
  true if rename detection is enabled.

#### setDetectRenames

    public void setDetectRenames(boolean on)

Enable or disable rename detection. Before enabling rename detection the repository must be set with `setRepository(Repository)`. Once enabled the detector can be configured away from its defaults by obtaining the instance directly from `getRenameDetector()` and invoking configuration.

Parameters:
  `on` - if rename detection should be enabled.

#### getRenameDetector

    public RenameDetector getRenameDetector()

Returns:
  the rename detector if rename detection is enabled.

#### setProgressMonitor

    public void setProgressMonitor(ProgressMonitor pm)

Set the progress monitor for long running rename detection.

Parameters:
  `pm` - progress monitor to receive rename detection status through.

#### setPathFilter

    public void setPathFilter(TreeFilter filter)

Set the filter to produce only specific paths. If the filter is an instance of `FollowFilter`, the filter path will be updated during successive scan or format invocations. The updated path can be obtained from `getPathFilter()`.

Parameters:
  `filter` - the tree filter to apply.

#### getPathFilter

    public TreeFilter getPathFilter()

Returns:
  the current path filter.

#### flush

    public void flush()
               throws IOException

Flush the underlying output stream of this formatter.

Throws:
  `IOException` - the stream's own flush method threw an exception.

#### release

    public void release()

Release the internal ObjectReader state.

#### scan

    public List<DiffEntry> scan(AnyObjectId a,
                       AnyObjectId b)
                         throws IOException

Determine the differences between two trees. No output is created, instead only the file paths that are different are returned. Callers may choose to format these paths themselves, or convert them into `FileHeader` instances with a complete edit list by calling `toFileHeader(DiffEntry)`.

Parameters:
  `a` - the old (or previous) side.
  `b` - the new (or updated) side.
Returns:
  the paths that are different.
Throws:
  `IOException` - trees cannot be read or file contents cannot be read.

#### scan

    public List<DiffEntry> scan(RevTree a,
                       RevTree b)
                         throws IOException

Determine the differences between two trees. No output is created, instead only the file paths that are different are returned. Callers may choose to format these paths themselves, or convert them into `FileHeader` instances with a complete edit list by calling `toFileHeader(DiffEntry)`.

Parameters:
  `a` - the old (or previous) side.
  `b` - the new (or updated) side.
Returns:
  the paths that are different.
Throws:
  `IOException` - trees cannot be read or file contents cannot be read.

#### scan

    public List<DiffEntry> scan(AbstractTreeIterator a,
                       AbstractTreeIterator b)
                         throws IOException

Determine the differences between two trees. No output is created, instead only the file paths that are different are returned. Callers may choose to format these paths themselves, or convert them into `FileHeader` instances with a complete edit list by calling `toFileHeader(DiffEntry)`.

Parameters:
  `a` - the old (or previous) side.
  `b` - the new (or updated) side.
Returns:
  the paths that are different.
Throws:
  `IOException` - trees cannot be read or file contents cannot be read.

#### format

    public void format(AnyObjectId a,
              AnyObjectId b)
                throws IOException

Format the differences between two trees. The patch is expressed as instructions to modify `a` to make it `b`.

Parameters:
  `a` - the old (or previous) side.
  `b` - the new (or updated) side.
Throws:
  `IOException` - trees cannot be read, file contents cannot be read, or the patch cannot be output.

#### format

    public void format(RevTree a,
              RevTree b)
                throws IOException

Format the differences between two trees. The patch is expressed as instructions to modify `a` to make it `b`.

Parameters:
  `a` - the old (or previous) side.
  `b` - the new (or updated) side.
Throws:
  `IOException` - trees cannot be read, file contents cannot be read, or the patch cannot be output.

#### format

    public void format(AbstractTreeIterator a,
              AbstractTreeIterator b)
                throws IOException

Format the differences between two trees. The patch is expressed as instructions to modify `a` to make it `b`.

Parameters:
  `a` - the old (or previous) side.
  `b` - the new (or updated) side.
Throws:
  `IOException` - trees cannot be read, file contents cannot be read, or the patch cannot be output.

#### format

    public void format(List<? extends DiffEntry> entries)
                throws IOException

Format a patch script from a list of difference entries. Requires `scan(AbstractTreeIterator, AbstractTreeIterator)` to have been called first.

Parameters:
  `entries` - entries describing the affected files.
Throws:
  `IOException` - a file's content cannot be read, or the output stream cannot be written to.

#### format

    public void format(DiffEntry ent)
                throws IOException

Format a patch script for one file entry.

Parameters:
  `ent` - the entry to be formatted.
Throws:
  `IOException` - a file's content cannot be read, or the output stream cannot be written to.

#### format

    public void format(FileHeader head,
              RawText a,
              RawText b)
                throws IOException

Format a patch script, reusing a previously parsed FileHeader.

This formatter is primarily useful for editing an existing patch script to increase or reduce the number of lines of context within the script. All header lines are reused as-is from the supplied FileHeader.

Parameters:
  `head` - existing file header containing the header lines to copy.
  `a` - text source for the pre-image version of the content. This must match the content of `DiffEntry.getOldId()`.
  `b` - text source for the post-image version of the content. This must match the content of `DiffEntry.getNewId()`.
Throws:
  `IOException` - writing to the supplied stream failed.

#### format

    public void format(EditList edits,
              RawText a,
              RawText b)
                throws IOException

Formats a list of edits in unified diff format

Parameters:
  `edits` - some differences which have been calculated between A and B
  `a` - the text A which was compared
  `b` - the text B which was compared
Throws:
  `IOException`

#### writeContextLine

    protected void writeContextLine(RawText text,
                        int line)
                             throws IOException

Output a line of context (unmodified line).

Parameters:
  `text` - RawText for accessing raw data
  `line` - the line number within text
Throws:
  `IOException`

#### writeAddedLine

    protected void writeAddedLine(RawText text,
                      int line)
                           throws IOException

Output an added line.

Parameters:
  `text` - RawText for accessing raw data
  `line` - the line number within text
Throws:
  `IOException`

#### writeRemovedLine

    protected void writeRemovedLine(RawText text,
                        int line)
                             throws IOException

Output a removed line

Parameters:
  `text` - RawText for accessing raw data
  `line` - the line number within text
Throws:
  `IOException`

#### writeHunkHeader

    protected void writeHunkHeader(int aStartLine,
                       int aEndLine,
                       int bStartLine,
                       int bEndLine)
                            throws IOException

Output a hunk header

Parameters:
  `aStartLine` - within first source
  `aEndLine` - within first source
  `bStartLine` - within second source
  `bEndLine` - within second source
Throws:
  `IOException`

#### writeLine

    protected void writeLine(char prefix,
                 RawText text,
                 int cur)
                      throws IOException

Write a standard patch script line.

Parameters:
  `prefix` - prefix before the line, typically '-', '+', ' '.
  `text` - the text object to obtain the line from.
  `cur` - line number to output.
Throws:
  `IOException` - the stream threw an exception while writing to it.

#### toFileHeader

    public FileHeader toFileHeader(DiffEntry ent)
                            throws IOException,
                                   CorruptObjectException,
                                   MissingObjectException

Creates a `FileHeader` representing the given `DiffEntry`

This method does not use the OutputStream associated with this DiffFormatter instance. It is therefore safe to instantiate this DiffFormatter instance with a `DisabledOutputStream` if this method is the only one that will be used.

Parameters:
  `ent` - the DiffEntry to create the FileHeader for
Returns:
  a FileHeader representing the DiffEntry. The FileHeader's buffer will contain only the header of the diff output. It will also contain one `HunkHeader`.
Throws:
  `IOException` - the stream threw an exception while writing to it, or one of the blobs referenced by the DiffEntry could not be read.
  `CorruptObjectException` - one of the blobs referenced by the DiffEntry is corrupt.
  `MissingObjectException` - one of the blobs referenced by the DiffEntry is missing.

#### formatGitDiffFirstHeaderLine

    protected void formatGitDiffFirstHeaderLine(ByteArrayOutputStream o,
                                    DiffEntry.ChangeType type,
                                    String oldPath,
                                    String newPath)
                                         throws IOException

Output the first header line

Parameters:
  `o` - The stream the formatter will write the first header line to
  `type` - The `DiffEntry.ChangeType`
  `oldPath` - old path to the file
  `newPath` - new path to the file
Throws:
  `IOException` - the stream threw an exception while writing to it.

#### formatIndexLine

    protected void formatIndexLine(OutputStream o,
                       DiffEntry ent)
                            throws IOException

Parameters:
  `o` - the stream the formatter will write line data to
  `ent` - the DiffEntry to create the FileHeader for
Throws:
  `IOException` - writing to the supplied stream failed.