Somebody fixed a bug in ts/src/entity/BookEntity.ts straight in the generator’s output. You
regenerate for a spec change and the generator rewrites that file from its templates, so the fix
is gone. The build passes because no test calls the method that went, and its deletion sits in a
diff that also carries every change the spec made.
What you get
You will end up with a list of every file that differs from what the generator wrote, labeled as generated output, scaffold copy, or your own. This is for you if you regenerate an SDK that people have edited.
Short answer
Use git and the generator’s own checks to list every file in a generated SDK that no longer
matches what the generator wrote, before you regenerate. In an sdkgen project, run
npx voxgig-sdkgen doctor inside .sdk for the scaffold copies and npm run check-drift on a
clean tree for the output. For any other generator, keep a branch of unedited output and read
git diff --name-status against it. Move each edit into the generator’s inputs first.
You will need
Node 22 or later, git, and a generated SDK committed to git with a clean working tree. Verified
2026-11-19 against @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, ogen v1.25.0,
cargo-progenitor 0.17.0, and OpenAPI Generator 7.27.0. The project on this page is a Bookshelf
API with five operations and one TypeScript target.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
git diff against a generated branch | Any generator, when you want a byte-exact list without running it | A branch every regeneration must update first, or each later diff includes the generator’s own changes | Nobody will keep the branch, where regenerating in a clean tree answers the same question |
ogen with --clean | A Go client, whose generated files are named oas_*_gen.go and carry a do-not-edit header | No report of its own, so you regenerate over a clean tree and read git | You need the list before anything is overwritten |
OpenAPI Generator FILES manifest | You run OpenAPI Generator and need the paths its last run wrote | Paths with no checksums, so it names the generated files and never says whether one changed | You need the changes themselves, which only a diff shows |
| progenitor | A Rust client built by its macro or build.rs, where no generated file is committed | Its static crate is two unmarked files, so only a diff finds an edit | You publish the generated crate and people patch it |
sdkgen doctor and check-drift | An sdkgen project, where you want each scaffold mismatch classified | Two commands for two halves: doctor never reads ts/, and check-drift deletes and regenerates it | The edits sit in another generator’s output |
Voxgig maintains sdkgen. It is one of five options here, not the recommendation.
The trade-off is classification against coverage. doctor says what each mismatch is, but it
reads only the copies under .sdk/. A diff against a generated branch covers every file and
explains none of them, and it is only as good as the discipline that keeps the branch pure.
ogen and progenitor leave no record beyond the files themselves, so with them the diff is the
whole method.
Commit what the generator wrote before anyone edits it
Every method here compares your tree with something, so the first job is to have that something.
generate.sh scaffolds the project, commits it untouched on a branch called generated, and
makes three hand edits on main.
cp "$here/api.json" .
npx --yes @voxgig/create-sdkgen@0.31.9 bookshelf --def api.json --target ts
cd bookshelf-sdk
(cd .sdk && npm run generate)
git init --quiet --initial-branch generated
git add --all
git commit --quiet --message 'What the generator wrote'
git switch --quiet --create main
cp -R "$here/fixture/sdkgen/main/." .
git add --all
The edits are a timeout added to a template under .sdk/tm/, a method added to
ts/src/entity/BookEntity.ts, and a file added at ts/src/extra/isbn.ts. One sits in the
scaffold, one in generated output, and one where the generator never wrote anything.
Ask doctor about the scaffold copies
An sdkgen project keeps the generator’s templates and components under .sdk/, copied in by
target add. doctor compares those copies with their source. Run it inside .sdk.
npx voxgig-sdkgen doctor
On the edited project it printed this, saved with its exit status on the last line.
[20:19:38.070] INFO: sdkgen doctor-finding CUSTOMIZED (an add merges its updates into it): tm/ts/src/utility/FetcherUtility.ts
[20:19:38.071] INFO: sdkgen doctor-end .sdk matches the scaffold (0 additive, 1 customized)
exit=0
doctor found the template and called it customized, meaning a copy the project changed after
an add wrote it. The next add
merges into such a copy
and does not replace it. That is the default mode, and it passes. The report is silent about
ts/, because doctor compares only what target add copies.
A failure takes a different change. generate.sh goes on to edit a component, add a file to a
template folder, delete a template, and add a component, and then doctor exits 1.
[20:19:38.962] INFO: sdkgen doctor-finding STALE (no longer written by `target add`): tm/ts/src/utility/Extra.ts
[20:19:38.962] INFO: sdkgen doctor-finding MISSING (would be written by `target add`): tm/ts/src/utility/MediaUtility.ts
[20:19:38.962] INFO: sdkgen doctor-finding additive (project-owned, not drift): src/cmp/ts/Extra_ts.ts
[20:19:38.962] INFO: sdkgen doctor-end .sdk has drifted: 1 forked, 1 edited, 1 stale, 1 missing, 0 outdated, 0 unresolved
The summary counts the two customized copies as forked and edited, but the exit status comes
from the stale and the missing file. With main: kit: copies: 'overwrite' in
.sdk/model/project.aontu, those two copies print as FORKED and EDITED, and fail as well.
The doctor reference lists
nine classes, and six appeared in these runs.
Regenerate from nothing to check the output
Output is the other half, and the scaffold ships a script for it. npm run check-drift deletes
every target folder, regenerates, and prints what git status reports afterwards. It refuses to
start on a tree with uncommitted changes, with exit status 2.
npm run check-drift
check-drift: DRIFT. These differ from what the generator produces:
M ts/src/entity/BookEntity.ts
D ts/src/extra/isbn.ts
M ts/src/utility/FetcherUtility.ts
The first status line is the hand edit: regeneration removed the added method. The second is the file
nobody generated, deleted with its folder. The third is the template edit arriving in the file
it produces, which is a change to commit and not one to move. The script exits 1 and leaves the
regenerated tree in place, and git checkout -- . restores yours. Its own legend reads D as
output the generator stopped emitting, so check each line against your history before you act
on it.
Label every difference from the generated branch
A branch that holds only generator output answers the same question for any generator, without
running one. git diff --name-status generated main lists all three edits and says nothing
about what kind of file each one is. hand-edits.mjs adds that from the records the generator
leaves in the tree.
let kind = 'output'
let evidence = 'on the generated branch, unmarked'
if (status === 'A') [kind, evidence] = ['added', 'never generated']
else if (output.has(path)) evidence = output.get(path)
else if (scaffold.has(path)) [kind, evidence] = ['scaffold', scaffold.get(path)]
else {
const header = generatedHeader(repo, from, path)
if (header) evidence = `header: ${header}`
else if (projects.some((base) => path.startsWith(base))) [kind, evidence] = ['unrecorded', 'no record names it']
}
The records are sdkgen’s three files under .sdk/log/, OpenAPI Generator’s FILES
manifest,1 and the header line of a generated Go file. Where none exists, the branch itself is
the evidence.
node demo.mjs sdkgen
sdkgen: generated..main
M .sdk/tm/ts/src/utility/FetcherUtility.ts scaffold copies.jsonl
M ts/src/entity/BookEntity.ts output generated.jsonl: Root/Entity/Entity@ts
A ts/src/extra/isbn.ts added never generated
1 of 3 changed files is generated output: move that edit before you regenerate
exit status 1
the same edits, in what sdkgen printed (reports/doctor.txt, reports/check-drift.txt)
edit doctor check-drift branch diff
.sdk/tm/ts/src/utility/FetcherUtility.ts CUSTOMIZED M * M
ts/src/entity/BookEntity.ts - M M
ts/src/extra/isbn.ts - D A
* reported as ts/src/utility/FetcherUtility.ts, the file that template writes
doctor exit status 0, check-drift exit status 1
generated.jsonl names the component that wrote the entity, so that is where the method moves:
added to .sdk/src/cmp/ts/fragment/Entity.fragment.ts, it came back in BookEntity.ts on the
next generate. The table under the list is the trade-off in three rows. doctor classified one
edit and never saw the other two. check-drift saw the output edits and showed the template
edit only as its effect. The branch diff saw all three and needed the records to tell them
apart.
Find the edits in another generator’s output
ogen has no report of its own. Every file it wrote for this document is named oas_*_gen.go
and opens with the line that marks generated Go code.2
Its --clean flag deletes
files of that name before it writes. A hand-written file beside them, such as titles.go, is
left alone. So the check is to regenerate in a clean tree and read git status, or to keep the
same generated branch.
The progenitor crate has three modes, and two of them leave nothing to edit. Its generate_api! macro
expands the client at compile time, and its build.rs builder writes into Cargo’s
OUT_DIR, outside your source.
Only cargo progenitor writes a crate you commit, as Cargo.toml and src/lib.rs, with no
header and no manifest. Regenerating over an edited crate replaced both files in the run for
this page.
node demo.mjs ogen progenitor
ogen: generated..main
M bookshelf/oas_client_gen.go output header: Code generated by ogen, DO NOT EDIT.
A bookshelf/titles.go added never generated
1 of 2 changed files is generated output: move that edit before you regenerate
exit status 1
progenitor: generated..main
M bookshelf/Cargo.toml output on the generated branch, unmarked
M bookshelf/src/lib.rs output on the generated branch, unmarked
2 of 2 changed files are generated output: move those edits before you regenerate
exit status 1
The ogen edit is recognized by its header. For progenitor the branch is the only evidence, so
both files count as output. The license edit belongs in --license-name, and the timeout in a
reqwest::Client passed to Client::new_with_client.
Check it worked
Eighteen tests run offline against the four fixtures and the saved reports. One fails if
doctor.txt ever names a file under ts/, and another if the branch diff misses an edit.
node --test hand-edits.test.mjs
1..18
# tests 18
# suites 0
# pass 18
# fail 0
# cancelled 0
# skipped 0
# todo 0
Then point the script at your own repository. Once every edit has moved,
node hand-edits.mjs . generated prints no file differs from the generated branch and exits 0.
When it goes wrong
npm run dry-generate rewrites files. In the run for this page it rewrote BookEntity.ts and
FetcherUtility.ts, the same two files a real generate changed, although voxgig-model --help
describes its dry run as modifying no files. Commit before you try it.
check-drift exits 2 with the working tree has uncommitted changes. It deletes target
folders, so it will not start over work that git cannot restore. Commit or stash, then run it
again.
A copy that doctor called customized is gone after target add --force. A plain target add
merged into the edited template and said so. With --force it replaced the template, and its
log named no file. Run doctor first and paste its report into the regeneration pull request.
Every file differs from generated. Someone regenerated on main, or upgraded the generator,
without updating the branch, so the diff holds the generator’s changes as well as yours.
Regenerate on generated, merge it into main, and compare again.
When not to do this
Do not hunt for hand edits in a tree that nobody may edit. If CI regenerates and fails on any difference, an edit never survives a merge, and that check costs less than this one.
Do not rely on sdkgen’s doctor alone before a regeneration. It reads the scaffold copies only,
so an edit under a target folder such as ts/ passes it.
Do not keep a generated crate at all if progenitor’s macro fits. With no generated file in the
repository there is nothing to edit and nothing to audit, which no committed SDK can say,
sdkgen’s included. ogen has a similar edge for a Go team: one naming rule and one header make
git status after go generate ./... the whole audit, with no record files to keep in step.
Do not move an edit by pasting it back after regenerating. Put it where the generator reads it:
a template or component under .sdk/, a generator option, or a file the generator does not own.
Related how-tos
Last verified
Verified 2026-11-19 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3,
ogen v1.25.0, cargo-progenitor 0.17.0, and OpenAPI Generator 7.27.0. Every output block is
what the command preceding it printed. All four generators were run on the Bookshelf document,
and what they wrote is committed under fixture/. doctor and check-drift need the installed
toolchain, so their reports are shown as generate.sh saved them under reports/.
cargo progenitor ran with a nightly rustfmt, which its formatting options require.
Footnotes
-
The comment on the method that writes it says
FILESexists to track the files created by a run, which it calls ideal for CI. Created is meant literally. A second run over the same folder wrote a manifest one line shorter here, because.openapi-generator-ignoreis written only when it is missing, so the second run did not create it. ↩︎ Back to text -
The convention is a short paragraph in the documentation of
go generate. Generated source should have a line matching^// Code generated .* DO NOT EDIT\.$, before the first text that is not a comment. The stated purpose is to convey to humans and machine tools that the code is generated. The capitals read as an order, but the paragraph names no tool that refuses an edited file. ↩︎ Back to text