pheon/docs/git.md

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

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.