pheon/docs/git.md
Jan Petykiewicz 8efeb04aab Simplify and speed up GDSII diffs
Summarize added and removed cells, group references, and keep replacement pairs together at text display limits. Trim hierarchy labels and summarize long unmatched paths.

Stream JSON object evidence and reduce parsing and comparison allocations. Parse large revisions concurrently and adaptively reuse matching cell bodies when most of the layout is shared.
2026-11-18 10:58:19 -08:00

60 lines
2 KiB
Markdown

# Git integration
Configure Git to show meaningful GDSII changes during review. Install the
[Pheon CLI](cli.md#install) first, then choose one of the following drivers.
Templates are also available in [contrib/git](../contrib/git/).
## Object comparison
Use the external driver for object-aware comparison and affected hierarchy.
Add this to your repository's `.gitattributes`:
```gitattributes
*.gds diff=pheon
```
Add this to `.git/config`, or use the same section in your user Git config:
```gitconfig
[diff "pheon"]
command = pheon git-diff --hierarchy ascii --
binary = true
trustExitCode = false
```
Then run `git diff` as usual. The driver reads Git's temporary old and new files
and handles additions, deletions, and renames. The heading names the file and
indicates whether it was added or deleted. Keep the final `--` because Git appends
its path and revision arguments after it. Put Pheon options such as `--top CHIP`
or `--show-layer 1/0` before that marker.
For an existing `diff=layout` attribute, put the configuration under
`[diff "layout"]` instead. Attribute names only select a Git driver.
The external driver returns 0 after rendering either an equal or different
comparison, and nonzero for invalid or incomplete comparisons. For automation
that needs equality status, run `pheon diff OLD NEW` directly; it returns
0, 1, or 2 as described in the [CLI guide](cli.md).
## Normalized text comparison
Use text conversion when you want Git to compare normalized text dumps. Set
`.gitattributes` to:
```gitattributes
*.gds diff=pheon-text
```
Configure the driver:
```gitconfig
[diff "pheon-text"]
textconv = pheon dump
binary = true
cachetextconv = true
```
Git can cache converted text. Invalidate that cache when upgrading to a tool or
comparison profile that changes the dump format, or disable `cachetextconv`.
These diffs are for human review; they are not patches that can be applied to
GDSII files. See the [comparison rules](comparison.md) for normalization details.