snapshot-patch.py applies patch operations to an anchored snapshot and writes a new patched snapshot.
It is intended for applying precise, line-addressable patches generated from an anchored snapshot, including those prepared by an LLM.
The source snapshot is never modified in place.
Python 3.10 or newer is required.
python snapshot-patch.py --snapshot-file SNAPSHOT --patch-file PATCH
A patch can also be read from standard input:
python snapshot-patch.py --snapshot-file SNAPSHOT --patch-stdin
An explicit output path can be provided with --output-file:
python snapshot-patch.py --snapshot-file SNAPSHOT --patch-file PATCH --output-file OUTPUT
--snapshot-file PATH
Required. Specifies the source anchored snapshot.
The snapshot is parsed using the shared snapshot parser. Patch operations target snapshot file blocks by META.id and anchored lines by their line number and line identifier.
The snapshot structure and anchored line format are described in Snapshot format.
Exactly one patch source is required.
--patch-file PATH
Reads the patch as UTF-8. A UTF-8 byte-order mark is accepted.
--patch-stdin
Reads the patch from standard input as UTF-8. A UTF-8 byte-order mark is accepted.
The accepted patch syntax is described in Patch format. Rules intended specifically for LLM-generated output are available in Patch generation rules for LLM.
A patch targets one or more snapshot file blocks using their META.id values.
Operations are applied in patch order to the current anchored content of each selected block. Each anchor must match both its line number and line identifier. Missing anchors, reversed ranges, duplicate file headers, unknown file identifiers, malformed operations, and invalid payload usage are rejected.
Supported operations include:
- insertion before or after an anchored line
- insertion of a blank line before or after an anchored line
- replacement of one anchored line or an anchored range
- deletion of one anchored line or an anchored range
Patch payload lines are converted to plain snapshot content. Leading whitespace is preserved. Middle-dot characters (·) are converted to ordinary spaces before patch parsing and application.
After all operations for a file block are applied, its META.patch_applied value is set to true.
--output-file PATH
Optional. Specifies the output snapshot path.
When omitted, the output is created beside the source snapshot:
- the first
anchoredoccurrence in the source filename is replaced withpatched - if the source filename does not contain
anchored,patched-is prepended
For example:
project_snapshot-anchored-2026-08-05_10-35-22.txt
project_snapshot-patched-2026-08-05_10-35-22.txt
The output path must differ from the source snapshot path. snapshot-patch.py never writes in place.
The patched snapshot is written as UTF-8 with LF line endings and ends with a final line break.
Each touched file block is serialized and parsed again after patch application. This block-level round-trip validation verifies that its filename, content, and metadata remain unchanged by serialization.
After all selected blocks are patched, the complete output snapshot is serialized and parsed again using the shared snapshot parser. Final validation verifies that the parsed file identifiers and their order match the source snapshot.
The output file is written only after patch parsing, patch application, block-level validation, and whole-snapshot validation succeed.
The created patched snapshot path is printed after successful completion.