How-to › Ship an SDK

How to find hand edits in a generated SDK before you regenerate#

List every file that no longer matches what the generator wrote, and label each one as output, scaffold copy, or your own, before a regeneration overwrites it.

Audience
Platform team
Level
intermediate
Topic
Regenerate without losing edits
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
git diff against a generated branchAny generator, when you want a byte-exact list without running itA branch every regeneration must update first, or each later diff includes the generator’s own changesNobody will keep the branch, where regenerating in a clean tree answers the same question
ogen with --cleanA Go client, whose generated files are named oas_*_gen.go and carry a do-not-edit headerNo report of its own, so you regenerate over a clean tree and read gitYou need the list before anything is overwritten
OpenAPI Generator FILES manifestYou run OpenAPI Generator and need the paths its last run wrotePaths with no checksums, so it names the generated files and never says whether one changedYou need the changes themselves, which only a diff shows
progenitorA Rust client built by its macro or build.rs, where no generated file is committedIts static crate is two unmarked files, so only a diff finds an editYou publish the generated crate and people patch it
sdkgen doctor and check-driftAn sdkgen project, where you want each scaffold mismatch classifiedTwo commands for two halves: doctor never reads ts/, and check-drift deletes and regenerates itThe 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.

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

  1. The comment on the method that writes it says FILES exists 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-ignore is written only when it is missing, so the second run did not create it. ↩︎ Back to text

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

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.