typdiff-git 0.7.4

Generate one visual Typst revision PDF from all .typ files changed between two Git revisions
typdiff-git-0.7.4 is not a library.

typdiff-git

A Git-aware wrapper for sou1118/typdiff that generates full-document Typst revision PDFs with visual diffs for text, figures, and subfigures.

typdiff-git compares two Git revisions, or a Git revision and the current working tree, then compiles the complete Typst project from its root document. Text changes are handled by typdiff, while added, modified, and deleted figures receive dedicated visual markers.

Features

  • Compare two commits, tags, or branches
  • Compare a Git revision with the current working tree
  • Include staged, unstaged, and non-ignored untracked files
  • Compile a complete multi-file Typst document from main.typ
  • Preserve document structure, references, numbering, bibliography, and page layout
  • Show added and deleted text using typdiff markup
  • Keep newly added cross-reference functions executable, such as #Fig(<fig:example>)
  • Mark newly added figures with a blue frame
  • Show modified figures vertically as Previous version and Revised version
  • Detect figure changes when:
    • the asset path changes
    • the path remains unchanged but the file contents change
  • Compare individual assets inside multi-panel figures and subfig layouts
  • Leave unchanged subfigures untouched
  • Insert deleted-figure notices near their former references
  • Include the previous caption in deleted-figure notices when available
  • Fall back to a final Deleted Figures section when an inline insertion point cannot be found
  • Preserve intermediate old, new, and report trees for debugging

Example output

Added figure

A newly added #figure(...) <fig:...> definition is wrapped in a blue box labeled Added figure.

Modified figure

A modified image or PDF is replaced by a vertical comparison:

Previous version
[old figure]

Revised version
[new figure]

The comparison uses the original horizontal width, making it suitable for detailed scientific figures that would be difficult to read side by side.

Deleted figure

A deleted figure is represented near its former reference by a red notice containing, when available:

  • the former figure label
  • the previous asset path
  • the previous caption
  • a statement that the figure was removed from the revised document

Requirements

Install typdiff from crates.io:

cargo install typdiff

Make sure typst, typdiff, and git are available in PATH:

typst --version
typdiff --version
git --version

Installation

Install from crates.io:

cargo install typdiff-git

Or clone your repository and build the release binary:

git clone https://github.com/YOUR_ACCOUNT/typdiff-git.git
cd typdiff-git
cargo build --release

Install the binary in a user-local directory:

install -m 755 target/release/typdiff-git ~/.local/bin/typdiff-git

Ensure ~/.local/bin is in PATH.

Basic usage

typdiff-git OLD_REV NEW_REV \
  --main main.typ \
  -o revision-diff.pdf

For example:

typdiff-git submitted-version HEAD \
  --main main.typ \
  -o revision-diff.pdf

The output is a complete PDF based on the newer revision, not a collection of separately compiled chapter PDFs.

Compare with the working tree

Use WORKTREE as the newer revision:

typdiff-git HEAD WORKTREE \
  --main main.typ \
  -o working-tree-diff.pdf

This includes:

  • staged changes
  • unstaged changes
  • tracked-file deletions
  • non-ignored untracked files

Ignored files and .git/ are excluded.

WORKTREE is supported only as the newer side because the report uses the newer document structure as its base.

You may also compare an older submitted revision directly with the current working tree:

typdiff-git submitted-version WORKTREE \
  --main main.typ \
  -o current-revision.pdf

Multi-file Typst projects

A typical project may look like this:

main.typ
chap_intro.typ
chap_methods.typ
chap_results.typ
references.bib
Figs/

main.typ may include child documents:

#include "chap_intro.typ"
#include "chap_methods.typ"
#include "chap_results.typ"

typdiff-git exports both revisions, copies the complete newer tree into a temporary report tree, replaces changed child sources with visual diff sources, and compiles main.typ once.

This preserves:

  • chapter order
  • page settings
  • counters and numbering
  • bibliography
  • labels and cross-references
  • headers and footers
  • appendices

Cross-reference functions

Projects often define custom reference helpers such as:

#Fig(<fig:example>)
#Figure(<fig:example>)

Newly added references remain executable Typst. Therefore, an added call such as:

#Fig(<fig:example>)

is rendered as its resolved text, for example:

Fig. 1.1

rather than displayed as literal Typst source.

References that exist only in the old revision are neutralized before typdiff runs. This prevents unresolved deleted labels and invalid escaping from breaking compilation.

Figure handling

Supported figure asset extensions are:

.png
.jpg
.jpeg
.webp
.svg
.pdf

Added figures

A figure label that exists only in the newer revision is treated as an added figure:

#figure(
  image("Figs/new-result.pdf"),
  caption: [A newly added result.],
) <fig:new-result>

The complete figure definition is wrapped in a blue Added figure box.

Label-based detection means the figure can still be recognized when:

  • the asset already existed in the repository
  • an existing asset is reused in a new figure
  • the figure is composed using a helper such as subfig

Modified figures

A figure is treated as modified when either:

  1. its referenced asset path changes, or
  2. its asset path stays the same but the file contents differ between revisions.

For same-path changes, the old and new files are compared byte for byte. File timestamps are not used.

The generated comparison places the old asset above the new asset:

Previous version
[old asset]

Revised version
[new asset]

Subfigures and multi-panel figures

