Building Git-Native Visual History with PixLog

#abotwrotethis #showdev #opensource #git

This is an internal platform-posting test; I am PixLog's author, and this article was drafted with AI assistance and fact-checked against PixLog v0.1.1.

Git tells you a binary file changed. PixLog shows which pixels changed, who changed them, and how the asset was made. Unlike Git LFS, which focuses on large-file storage and transport, or DVC, which tracks data and pipeline dependencies alongside Git, PixLog adds pixel-aware history, generation provenance, and visual policy without creating a second commit graph or staging area.

One version-control authority

PixLog follows one architectural rule: Git owns HEAD, the index, commits, branches, merges, and remotes.

When you run git add on a tracked image, PixLog's filter-process server hashes the exact bytes, stores a SHA-256 blob object locally, inspects the image to create a manifest object, looks up an optional recipe object, and commits only a compact pointer to Git. Worktrees hold the original image bytes; checkout restores those exact bytes through the smudge filter. There is no second PixLog HEAD or index.

The model separates four identities:

Git identity: the blob, tree, and commit OIDs Git sees.
Content identity: the SHA-256 of the exact image bytes.
Manifest identity: normalized format, dimensions, color-profile, and supported metadata inspection.
Recipe identity: normalized generation or edit provenance.

This matters because recompression can alter nearly every byte while preserving appearance, and metadata can change without changing pixels.

Visual diff and blame

The deterministic visual pipeline decodes PNG, JPEG, and GIF, samples at most 2,048 pixels on the longest edge, and reports change ratio, normalized RMSE, global SSIM, mean channel delta, and connected changed regions. It can also write a heatmap.

pixlog diff HEAD~1 HEAD -- assets/hero.png compares two revisions. Visual blame traces a coordinate through Git history: pixlog blame --point 760,145 assets/hero.png identifies the commit that changed that pixel.

Dimension changes are classified, but geometric registration is not implemented yet, so translation or rotation may over-report changes.

Generation recipes and trust

Recipes are content-addressed objects describing how an image was created. PixLog can import supported embedded ComfyUI and AUTOMATIC1111 metadata, record exact command context through pixlog run -- command, and associate manual or inferred provenance at lower confidence.

Capture fidelity and reproducibility are separate. A recipe can accurately preserve a request while still being only best-effort or provenance-only when a hosted model cannot reproduce identical bytes. Guarded replay checks repository state, requires an explicit base URL for HTTP execution, and reads authentication only from user-named environment variables.

Visual policy and merge

Policies can constrain formats, file size, required recipes, visual-change ratio, SSIM, and allowed edit regions or masks. Run pixlog check locally or through the PixLog Visual Policy GitHub Action; violations fail with machine-readable output suitable for CI.

The PNG merge driver is deliberately conservative: all three images must share the same geometry, and a pixel can be changed by only one side or changed to the same value by both sides.

How this differs from Git LFS and DVC

Git LFS is the mature choice when large-file server compatibility and locking are the main requirements, but it does not provide PixLog's built-in pixel metrics, visual blame, or generation recipes.

DVC is designed around data, models, experiments, and pipeline dependencies alongside Git. PixLog instead focuses on image assets inside normal Git history: exact bytes, changed regions, coordinate blame, provenance recipes, and enforceable visual rules.

Current limitations

Built-in visual decoding currently covers PNG, JPEG, and GIF.
Direct S3 and Azure Blob adapters are not shipped; file and HTTP Batch endpoints are available.
Hosted collaboration, geometric registration, and a swipe/onion-skin review UI are not shipped.
GitHub Checks publishing and semantic AI change summaries remain future work.
Hosted-model recipes may be provenance-only; deterministic replay is not guaranteed.

Install and try

On macOS:

brew install zhao-xuan/tap/pixlog chafa

Run the real five-commit demo:

git clone https://github.com/zhao-xuan/PixLog.git
cd PixLog
brew install zhao-xuan/tap/pixlog chafa imagemagick
bash demo/setup.sh
cd demo/workspace
pixlog diff HEAD~1 HEAD -- assets/hero.png

Then try:

pixlog blame --point 760,145 assets/hero.png
pixlog recipe show --revision HEAD assets/ai-poster.png
bash scripts/apply-unsafe-edit.sh && pixlog check

The final command intentionally fails the policy check.