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

Source: https://voxgig.com/howto/set-an-overwrite-policy-for-regeneration

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

## 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](/howto/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`](https://learn.microsoft.com/en-us/openapi/kiota/using) | 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](https://github.com/oapi-codegen/oapi-codegen#generating-api-clients) | 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`](https://openapi-generator.tech/docs/usage/#generate) | 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](https://github.com/oxidecomputer/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](https://github.com/voxgig/sdkgen/blob/main/docs/explanation/regeneration-overwrite.md) | 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.

```bash
node policy.mjs
```

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

```js title="fixture/sdkgen/generated/.sdk/build/sdkgen.js"
// 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.

```text title="reports/sdkgen-generate.pruned.txt"
[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.

```text title="reports/sdkgen-merge-after-checkout.tsc.txt"
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](https://github.com/voxgig/sdkgen/blob/main/docs/explanation/regeneration-overwrite.md)
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](https://github.com/oapi-codegen/oapi-codegen#generating-api-clients) names it.

```yaml title="fixture/oapi-codegen/oapi-codegen.yaml"
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](https://github.com/oapi-codegen/oapi-codegen#should-i-commit-the-generated-code),
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.

```bash
node leftovers.mjs fixture/openapi-generator/before/FILES fixture/openapi-generator/after/client
```

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

```bash
node --test policy.test.mjs
```

```text output
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`](https://openapi-generator.tech/docs/usage/#batch) instead, which cleans
previously written files before it generates. The Maven plugin documents a
[`cleanupOutput` setting](https://github.com/OpenAPITools/openapi-generator/blob/v7.27.0/modules/openapi-generator-maven-plugin/README.md),
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](https://openapi-generator.tech/docs/customization/#ignore-file-format) 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

- [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)

- [Let a coding agent customize a generated SDK safely](/howto/customise-a-generated-sdk-with-an-agent-safely)

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

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

[^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](https://github.com/voxgig/sdkgen/blob/main/docs/explanation/regeneration-overwrite.md).
The run for this page reproduced the first with the toolchain it started with and one
`git checkout`.

[^2]: OpenAPI Generator's own
[customization page](https://openapi-generator.tech/docs/customization/#ignore-file-format)
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.

[^3]: Kiota's [usage page](https://learn.microsoft.com/en-us/openapi/kiota/using) 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.