For a multi-panel figure such as:

#figure(
  (
    subfig("Figs/panel-a.pdf", ...),
    subfig("Figs/panel-b.pdf", ...),
  ),
  caption: [A two-panel comparison.],
) <fig:panels>

assets are tracked in source order:

asset 0 = panel-a.pdf
asset 1 = panel-b.pdf

If only panel A changes, only asset 0 is replaced with a previous/revised comparison. Panel B remains unchanged.

Deleted figures

A figure definition removed from the newer revision is detected by its <fig:...> label. A red Deleted figure box is inserted near the paragraph containing the removed #Fig(...) or #Figure(...) reference.

The box can include:

  • the former label
  • the previous image path
  • the previous caption

The previous caption is shown without additional coloring or strike-through.

If the former location cannot be determined, the notice is added to a final Deleted Figures section.

Custom image functions

The built-in image(...) function is always recognized.

If a project uses a custom function whose first quoted string argument is an image path, register it with --image-function:

typdiff-git HEAD WORKTREE \
  --main main.typ \
  --image-function my-image \
  --image-function panel-image \
  -o revision.pdf

Example:

#my-image("Figs/example.pdf", width: 90%)

The option is repeatable.

Include and exclude paths

Limit processing to selected paths:

typdiff-git OLD_REV NEW_REV \
  --main main.typ \
  --path chapters \
  -o revision.pdf

Exclude style, template, or generated files that should not be passed through typdiff:

typdiff-git OLD_REV NEW_REV \
  --main main.typ \
  --exclude page_settings.typ \
  --exclude template.typ \
  --exclude generated \
  -o revision.pdf

This is recommended for Typst files that primarily define functions, styles, or templates. They remain available from the newer project tree, but their code is not decorated with text-diff markup.

Debugging

By default, intermediate files are created in a temporary directory and removed when the command exits.

Use --debug-dir to preserve them:

typdiff-git HEAD WORKTREE \
  --main main.typ \
  --debug-dir .typdiff-debug \
  -o working-tree-diff.pdf

The debug tree contains:

.typdiff-debug/
├── old/                    # exported old revision
├── new/                    # exported new revision or WORKTREE
├── report/                 # exact project tree used for compilation
│   ├── main.typ
│   ├── changed-child.typ
│   ├── .typdiff-figures/   # generated figure comparisons
│   └── .typdiff-notices.typ
└── deleted-figures.txt

The exact source compiled by Typst is:

.typdiff-debug/report/main.typ

Useful checks include:

grep -R -n "Added figure" .typdiff-debug/report --include='*.typ'
grep -R -n "Deleted figure" .typdiff-debug/report --include='*.typ'
grep -R -n ".typdiff-figures" .typdiff-debug/report --include='*.typ'
find .typdiff-debug/report/.typdiff-figures -type f -name '*.pdf' -print

Add the debug directory to .gitignore:

.typdiff-debug/

Typical command

typdiff-git HEAD WORKTREE \
  --main main.typ \
  --exclude page_settings.typ \
  --debug-dir .typdiff-debug \
  -o working-tree-diff.pdf

How it works

  1. Validate the old and new revisions.
  2. Export the old revision.
  3. Export the new revision or current working tree.
  4. Copy the complete newer project into a report tree.
  5. Detect added figure definitions by label.
  6. Detect modified image and PDF assets by path and file contents.
  7. Generate previous/revised figure-comparison PDFs.
  8. Rewrite only affected figure or subfigure asset references.
  9. Run typdiff for changed child .typ documents.
  10. Insert deleted-figure notices near their former references.
  11. Compile the report-tree main.typ once with Typst.

Limitations

  • main.typ is used as the newer structural entry point. Text written directly in main.typ is not currently highlighted because rewriting the entry point can interfere with imports, includes, and document-level configuration.
  • Image paths assembled dynamically may not be resolved statically:
#image("Figs/" + filename)
  • Image paths stored only in runtime data structures may require project-specific handling.
  • Deleted figures are positioned using removed figure references when available. If no reliable location is found, they are listed in the final appendix.
  • Git LFS assets must be available as real image or PDF files in both exported trees. A pointer file cannot be rendered by Typst.
  • Figure-comparison blocks increase document height and can change page breaks.

Relationship to typdiff

This project is not a fork of typdiff. It invokes typdiff as an external source-level diff engine and adds Git-aware project orchestration, full-document compilation, and visual figure comparison.

Upstream project:

Issues concerning Typst source parsing and text-diff rendering may belong upstream. Git revision handling, working-tree snapshots, full-project compilation, and figure lifecycle visualization are implemented in typdiff-git.

Contributing

Bug reports and pull requests are welcome. Forks and independent extensions of this project are even more welcome. This project was created primarily to address an urgent practical need: generating revision documents for an academic manuscript under a tight deadline. Please note that I am not a Rust expert, and much of the code was developed with the assistance of AI tools. The implementation may therefore contain unconventional design choices or areas that could benefit from review and improvement. Please test the tool carefully before using its output for important submissions.

When reporting an issue, please include:

  • the command used
  • the relevant execution log
  • whether the newer side is a commit or WORKTREE
  • a minimal Typst example if possible
  • the contents of the relevant files under .typdiff-debug/report/

Please do not include confidential manuscripts or unpublished data in public issues.

License

Apache-2.0.