forkdiff-gen

Overview ¶

forkdiff-gen generates live/fork-surface.json, issue #423's measurement of the claim every release repeats and nothing had measured: "everything outside live resource markers is stock OpenTofu."

It diffs HEAD against the fork point - upstream commit 2b6193043d, the OpenTofu v1.13.0 tag, the upstream tree this checkout last merged from github.com/opentofu/opentofu (#1778) - and groups every changed path (added, modified, deleted) by top-level root: internal/live/, tools/, live/, site/, .github/, and a catch-all "other" for anything not under one of those. live/forkdiff_test.go (issue #423's guard) holds the other bucket to an allowlist: empty, or every entry accounted for with a one-line reason.

Usage, from anywhere in the checkout:

go run ./tools/forkdiff-gen

It shells out to git and needs the fork point reachable in the local object database. In this checkout that is usually already true - the `upstream` remote points at opentofu/opentofu precisely so it can be - but a shallow or fresh clone may need one read-only fetch first:

git fetch upstream

The tool's own error message says so when the commit is missing; it never fetches on its own.

A second mode, mirroring tools/readiness-gen -render, writes the docs site's copy of the artifact (site/data/fork_surface.json) from the already-committed live/fork-surface.json rather than a fresh diff - see render.go:

go run ./tools/forkdiff-gen -render

Limits (read this before trusting a "0" in the other bucket) ¶

The fork point is the fixed commit above, named by hash, not re-derived from git ancestry. It cannot be: this checkout's history was purged and re-rooted on 2026-08-14 (HANDOFF.md's "choudoufu history rewrite" note), so upstream's own commits are not ancestors of HEAD by git's own reckoning - `git merge-base --is-ancestor` says no. Upstream trees enter this history as grafts instead (#1778, ruling 5): v1.13.0's tree was committed as 2958e54f45 with the re-rooted original fork point (46ee2e77a3, a copy of upstream 03743ce6e8) as its parent, and merged. The graft's tree is byte-identical to 2b6193043d's (53f60e3359), so diffing against either gives the same surface. This tool names 2b6193043d because it is the hash a reader can look up in opentofu/opentofu; live/ci_coverage_test.go's upstreamBaseCommit names the graft because a CI guard needs a commit on HEAD's ancestry. What this tool runs is a content diff between two fixed commits (`git diff 2b6193043d HEAD`), which needs no ancestry at all and is unaffected by how the history in between is shaped. But it also means the fork point never advances by itself. If choudoufu ever backports an upstream commit into internal/ outside internal/live/, that backport is real fork-owned history from this artifact's point of view - it lands in the other bucket (there is no named root for stock-owned internal/ packages) exactly as a hand-written stock edit would, and live/forkdiff_test.go's allowlist is where it gets named and justified. The fork point moving to a newer upstream commit is a deliberate, separate act this tool does not perform.

The one exception the other bucket does not surface file-by-file is the module-path rename: every internal/**/*.go file whose only difference from the fork point, line for line and order-independently, is the quoted Go import path changing from "github.com/opentofu/opentofu" to "github.com/intentius/choudoufu" is excluded from the changed-file count entirely (its logic is byte-for-byte stock's; only the import spelling moved) rather than listed and allowlisted one by one - there are over a thousand of them, which is a fact about forking a Go module, not a fact about this fork's surface. mechanicalModuleRename in the artifact records how many were excluded this way. The substitution is deliberately narrow - a quoted import line under internal/, nothing else - because the same text substitution is not safe to apply blindly: a shell script's `exec` line and a doc comment citing an upstream issue by URL both contain the same string and must not be rewritten, and neither is treated as mechanical here. Every path outside internal/ is reported file for file with no filtering at all.

Render mode (issue #424, mirroring tools/readiness-gen's own -render): `go run ./tools/forkdiff-gen -render` writes the docs site's copy of the artifact (SiteDataRel, #1055) from the already-committed live/fork-surface.json - not a fresh diff against the fork point. That is the same deliberate choice readiness-gen's -render makes against live/readiness.json: reading the committed artifact rather than recomputing it is what makes a hand-edited or freshly regenerated live/fork-surface.json that never got rendered show up as a doc-render diff (TestForkSurfaceSiteDataIsCurrent in render_test.go) instead of silently passing because the render step re-derived the same numbers itself. No git, no network, no other generator's process.