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.
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:
This matters because recompression can alter nearly every byte while preserving appearance, and metadata can change without changing pixels.
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.
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.
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.
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.
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.
PixLog makes Git image-aware while keeping Git as the only version-control authority.