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 - commit 03743ce6e8, "RFC: Speed up tofu show <planfile> by embedding schemas into the planfile (#4239)", the commit this checkout diverged from github.com/opentofu/opentofu at - 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, rewrites the fork-surface span of the docs site's positioning page in place, 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), and 03743ce6e8 is consequently not an ancestor of HEAD by git's own reckoning - `git merge-base --is-ancestor` says no. What this tool runs is a content diff between two fixed commits (`git diff 03743ce6e8 HEAD`), which is exactly as valid a comparison as it was the day the fork was cut, 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` rewrites the docs site's positioning page in place, between `<!-- forkdiff-gen:begin fork-surface -->` / `<!-- forkdiff-gen:end fork-surface -->` markers, 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 (TestForkSurfaceRenderedSpanIsCurrent 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.