Criei um 'git diff' pra arquivos Excalidraw · eujonas

Todo time tem diagramas no repositório. Arquitetura do sistema, fluxo de onboarding, modelo de dados. Eles mudam, PRs são mergeados, e ninguém revisa as mudanças nos diagramas. Por quê? Porque não tem como. O git diff te mostra um JSON gigante onde mudou um x de 142 pra 145. Impossível saber se alguém moveu uma caixinha ou reescreveu a arquitetura inteira.

Eu construí uma solução. Instala em 5 segundos e já funciona:

Instalação

Apenas linux:

curl -fsSL https://raw.githubusercontent.com/JonRC/excalirender/main/install.sh | sh

Qualquer OS com Docker:

docker run --rm -v "$(pwd):/data" -w /data jonarc06/excalirender diff v1.excalidraw v2.excalidraw

Como usar

# Diff básico — gera PNG com tags Added, Removed, Modified
excalirender diff v1.excalidraw v2.excalidraw

# GIF animado — alterna entre estado antigo e novo
excalirender diff v1.excalidraw v2.excalidraw -o diff.gif

# Dark mode + fundo transparente
excalirender diff old.excalidraw new.excalidraw --dark --transparent

# Pipe do stdin — útil em CI
git show HEAD~1:diagram.excalidraw | excalirender diff - diagram.excalidraw -o diff.png

Exemplo: Hollow Knight game flow

Pra demonstrar, criei um exemplo com o fluxo de conclusão do Hollow Knight. A versão antiga tem erros de digitação ("Forgoten Crossroads", "Crystal Caves", "Hollow Night") e uma área falsa ("Mushroom Market"). A versão nova corrige tudo, adiciona "Ancient Basin" e remove a área falsa. O GIF alterna entre os dois estados:

Diff GIF — Hollow Knight game flow

Veja o examplo completo em: examples/diff-gif

Como o algoritmo funciona

O Excalidraw atribui um ID único pra cada elemento. O diff usa isso como base:

Se o ID existe nos dois arquivos → compara propriedades (posição, tamanho, cor, texto, stroke, etc.)
Se alguma propriedade mudou → marca como "Modified"
Se o ID só existe no arquivo antigo → "Removed"
Se o ID só existe no novo → "Added"

Campos transitórios como seed (que controla a aleatoriedade do estilo hand-drawn) são ignorados na comparação. Sem isso, praticamente todo elemento apareceria como "Modified" mesmo sem mudança real.

Conheça o projeto

O projeto é open source, licença MIT: github.com/JonRC/excalirender

Se você já passou pelo problema de revisar mudanças em diagramas e ficou frustrado olhando JSON, experimenta. E se tiver sugestão ou quiser contribuir, o repo tá aberto.