A colleague fixed the base URL in a generated client and added a helper at the end of the file. The API gains a field, you regenerate, and both edits are gone, because the generator writes each file whole. Keeping the file out of generation instead freezes it, so the field never arrives either.
What you get
You will end up with a regeneration that keeps hand edits and lands the generator’s changes, conflicts you can find before they are committed, and a baseline that survives a clone. This is for you if people edit generated files and regenerate them.
Short answer
Run jostraca with existing: { txt: { merge: true } } and it merges each regenerated file against
its last generation in .jostraca/generated/, keeping your edits and landing the generator’s
changes. A conflict puts your side first, then =======. Commit that baseline with
control.version: true, or a clone overwrites every edit. sdkgen runs jostraca with merge off and
overwrites ts/, so change its model, templates or components under .sdk/ instead.
You will need
Node 22 or later, git, and a generated tree committed to git. The page runs
jostraca, the library that writes files for generators
such as sdkgen, with a small generator of its own in gen.mjs. Merge mode applies to a tree you
generate with jostraca yourself: sdkgen turns it off for its own output. Run
Find hand edits in a generated SDK before you regenerate
first if you do not know which files carry edits.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Copier update | A project made from a versioned template, rather than from an API document | The answers file must never be edited by hand, and conflicts land inline or in .rej files | Your output comes from an OpenAPI document |
| Fern Replay | A Fern SDK published through pull requests | Fern’s pull-request output mode, and .fern/replay.lock committed in the SDK repository | Your SDK reaches its repository another way than Fern’s pull requests |
| jostraca merge mode | Your own generator built on jostraca, with edits inside generated files | A baseline to commit, and markers that can reach source files | Your generator overwrites by design, as sdkgen does |
| Kiota | Typed clients whose behavior changes go in middleware, outside the generated tree | No merge of its own, so an edit lasts until the description changes | Edits must live inside generated files |
| OpenAPI Generator | Whole files you take over, listed in .openapi-generator-ignore | An ignored file stops receiving every later change the generator makes to it | You edit a few lines of a file the generator still owns |
Voxgig maintains jostraca, the subject of this page, and sdkgen, which writes its files with it. Copier, Fern, Kiota and OpenAPI Generator are other projects’ tools.
Merge keeps an edit in place, at the price of a baseline you must not lose and markers you must not commit. Neither Kiota’s documentation nor OpenAPI Generator’s describes a merge, so with them the merge base is a git branch that holds only generator output. Fern Replay and Copier keep their own record of the last generation and merge against it for you.
Turn on merge in the generator
gen.mjs writes one client file per entity. The existing option decides what happens to a file
already on disk, and now is pinned so the markers carry the same timestamp on every run:
export async function generate(folder, model, { existing = { txt: { merge: true } }, control } = {}) {
const jostraca = Jostraca({ now: () => 1735689600000, existing, ...(control ? { control } : {}), log: quiet })
return jostraca.generate({ folder }, () => {
Project({}, () => {
Folder({ name: 'src' }, () => {
for (const name of Object.keys(model.entity).sort()) {
File({ name: `${cap(name)}Client.ts` }, () => Content({ src: clientSource(model, name), raw: true }))
}
})
})
})
}
Each run copies what it generated to .jostraca/generated/, and the next run merges against that
copy, as the options reference
describes. Without merge: true the default writes the file whole, which one test shows.
Regenerate over two hand edits
regen.mjs runs the story in throwaway git repositories, with git given an empty configuration
and a fixed identity. Two edits are committed: a byIsbn helper at the end of the file, and
BASE pointed at a staging host. Then the model changes twice:
node regen.mjs merge
1 generate v1, commit: written src/BookClient.ts
tracked under .jostraca: .jostraca/.gitignore
baseline .jostraca/generated/src/BookClient.ts: on disk, ignored by .jostraca/.gitignore:3:generated
2 commit two hand edits: a byIsbn helper at the end, BASE pointed at staging
3 regenerate from v2, which adds isbn: merged src/BookClient.ts
git diff: + isbn?: string
hand edits kept: byIsbn yes, staging BASE yes
4 commit, regenerate from v2 again: merged src/BookClient.ts
git status --porcelain: (empty)
5 regenerate from v3, which moves BASE to /v2: merged src/BookClient.ts, conflicted src/BookClient.ts
<<<<<<< EXISTING: 2025-01-01T00:00:00.000Z/merge
export const BASE = 'https://staging.example.com/v1'
=======
export const BASE = 'https://api.example.com/v2'
>>>>>>> GENERATED: 2025-01-01T00:00:00.000Z/merge
git diff --check: exit 2, src/BookClient.ts:2: leftover conflict marker
markers.mjs: src/BookClient.ts:2 src/BookClient.ts:6
6 regenerate from v3 again, markers still in: merged src/BookClient.ts, conflicted src/BookClient.ts
file byte for byte as it was: yes
Step 1 put the baseline in .jostraca/generated/, and the .gitignore jostraca wrote keeps it
out of git. Step 3 is the point of merge mode: the diff is the one line the model added, and both edits
stayed. Step 4 is the check to keep, because a second run from the same model left nothing for
git to report.
Step 5 changed the line the edit had changed. The existing side comes first, then =======, then
the generated side, which the options reference calls the order git writes a conflict in. jostraca releases before 0.41 put
the generated side first.1 A rerun leaves a conflicted file alone, so resolve it by hand, then
regenerate.
Find the markers before they are committed
git diff --check reports a leftover conflict marker in a change and exits non-zero, as the
git-diff documentation says. It sees only what is not yet
committed. markers.mjs reads the whole tree, skips .git and .jostraca, and exits 1 on any
line that opens or closes a conflict. Run it in CI after every regeneration.
Commit the baseline, or a clone overwrites your edits
.jostraca/.gitignore keeps the baseline out of git by default. A clone therefore has no base to
merge against:
node regen.mjs clone
7 fresh clone of step 4, no .jostraca/generated: nothing tracked
conflict: 'fail', regenerate from v2: jostraca: 3-way merge produced conflicts, left unchanged: src/BookClient.ts (no baseline)
hand edits kept: byIsbn yes, staging BASE yes
merge, regenerate from v2: written src/BookClient.ts, unmerged src/BookClient.ts
hand edits kept: byIsbn no, staging BASE no
8 control.version: true, fresh clone, regenerate from v2: merged src/BookClient.ts
tracked under .jostraca: .jostraca/generated/src/BookClient.ts .jostraca/jostraca.meta.log
hand edits kept: byIsbn yes, staging BASE yes
In a clone, merge mode lists the file as unmerged and overwrites it, even when the model has not
changed. conflict: 'fail' stops the run instead and keeps the file. control.version: true stops
jostraca writing its .gitignore, so the baseline is committed with the tree, and the clone
merged.
Check sdkgen before you hand-edit its output
record.sh scaffolded a TypeScript SDK with @voxgig/create-sdkgen 0.31.9, appended a line to a
generated entity file, and regenerated:
cat records/sdkgen-scaffold.txt
sdkgen 4.44.3, jostraca 0.42.0, scaffold @voxgig/create-sdkgen 0.31.9
existing in .sdk/build/sdkgen.js: existing: { txt: { write: true, merge: false } }
hand edit in ts/src/entity/BookEntity.ts after regenerating: overwritten
git status --porcelain after regenerating:
M ts/src/entity/BookEntity.ts
git status --porcelain after a second regeneration: 0 lines
sdkgen 4.45.0, the newest release, did the same, in records/sdkgen-4.45.0.txt. sdkgen’s
regeneration explanation
calls generated directories disposable and lists the failures merge caused it, a stale baseline
among them. Make the change in the model, the templates or the components under .sdk/, then
regenerate.
Merge Kiota and OpenAPI Generator output through a branch
Kiota’s lock file records the generation parameters and a hash of the description, and Kiota skips a run when neither has changed. None of the 20 pages of its documentation index read for this page describes keeping an edit in generated code. Request behavior goes in middleware handlers. OpenAPI Generator’s ignore file takes whole files out of generation.
The merge base can be a git branch instead. record.sh committed each generator’s v1 output on a
generated branch, edited main, regenerated v2 on generated, and merged. It ran the branch
twice per tool, once with an edit appended to the file and once with an edit on its first
title?: line:
branch() { # $1 = directory, $2 = generate function, $3 = edited file, $4 = the hand edit, a sed script
mkdir -p "$1" && cd "$1"
git init -q -b generated .
"$2" api-v1.json && commit "generate from v1"
git checkout -q -b main
sed -i "$4" "$3" && commit "hand edit"
git checkout -q generated
rm -rf out && "$2" api-v2.json && commit "generate from v2"
git checkout -q main
git merge --no-edit -q generated > "$1.log" 2>&1 && echo " git merge: exit 0" || echo " git merge: exit $?"
}
cat records/kiota.txt records/openapi-generator.txt
kiota: regenerate from v2 over the edited tree
hand edit in out/models/index.ts: overwritten
kiota: hand edit appended to the file, v2 generated on the generated branch, git merge generated
git merge: exit 0
hand edit in out/models/index.ts: kept
lines naming isbn in out/models/index.ts: 4
git status --porcelain: 0 lines
kiota: hand edit on the first title?: line, then the same merge
git merge: exit 0
git status --porcelain:
lines with the hand edit in out/models/index.ts: 1, lines naming isbn: 4
conflict marker lines in out/models/index.ts: 0
the conflict:
openapi-generator: regenerate from v2 over the edited tree
hand edit in out/models/Book.ts: overwritten
openapi-generator: hand edit appended to the file, v2 generated on the generated branch, git merge generated
git merge: exit 0
hand edit in out/models/Book.ts: kept
lines naming isbn in out/models/Book.ts: 3
git status --porcelain: 0 lines
openapi-generator: hand edit on the first title?: line, then the same merge
git merge: exit 1
git status --porcelain:
M out/apis/DefaultApi.ts
M out/docs/Book.md
UU out/models/Book.ts
M out/runtime.ts
lines with the hand edit in out/models/Book.ts: 1, lines naming isbn: 3
conflict marker lines in out/models/Book.ts: 2
the conflict:
<<<<<<< HEAD
title?: string; // edited by hand
=======
title?: string;
/**
*
*/
isbn?: string;
>>>>>>> generated
A plain run over the edited tree overwrote the edit with both tools. The branch kept an appended
edit and landed isbn. Kiota puts isbn a few lines before title, so the edit on that line
merged too. OpenAPI Generator puts it directly below, so git stopped with a conflict, your side
first. Resolve it on main and commit, as you would any merge.
Check it worked
Sixteen tests hold each step of the scenario and each record to what the page says. Two check
that markers.mjs ignores an underline of equals signs, refuses an empty tree, and reads a file
with CRLF line endings.
node --test merge.test.mjs
1..16
# tests 16
# suites 0
# pass 16
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 1932.511904
When it goes wrong
A build breaks on a line that starts with <<<<<<<. A conflicted file was committed. Run
markers.mjs in CI, and resolve each conflict before the commit.
CI regenerates and every edit disappears. The job runs in a fresh clone, so there is no baseline,
and the merge overwrote the files. Set control.version: true and commit .jostraca/generated/,
or set conflict: 'fail' so the job stops instead.
A regeneration reports merged and the generator’s change never lands. The baseline is stale: a
branch switch took the edited file back while the ignored baseline stayed at the newer generate.
node regen.mjs stale
9 default .gitignore, v2 on a branch, back to main, regenerate from v2: merged src/BookClient.ts
isbn landed: no, hand edits kept: byIsbn yes, staging BASE yes
git status --porcelain: (empty)
10 control.version: true, v2 on a branch, back to main, regenerate from v2: merged src/BookClient.ts
isbn landed: yes, hand edits kept: byIsbn yes, staging BASE yes
git status --porcelain: M .jostraca/generated/src/BookClient.ts, M .jostraca/jostraca.meta.log, M src/BookClient.ts
A committed baseline moves with the checkout, so step 10 landed isbn.
The baseline stays out of git after you set control.version: true. The options reference says
of the .gitignore: “With true it is not written, and an existing one is left alone.” Delete
that file once, then commit .jostraca/.
When not to do this
Do not hand-edit sdkgen output. The scaffold sets merge: false, so the next generate overwrites
the edit, on 4.44.3 and on 4.45.0.
Do not turn on jostraca’s merge without committing its baseline. Every clone and CI job then overwrites the edits that merge was meant to keep, and a branch switch can drop the generator’s change.
Do not merge a file you have rewritten. Take it over completely, with OpenAPI Generator’s ignore
file or Fern’s .fernignore, because a merge of mostly edited text conflicts on every run.
Kiota is the better choice when the changes are behavior, not code. Its middleware handlers sit outside the generated tree, so nothing needs merging. OpenAPI Generator suits a team that wants templates of its own and a short list of files it owns outright.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, jostraca 0.42.0 with shape 12.2.5, @voxgig/create-sdkgen
0.31.9, @voxgig/sdkgen 4.44.3 and 4.45.0, Kiota 1.39.0, and OpenAPI Generator 7.27.0. Every output
block is what the command preceding it printed. The jostraca scenario runs on each build. sdkgen,
Kiota and OpenAPI Generator ran once in record.sh, and their records are committed. Copier and
Fern Replay were not run. What the table says of them comes from their documentation, Fern’s custom
code page for the sdk-config.yml format.
Footnotes
-
The options reference spends one sentence on the swap, noting that before 0.41 the generated side came first. It adds that a file still holding markers in the older order is recognized as unresolved all the same. The same page gives the reason for the order: with the file on disk first, an editor’s “accept current” keeps the user’s lines. On a file merged before 0.41, the same choice kept the generator’s. ↩︎ Back to text