How-to › Ship an SDK

How to set an overwrite policy for a regenerated SDK#

Decide whether a regeneration overwrites, keeps, or cleans the files already on disk, set it where your generator reads it, and check that a removed file is gone.

Audience
Platform team
Level
intermediate
Topic
Regenerate without losing edits
Verified

Read first: Preview a regeneration as a diff before writing files

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Kiota --clean-outputNothing hand-written lives in the output directoryDeletes every file there first, so a hand-written file beside the client goes tooYou keep your own files next to the generated ones
oapi-codegen single output fileA Go client, where one output file holds every operationNo setting to choose: the file is replaced whole, with any edit inside itYou need per-file control over what a run may replace
OpenAPI Generator --skip-overwrite and --minimal-updateYou must keep edits in generated files, or keep timestamps of unchanged onesSkipped files stay stale, and only batch --clean removes a dropped file, with any edit in itYou want dropped files gone after every plain generate
progenitor static crateA Rust client you commit as its own crateBoth files are rewritten every run, and a module file it stops using staysIts macro fits, which leaves no file on disk to have a policy about
sdkgen overwrite with pruningAn sdkgen project, where edits belong in .sdk/ and output is disposableA hand edit in a target folder is lost on the next run, without a warningYou 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.

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

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

  2. 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-overwrite flag. The flag stays in the usage listing, described in eleven words. ↩︎ Back to text

  3. Kiota’s usage page describes --clean-output as 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 for kiota update accepts it too, and the run here honored it. ↩︎ 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.