Developer tools · Text comparison
How to Read a Unified Diff: Hunk Headers, Context Lines and +/- Markers
· Background
text-diff patches developer-workflow
Decodes the unified diff format line by line, from file headers and @@ hunk ranges to context lines and change markers, so patches from any tool make sense.
A wall of pluses, minuses and @@ symbols — opens with the first encounter with a patch in an email or pull request
A downloaded `changes.patch` begins with punctuation that resembles familiar diff output, but its exact structure matters. ToolAcre writes two labels and then every comparison row with a one-character marker. Reading what exists is safer than mentally supplying fields from another patch format.
Open the file in a plain-text editor. The first two lines identify the left and right labels supplied by the UI as `original` and `changed`. Subsequent lines reconstruct the compared texts through context, removal and addition markers.
The file header lines — explains the --- and +++ lines, the paths, and the a/ and b/ prefixes tools add
The header is `--- original` followed by `+++ changed`. In other tools those prefixes may sit within a richer patch grammar, but this exporter adds no timestamps, paths or metadata. The labels describe sides, not files proven to exist on disk.
That distinction matters because Text diff accepts pasted strings rather than file objects. Download creates a local textual report after comparison. Treating the labels as repository paths or revision identifiers would attribute provenance that the UI never collected.
Hunk headers explained — decodes @@ -12,7 +12,8 @@ as start line and line count for each side
There are no lines beginning with `@@` in `toUnifiedText`. The function maps directly over all rows after the two labels. Consequently this output has no hunk ranges to decode and no start-line/count pairs embedded in the downloaded text.
Line numbers remain available in the rendered browser view, where rows carry left and right positions. The export chooses a simpler representation. If a downstream program requires standards-complete unified hunks, verify compatibility rather than assuming the `.patch` extension supplies missing syntax.
ToolAcre emits no @@ hunk headers, so there are none to decode
A leading space marks an unchanged row, minus marks a left removal, and plus marks a right addition. The UI can collapse long equal runs visually, but `lastDiff` retains the complete result and download serializes all rows. No skip marker enters the patch string.
The outline mentioned three context lines as a default. Three is used by the visual collapse call, not by the export. Conflating those paths would understate the downloaded content. Presentation and serialization share rows but apply different transformations.
The download marks every row and does not use a three-line context default
Compare left `a b` with right `a c`. The exported lines are the two labels, then space-a, minus-b and plus-c. Reading top to bottom says that `a` survives, `b` leaves the original and `c` enters the changed side.
A modification is therefore represented as adjacent removal and addition when alignment places them together. The format does not name it “modified.” If repeated lines allow another alignment, the sequence can look different while still accounting for each input row.
Worked example: read the full patch-shaped stream that ToolAcre actually exports
Normal, context and complete unified diff formats have their own specifications and histories, but those are not implemented or documented by the source set used here. This article does not claim why one format became popular or list fields ToolAcre does not emit.
Use a version-control command when another tool must apply the patch. ToolAcre’s download is useful as a portable review artifact, yet the repository contains no patch parser or apply function proving it can round-trip through arbitrary patch consumers.
Complete unified, context and normal format comparisons require external sources
Binary patches, rename headers, mode changes and application are outside this route. The text contains no object identifiers or common ancestor. It cannot represent a repository operation simply because its markers look familiar.
The exporter also reflects active comparison options. A row considered equal after case or whitespace normalization carries the original left text only, so the patch-shaped document is not a byte-for-byte reconstruction of both inputs under loose matching.
Takeaway: a diff is a compressed story — summarises reading order and notes how ToolAcre's Text comparison shows the same kinds of changes as highlighted lines for quick review
Read the two labels first, then interpret every prefixed row in order. If you need rendered line numbers, return to the browser view. If you need standards-complete hunks, generate them with a tool that documents that contract.
ToolAcre provides a compact way to take the comparison outside the page without claiming to implement every patch feature. That narrower name—patch-shaped output—keeps expectations aligned with the exact function and avoids a false promise of application compatibility.