pheon/docs/git.md

63 lines
2.1 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.
The external driver also accepts `--color=always` before `--` to keep colors
when its output goes through a pager that supports ANSI colors.
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.