You remove two endpoints from the API document and regenerate. The generator rewrites the files
it still produces and leaves apis/AuthorsApi.ts where it was, so the package keeps shipping a
client for endpoints that are gone. Run over a file a colleague fixed by hand, the same command
erases the fix, because nothing in the project says which files a run may replace.
What you get
You will end up with one stated policy for files already on disk, set in your generator’s configuration, and a check that a removed operation’s file is gone. This is for you if you regenerate into a directory that is committed.
Short answer
Pick one policy for files already on disk, overwrite, keep, or clean, and set it in the
generator’s configuration before the next run. sdkgen overwrites generated output and removes
files its record shows it stopped writing, and the existing line in .sdk/build/sdkgen.js
should stay at merge: false. Kiota cleans with --clean-output, OpenAPI Generator keeps with
--skip-overwrite or cleans with batch --clean, and oapi-codegen and progenitor rewrite their
output whole. Then check that a removed operation’s file is gone.
You will need
Node 22 or later, git, and a generated SDK committed to git. Verified 2026-11-19 against
@voxgig/sdkgen 4.44.3, oapi-codegen v2.8.2, cargo-progenitor 0.17.0, Kiota 1.38.0, and
OpenAPI Generator 7.27.0. Read
how to preview a regeneration as a diff first if you
have not seen what your generator would change.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
Kiota --clean-output | Nothing hand-written lives in the output directory | Deletes every file there first, so a hand-written file beside the client goes too | You keep your own files next to the generated ones |
| oapi-codegen single output file | A Go client, where one output file holds every operation | No setting to choose: the file is replaced whole, with any edit inside it | You need per-file control over what a run may replace |
OpenAPI Generator --skip-overwrite and --minimal-update | You must keep edits in generated files, or keep timestamps of unchanged ones | Skipped files stay stale, and only batch --clean removes a dropped file, with any edit in it | You want dropped files gone after every plain generate |
| progenitor static crate | A Rust client you commit as its own crate | Both files are rewritten every run, and a module file it stops using stays | Its macro fits, which leaves no file on disk to have a policy about |
| sdkgen overwrite with pruning | An sdkgen project, where edits belong in .sdk/ and output is disposable | A hand edit in a target folder is lost on the next run, without a warning | You have edits in output that cannot move yet |
Voxgig maintains sdkgen. It is one of five options here, not the recommendation.
Overwrite is predictable and unforgiving: an edit in output lasts until the next run. Keeping
files saves the edit and freezes everything else, which is what --skip-overwrite does. A clean removes
what the document dropped and whatever else was in the directory. Merge sits between them, and
its cost is a base that has to stay in step with the tree.
Run one scenario through every policy
A policy decides the fate of four kinds of file. One is a generated file with a hand edit in it,
and one is a generated file the next document must change. The others are the files that
document no longer produces, and a hand-written file in the output directory. generate.sh ran
each generator from a document with books and authors, made the edit, added the file, removed
the authors, and regenerated. policy.mjs prints what git saw afterwards.
node policy.mjs
tool policy hand edit must update dropped files hand-written file
Kiota update lost updated 2 of 2 left kept
Kiota update --clean-output lost updated removed deleted
oapi-codegen one output file lost updated one file kept
OpenAPI Generator no flag lost updated 4 of 4 left kept
OpenAPI Generator --minimal-update lost updated 4 of 4 left kept
OpenAPI Generator --skip-overwrite kept stale 4 of 4 left kept
OpenAPI Generator edited file in the ignore file kept updated 4 of 4 left kept
OpenAPI Generator batch --clean lost updated removed kept
progenitor cargo progenitor lost updated one file kept
sdkgen generate lost updated 1 of 6 left kept
sdkgen check-drift lost updated 1 of 6 left deleted
sdkgen generate, edited file protected kept updated 1 of 6 left kept
sdkgen generate, client file protected lost stale 1 of 6 left kept
sdkgen generate, merge on kept updated 1 of 6 left kept
sdkgen the same after a checkout kept stale 1 of 6 left kept
Read the rows in pairs. Kiota’s update regenerates from the committed kiota-lock.json and
left both author files, and --clean-output removed them along with the hand-written file.
OpenAPI Generator’s --minimal-update ends in the same tree as no flag. The difference is in
what it leaves untouched: it rewrote 4 of the 16 files, where the plain run rewrote 10.
--skip-overwrite kept the edit by writing nothing, so the index still exports the author
client. batch --clean removed the author files and the edit, and left titles.ts. Three rows keep the edit and still land the change. One is OpenAPI Generator with the
edited file named in its ignore file. The other two are sdkgen, first with that file protected
and then with merge on. The last row is the merge again, after a git checkout.
Keep sdkgen on overwrite
sdkgen’s policy is one line of the build configuration that the scaffold writes, and the scaffold explains its choice beside it.
// Overwrite generated SDK output, never 3-way merge: output is fully
// model-derived and never hand-edited, and merging against a drifting
// .jostraca base keeps stale files / injects <<<<<<< markers on toolchain
// bumps. See @voxgig/sdkgen docs/explanation/regeneration-overwrite.md.
existing: { txt: { write: true, merge: false } },
That is what ran here. npm run generate rewrote the edited entity, updated the client class,
and removed the author files, naming each one.
[20:41:18.276] INFO: model/apidef entity-gc removed orphaned entity model file author.aontu (no longer derived from the def)
[20:41:18.701] INFO: model/sdkgen generate-prune removed .sdk/test/entity/author/AuthorTestData.json, no longer generated
[20:41:18.702] INFO: model/sdkgen generate-prune removed ts/src/entity/AuthorEntity.ts, no longer generated
[20:41:18.702] INFO: model/sdkgen generate-prune removed ts/test/entity/author/AuthorDirect.test.ts, no longer generated
[20:41:18.702] INFO: model/sdkgen generate-prune removed ts/test/entity/author/AuthorEntity.test.ts, no longer generated
Removal follows a record. Each generate lists what it wrote in .sdk/log/generated.jsonl, and
a file on an earlier list is deleted when the component that wrote it runs again without it. A file the generator never
wrote, such as ts/src/extra/isbn.ts, is not on any list and stays. npm run check-drift
deletes each target folder first, so the same file goes. Of the six author files, one stayed: a
flow model, BasicAuthorFlow.aontu. It was dropped from its index and left on disk.
So the policy to set is the one already there. Keep merge: false, keep hand-written code out
of target folders, and move an edit into the template or component under .sdk/ that writes
the file.
Know what merge and the protect marker cost
Change merge: false to merge: true and jostraca, the engine under sdkgen, merges three ways
against a copy of its last output in .jostraca/generated/. With that base in step, the run
kept the hand edit and landed every change. The base is ignored by git, though. After one
git checkout -- ., the same command exited 0, removed AuthorEntity.ts, and left the client
importing it.
src/BookshelfSDK.ts(3,30): error TS2307: Cannot find module './entity/AuthorEntity' or its corresponding type declarations.
The narrower tool is a marker. A generated file that contains the text JOSTRACA_PROTECT is
not rewritten, so the edit in the protected entity survived an overwrite run. The whole file is
frozen with it. With the marker on the client class instead, that file kept its import of the
deleted entity, which is the row that reads stale.
The overwrite explanation
names these failures.1
Set the policy in oapi-codegen and progenitor
oapi-codegen has no overwrite setting, because it writes one file. The
output key names it.
package: bookshelf
output: bookshelf/bookshelf.gen.go
generate:
client: true
models: true
The run replaced bookshelf.gen.go whole: the edit and the author operations went together,
and titles.go beside it was untouched. A document that failed to parse left the previous file
in place. The policy is therefore a convention. Generated code goes in the .gen.go file and
everything else in files of your own. The project recommends
committing the generated file,
so a diff shows each change.
cargo progenitor rewrites Cargo.toml and src/lib.rs on every run and has no flag to skip
or clean. The hand-written titles.rs stayed on disk, but the line declaring it was an edit in
lib.rs, so the module dropped out of the build. A second leftover is its own:
--include-client true writes src/progenitor_client.rs, and a later run with false leaves
that file behind. Keep hand code in a crate that depends on the generated one, or use the
generate_api! macro and commit no generated file.
Check it worked
Remove an operation, regenerate, and read git status --short. With sdkgen the removed
entity shows as D ts/src/entity/AuthorEntity.ts. Where a run does not clean, compare
manifests. leftovers.mjs reads the FILES manifest OpenAPI Generator committed and the one
its last run wrote, and lists what dropped out and is still on disk.
node leftovers.mjs fixture/openapi-generator/before/FILES fixture/openapi-generator/after/client
apis/AuthorsApi.ts
docs/Author.md
docs/AuthorsApi.md
models/Author.ts
4 files from the previous run still on disk, not written by the last one
It exits 1 until those files are deleted. Eighteen tests hold every row of the table to its report.
node --test policy.test.mjs
1..18
# tests 18
# suites 0
# pass 18
# fail 0
# cancelled 0
# skipped 0
# todo 0
When it goes wrong
The removed operation’s file is still there. The generator overwrites and does not clean: Kiota
without --clean-output, and OpenAPI Generator’s generate under every flag run here. Run
batch --clean instead, which cleans
previously written files before it generates. The Maven plugin documents a
cleanupOutput setting,
which was not run for this page.
The edited file is gone after batch --clean. It was in the committed FILES and in the ignore
file, so the clean deleted it and the run did not write it back. Restore it from git, and do not
clean a directory whose ignore file protects an edit.
The edit survived and the client is stale. --skip-overwrite wrote nothing in this run, since
every file existed, so the index still exported AuthorsApi. Name the edited file in the
ignore file instead:
that run kept the edit and updated the index.2
--clean-output deleted a file you wrote. It empties the output directory.3 Move
hand-written files out of it.
The SDK stops compiling after a regeneration that exited 0. Merge is on and its base is out of step, or a protected file needed the change. Turn merge off, remove the marker, and regenerate.
When not to do this
Do not set a keep or merge policy to protect edits you could move. An edit in sdkgen output
belongs in .sdk/, and one in a Go or Rust client belongs in a file the generator does not
write.
Do not turn on sdkgen’s merge for a repository people check out, which is every repository. The base it merges against never travels with a commit.
Do not pick a generator for its overwrite flags. oapi-codegen has none and needs none, since one file cannot leave another behind. For a Go client that is a better position than any policy here, sdkgen’s included. Progenitor’s macro goes further and leaves no generated file to manage.
Do not clean a directory you have not committed. Every policy on this page assumes git can put back what a run removes.
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,
jostraca 0.42.0, oapi-codegen v2.8.2, cargo-progenitor 0.17.0, Kiota 1.38.0, and OpenAPI
Generator 7.27.0. Every output block is what the command preceding it printed. All five
generators were run through the scenario by generate.sh. The page’s commands read the reports
it saved and run no generator. cargo progenitor ran with a nightly rustfmt.
Footnotes
-
The explanation lists three: stale-file retention, conflict-marker injection, and silent no-ops. It adds that they are latent, appearing only when an existing tree is regenerated after a toolchain upgrade. The run for this page reproduced the first with the toolchain it started with and one
git checkout. ↩︎ Back to text -
OpenAPI Generator’s own customization page makes the comparison. The ignore file, it says, allows for better control over overwriting existing files than the
--skip-overwriteflag. The flag stays in the usage listing, described in eleven words. ↩︎ Back to text -
Kiota’s usage page describes
--clean-outputas deleting the output directory before generating the client, and lists it as available for the download and generate commands. The same page’s usage line forkiota updateaccepts it too, and the run here honored it. ↩︎ Back to text