Organize documentation into focused user guides
This commit is contained in:
parent
b3346b40a4
commit
a384bb2f89
1 changed files with 798 additions and 681 deletions
59
docs/git.md
Normal file
59
docs/git.md
Normal 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.
|
||||
Loading…
Reference in a new issue