Organize documentation into focused user guides

This commit is contained in:
Jan Petykiewicz 2026-11-16 16:51:41 -08:00
commit a384bb2f89

59
docs/git.md Normal file
View file

@ -0,0 +1,59 @@
# 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. Keep the final `--`: Git appends
its path and revision arguments after it. Put Pheon options before that marker,
for example `--top CHIP` or `--show-layer 1/0`.
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.