lite-diff

A simplified text format for describing file changes, inspired by the classic unified diff format and designed so that a patch written by an LLM agent either applies exactly as intended or fails with a clear error.

Specification

📄 Read the full specification → SPEC.md (v1.1, October 2026)

• Writing patches? Start with Appendix A — Writing lite-diff (for patch generators): the rules on one screen, intended as prompt material.
• Implementing? The conformance corpus (271 cases) and the reference implementation (Python, standard library only) are in this repository.
• Coming from v1.0? See §12 Changes from v1.0 and its migration notes. The v1.0 text is the initial commit of this repository.

Overview

lite-diff is designed to be:

• Predictable — position matching by content, not line numbers; an ambiguous anchor is an error, never a guess
• Easy to read — minimal syntax, familiar to anyone who knows unified diff
• Easy to implement — a normative parser state machine, a conformance corpus, well-defined error codes
• AI-friendly — tolerant of what LLM output actually looks like (blank context lines, stripped trailing whitespace, a Markdown fence), loud about what it gets wrong (wrong indentation, forgotten prefixes, misplaced hunks)

Quick Example

--- hello.txt
+++ hello.txt
@@
-Hello, World
+Hello, lite-diff

Key Features

Feature	Description
Content-based matching	Finds the position by context; numeric ranges are optional and only break ties
Loud failures	Ambiguous anchor → E414, no match → E410 with a diagnosis (indentation, tabs vs spaces, already applied), wrong hunk order → E413
@@ BOF / @@ EOF	Insert at file beginning or end
@@ <scope>	Start the search at the first line containing a text (e.g. @@ def main()
Boundary blocks ...	Delete a range between two markers
Blank lines as context	An empty line in a hunk body is the context of an empty line
File operations	Create, delete, rename, copy (rename requires an explicit rename from/rename to)
Global and block options	--strict, --check, --first-match, --apply-all-matches, --indent-shift, --lenient, --skip-applied, --ignore-*, --strip N, --eol; option <name> per block
Atomic application	All-or-nothing per document; a machine-readable result with per-hunk status and applied ranges (JSON Schema in Appendix B)
Version marker	--lite-diff 1.1; --lite-diff 1.0 selects a compatibility profile for existing v1.0 users

File Operations

# Create a new file
--- /dev/null
+++ new-file.txt
@@
+First line
+Second line

# Delete a file
--- old-file.txt
+++ /dev/null

# Rename with modifications
rename from old.txt
rename to new.txt
--- old.txt
+++ new.txt
@@
-old content
+new content

Compatibility

lite-diff accepts standard unified diff headers (diff --git, ---/+++, @@ -a,m +b,n @@) and extended Git headers. Patches generated by git diff apply unchanged: on a live repository's history of 76 commits every patch applied with the same result as git apply, with and without --strict.

Differences from git apply, by design:

• numeric ranges in hunk headers are never required and are used only to resolve an ambiguous anchor;
• an anchor that matches more than once is an error unless the header, --first-match or --apply-all-matches resolves it;
• a differing ---/+++ pair without rename from/rename to is an error, not a silent move;
• trailing whitespace is never significant in matching, and a blank line is the context of an empty line;
• the final newline follows git semantics: a hunk that reaches the end of file decides through \ No newline at end of file on its new side.

See §9.2 Interoperability Notes in the specification.

Repository Layout

Path	Contents
SPEC.md	The specification, v1.1
tests/	Conformance corpus: 271 cases, a runner on the Python standard library, the list of ambiguities found while writing it
reference/	Reference implementation (python -m litediff [--check] [--strict] <patch> <workdir>), with a module map for ports
LICENSE, LICENSE-CODE	CC BY 4.0 for the text, MIT for the code and test data

Implementations

• JAI: Diff Editor (lite-diff) — VS Code extension (v1.0; v1.1 port in progress)
• reference/ — Python reference implementation of v1.1

License

The specification text (SPEC.md, README.md) is published under CC BY 4.0 (LICENSE). The code and test data (reference/, tests/) are published under the MIT License.