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

Source: https://voxgig.com/howto/find-hand-edits-before-regenerating

- Audience: platform-team
- Level: intermediate
- Verified: 2026-11-19
- Published: 2026-11-19

## 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](https://git-scm.com/docs/git-diff) | 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`](https://ogen.dev/docs/intro/) | 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](https://github.com/OpenAPITools/openapi-generator/blob/v7.27.0/modules/openapi-generator/src/main/java/org/openapitools/codegen/DefaultGenerator.java) | 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](https://github.com/oxidecomputer/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`](https://github.com/voxgig/sdkgen/blob/main/docs/reference/cli.md) | 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`.

```bash title="generate.sh"
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`.

```bash
npx voxgig-sdkgen doctor
```

On the edited project it printed this, saved with its exit status on the last line.

```text title="reports/doctor.txt"
[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](https://github.com/voxgig/sdkgen/blob/main/docs/explanation/copies-merge.md)
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.

```text title="reports/doctor-classes.txt"
[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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/cli.md) 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.

```bash
npm run check-drift
```

```text title="reports/check-drift.txt"
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.

```js title="hand-edits.mjs"
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.

```bash
node demo.mjs sdkgen
```

```text output
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](https://pkg.go.dev/cmd/go#hdr-Generate_Go_files_by_processing_source).[^2]
Its [`--clean` flag](https://github.com/ogen-go/ogen/blob/v1.25.0/cmd/ogen/main.go) 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`](https://doc.rust-lang.org/cargo/reference/build-scripts.html), 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.

```bash
node demo.mjs ogen progenitor
```

```text output
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.

```bash
node --test hand-edits.test.mjs
```

```text output
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

- [Preview a regeneration as a diff before writing files](/howto/preview-a-regeneration-as-a-diff)

- [Fail a build when a generator customization becomes a fork](/howto/audit-generator-customisations-for-drift)

- [Find which template produced a generated file](/howto/find-which-template-produced-a-generated-file)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Set an overwrite policy for a regenerated SDK](/howto/set-an-overwrite-policy-for-regeneration)

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

[^1]: The comment on the method that writes it says `FILES` exists
[to track the files created by a run](https://github.com/OpenAPITools/openapi-generator/blob/v7.27.0/modules/openapi-generator/src/main/java/org/openapitools/codegen/DefaultGenerator.java),
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.

[^2]: The convention is a short paragraph in the documentation of
[`go generate`](https://pkg.go.dev/cmd/go#hdr-Generate_Go_files_by_processing_source). 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.