Your generator writes TypeScript, Markdown, JSON and PNG files into one folder, and people edit
some of them. Under jostraca’s default, a regeneration overwrites all four, so a tuned retry
count and a rewritten README go with the code nobody touched. Turning preserve on for
everything instead leaves a backup beside every generated source file.
What you get
You will end up with a table from extension to mode, one generate call per mode, and a test
that regenerates twice and lists the siblings left behind. This is for you if your generator
writes several kinds of file and people edit some kinds and not others.
Short answer
jostraca’s existing option has two sets, txt and bin, chosen by whether a file is binary,
so it has no key per extension. To give each file type its own mode, map extensions to modes in
your generator and run one generate call per mode, each with its own existing. A preserve
backup lasts one regeneration, because the next one that changes the file replaces it, so commit
before you regenerate and list the .old and .new siblings after.
You will need
Node 22 or later, a jostraca generator that writes at least one file, and an existing generated
output directory. The sample pins jostraca 0.42.0 with its peer shape, and the Go half uses the
Go port at the same version. The modes are documented in jostraca’s
options reference.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
Copier _skip_if_exists | A project template, where some files belong to the user after the first copy | One mode per pattern, skip, so a skipped file never gets a later fix | You generate code that changes on every run |
Hey API output.clean | A TypeScript client in a folder that holds nothing you wrote | One switch for the whole folder: empty it, or keep extra files and overwrite its own | You keep docs or config inside the output folder |
| jostraca existing file modes | You write the generator and can choose a mode for each kind of file | A table of types to keep up, one generate call per mode, and siblings to clean | Nobody edits the output, so the default overwrite is enough |
ogen --clean | A Go client in a package where your own files sit beside the generated ones | Its files are always rewritten, and --clean deletes by name pattern | You need an edit inside a generated file to survive |
OpenAPI Generator --skip-overwrite and .openapi-generator-ignore | You generate with it and want some patterns left alone | Ignored files freeze, and no pattern can back up, offer or merge | A file needs the next generate and the edit both |
Voxgig maintains jostraca, the subject of this page, whose repository sits in the jostraca
GitHub organization. Voxgig makes none of the other four tools in the table.
The other four decide per folder or per name pattern, and the choice is to write a file or leave it alone. jostraca offers five modes, and the cost is that someone has to choose one per type and clean up the files two of them leave. A generator nobody edits gets nothing from that choice.
Read the flag order from a run
modes.mjs generates one text file and one PNG, edits both by hand, and regenerates under each
setting.
node modes.mjs
existing notes.txt logo.png siblings files
default new generate new generate - written
txt write:false edit kept new generate - written
txt preserve new generate new generate notes.old.txt preserved written
txt present new generate new generate - written
txt present, write:false edit kept new generate notes.new.txt presented written
txt diff diff markers new generate - conflicted diffed written
txt merge merge markers new generate - conflicted merged written
txt diff and merge diff markers new generate - conflicted diffed written
bin preserve new generate new generate logo.old.png preserved written
bin present, write:false new generate edit kept logo.new.png presented written
bin diff throws: Validation failed for property "bin" with object "{diff:true}" because the property "diff" is not allowed.
Three rows matter most. present alone changes nothing: it runs only when write is false.
diff and merge together run diff alone, and each writes its own markers.1 A txt
setting never reaches the PNG, and bin refuses diff, merge and conflict. The extension
decides which set applies, through jostraca’s list of binary extensions, and a NUL byte early
in the file can move an unlisted extension to binary.2
Map each extension to a mode
The table lives in your generator, because jostraca has no place for it. Each mode is a full
existing value, and each extension names one mode.
export const MODES = new Map([
['overwrite', { txt: { write: true }, bin: { write: true } }],
['offer', { txt: { write: false, present: true }, bin: { write: false, present: true } }],
['merge', { txt: { merge: true } }],
['backup', { txt: { preserve: true }, bin: { preserve: true } }],
])
export const POLICY = new Map([
['.ts', 'overwrite'], // generated code nobody edits
['.md', 'offer'], // docs people rewrite: put the new version beside theirs
['.json', 'merge'], // config people tune: three-way merge against the last generate
['.png', 'backup'], // assets people replace: keep their bytes in a .old sibling
])
modeOf throws for an extension the table lacks, so an unlisted file type stops the run. It reads
the table as a Map, so constructor is not a type, and it looks up a name such as .env that
has no extension by its whole name.
Run one generate call per mode
A per-call existing is merged key by key over the global one, which a test checks, so each call
gets its own mode and the files keep their own folder.
const jostraca = Jostraca({ now, log })
const report = {}
for (const [mode, group] of groups) {
const res = await jostraca.generate({ folder, existing: MODES.get(mode) }, () => {
Project({}, () => {
for (const file of group) {
if ('from' in file) Copy({ from: file.from, to: file.path })
else File({ name: file.path }, () => Content(file.text))
}
})
})
report[mode] = res.files
}
The PNG goes through Copy, which treats it as binary. Each call leaves the other calls’ files
in place, as the listings below show for all four.
Regenerate twice and list the siblings
twice.mjs generates version 1.0.0, edits all four files, then generates 1.1.0 and 1.2.0.
node twice.mjs
after generating 1.1.0
README.md 1.0.0 + edit
README.new.md 1.1.0
assets/logo.old.png logo ours
assets/logo.png logo 1.1.0
config/defaults.json 1.1.0 + edit
src/client.ts 1.1.0
after generating 1.2.0
README.md 1.0.0 + edit
README.new.md 1.2.0
assets/logo.old.png logo 1.1.0
assets/logo.png logo 1.2.0
config/defaults.json 1.2.0 + edit
src/client.ts 1.2.0
After the first regeneration every type behaves as its row says. The merge kept the hand-tuned
retry count and took version 1.1.0, and the README kept the edit with the 1.1.0 text beside it.
After the second, logo.old.png holds logo 1.1.0: preserve backs up whatever is on disk when
it differs from the generate, so the replacement logo from the first edit is gone. A rerun that
changes nothing keeps the backup, as a test shows. Copy a backup out, or commit, before the next
change.
Keep the siblings out of git
jostraca 0.42.0 only writes the siblings. A test overwrites both with junk and regenerates, and the junk stays where it is while the generated files come out as before. git lists the siblings as files it does not track.
node gitcheck.mjs
git status after regenerating
M assets/logo.png
M config/defaults.json
M src/client.ts
?? README.new.md
?? assets/logo.old.png
with .gitignore: *.old *.new *.old.* *.new.*
M assets/logo.png
M config/defaults.json
M src/client.ts
?? .gitignore
The four patterns match the names jostraca makes, which a test checks for a.old.txt,
b.min.old.js, noext.old and .env.old. The suffix goes before the last extension, or after
a name that starts with a dot or has no extension. They also hide a real file named
whats.new.md, so check your tree with
git check-ignore before you commit them.
Do the same in Go
The Go port takes the same flags as *bool pointers in jostraca.Existing, and its
Go reference says a
per-call Existing in Options overlays the global one flag by flag.
var yes, no = true, false
var modes = map[string]jostraca.Existing{
"overwrite": {Txt: jostraca.ExistingTxt{Write: &yes}},
"offer": {Txt: jostraca.ExistingTxt{Write: &no, Present: &yes}},
"backup": {Txt: jostraca.ExistingTxt{Preserve: &yes}},
}
var policy = map[string]string{".go": "overwrite", ".md": "offer", ".env": "backup"}
go run -C go .
after generating 1.1.0
.env 1.1.0, generated
.env.old 1.0.0, hand edit
README.md 1.0.0, hand edit
README.new.md 1.1.0, generated
client.go 1.1.0, generated
refused: no regeneration mode for logo.svg
Go’s filepath.Ext returns .env for .env, so that file finds its row without the
fallback the TypeScript modeOf needs. The Go program has no test of its own: the captured output
is the whole check, and the gate compares it on every run.
Regenerate without file modes in other generators
Neither generator has a mode per file. Each writes its own files whole and decides only what
happens to the rest of the folder. record.sh ran one scenario on both, and on OpenAPI
Generator and Copier:3 generate, edit a generated file, add a Markdown file and a hand-written
one, generate again.
cat records/generators.txt
generate, edit, add files, generate again; what the second run left of each
tool setting code edit Markdown hand-written code
Hey API 0.99.0 output.clean: true lost deleted deleted
Hey API 0.99.0 output.clean: false lost kept kept
ogen v1.25.0 no flag lost kept kept
ogen v1.25.0 --clean lost kept kept
OpenAPI Generator 7.27.0 no flag lost lost kept
OpenAPI Generator 7.27.0 --skip-overwrite kept kept kept
OpenAPI Generator 7.27.0 ignore file **/*.md lost kept kept
Copier 9.19.1 _skip_if_exists: *.md lost kept kept
ogen no flag: oas_stale_gen.go, named like its output: kept
ogen --clean: oas_stale_gen.go, named like its output: deleted
Hey API empties output.path before each run unless clean is false, and its documentation
warns that false may leave broken output. The substitute for a mode is a folder: keep the
README and config outside output.path and import the client from it. The --clean flag of
ogen removes only files whose names start with oas or openapi and end in _gen.go or
_gen_test.go, as its
cleanDir shows, so your files
in the package are safe by name. An edit inside a generated file is lost under both.
Check it worked
Sixteen tests run, covering the flag order, sibling names, the per-type run, the second regeneration, git, and the package glob below.
node --test modes.test.mjs
1..16
# tests 16
# suites 0
# pass 16
# fail 0
# cancelled 0
# skipped 0
# todo 0
The test that carries the page regenerates three times and asserts that logo.old.png holds
logo 1.1.0, not the hand-made logo, and that exactly two siblings are on disk.
When it goes wrong
A fresh clone loses the hand-tuned config. The merge baseline lives in
.jostraca/generated/, which jostraca’s own .gitignore keeps out of git, so the clone has
none and merge overwrites the file. Add conflict: 'fail' to the merge mode to stop instead,
or set control.version: true and commit the baseline.
The README is overwritten although the mode is offer. The mode set present and left
write at its default. Set write: false in the same set.
A sibling ships in the package. A glob such as assets/*.png in the files list of
package.json picks up
logo.old.png too. Clean the siblings in the build step, or narrow the glob.
When not to do this
Do not give jostraca a table of modes for output nobody edits. The default overwrite is the right policy there, and every mode beyond it adds files to ignore and a decision to revisit.
Do not trust preserve as a backup. It keeps one generation of history, and the second run in
the test replaced the only copy of the edit. Commit before you regenerate, and let git be
the backup.
Choose Hey API when the client is TypeScript and the output folder holds only generated code:
its emptied folder is a simpler guarantee than any table of modes. Choose ogen when your Go
files can sit beside its oas_*_gen.go files, because the naming rule does the work a table
does here.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, jostraca 0.42.0 with shape 12.2.5, and the Go port
v0.42.0 with Go 1.24.7, and on Go 1.25.0 from an empty module cache. record.sh ran @hey-api/openapi-ts 0.99.0, ogen v1.25.0 on the Go
1.26 toolchain it fetched, OpenAPI Generator 7.27.0 on OpenJDK 21 and Copier 9.19.1, once, and
records/generators.txt is what it wrote.
Footnotes
-
jostraca’s options reference notes that the generated side of a merge conflict came first before 0.41, and that the existing side’s label carries the previous run’s completion time. With no previous run that time is
-1, which renders as1969-12-31T23:59:59.999Z: a conflict dated one millisecond before the epoch. ↩︎ Back to text -
The utilities reference puts the list at around 250 extensions, from
pngandpdftowoff2anddocx, and says only the last dot segment counts. A basename that starts with a dot has no extension at all, so.envis text by default, andlogo.png.txtis text too. ↩︎ Back to text -
Copier’s own example for
_skip_if_existsis a password the project generates the first time, from a template that hashes a random number, and should not override after that. The documented use is a secret that must survive every regeneration, and a README the user rewrote is the same case with lower stakes. ↩︎ Back to text