pheon/docs/git.md

1.9 KiB

Git integration

Configure Git to show meaningful GDSII changes during review. Install the Pheon CLI first, then choose one of the following drivers. Templates are also available in contrib/git.

Object comparison

Use the external driver for object-aware comparison and affected hierarchy. Add this to your repository's .gitattributes:

*.gds diff=pheon

Add this to .git/config, or use the same section in your user Git config:

[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.

Normalized text comparison

Use text conversion when you want Git to compare normalized text dumps. Set .gitattributes to:

*.gds diff=pheon-text

Configure the driver:

[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 for normalization details.