Skip to content

Migrating from create-forge 0.3.x

This page covers moving from the 0.3.x line — direct Copier generation by default, with an opt-in --engine-preview — to create-forge 0.4.0 and later, where the forge-template engine is the default new path and copier is the optional legacy extra.

What changed

0.3.x 0.4.0 and later
new defaults to Copier new defaults to the engine
Engine reachable via hidden --engine-preview --engine-preview removed; engine is the default
copier a required dependency copier moved to the optional legacy extra
Copier route: new, update, --template/--template-url/--ref Unchanged, now under --legacy
Engine-preview projects: no update support Engine-generated projects: full update support (.forge/generation.json)

Upgrading your installed CLI does not change files in projects you have already generated. See installation for the four supported install modes, including create-forge[legacy].

Upgrade your installed CLI

uv tool upgrade create-forge
# or, for a pinned install:
uv tool install "create-forge>=0.4,<0.5"

If you use any --template, --template-url, --ref, or a recorded .copier-answers.yml project, add the legacy extra:

uv tool install "create-forge[legacy]"

create-forge new and create-forge update without --legacy and without the extra installed both still work — they use the engine, not Copier.

Existing 0.3.x Copier projects

A project generated by any 0.3.x release (or by create-forge new --legacy today) keeps working exactly as documented in updates. Its recorded .copier-answers.yml is unaffected by the cutover — the direct-Copier route is not deprecated and carries no removal date.

uvx create-forge update --dry-run
uvx create-forge update

create-forge reads the project's own files to route the update automatically: a .copier-answers.yml-only project always uses the Copier route, with or without --legacy.

Existing 0.3.x engine-preview projects

A project generated with the hidden, now-removed --engine-preview flag recorded neither .forge/generation.json nor .copier-answers.yml — it never supported create-forge update, on 0.3.x or since. Running update against one is rejected outright, with nothing written:

$ create-forge update path/to/preview-project
Neither .forge/generation.json nor .copier-answers.yml was found in
path/to/preview-project. create-forge update needs one of them --
.forge/generation.json selects the engine-native route, .copier-answers.yml
the --legacy Copier route. This project was not created by create-forge, its
provenance file was deleted, or it was created by the removed
development-only --engine-preview flag, which wrote neither file and never
supported updates. Generate a fresh project with `create-forge new` and port
your changes across -- create-forge will not invent answers for an existing
tree.

There is no automated migration path — create-forge cannot tell a preview-era project apart from any directory it never touched, so it will never fabricate a provenance record for one. To move a preview project forward:

  1. Generate a fresh project with create-forge new, choosing the same archetype and capabilities.
  2. Port your own code, tests, and configuration across by hand.
  3. The new project has .forge/generation.json and supports create-forge update from then on.

If 0.4.0 doesn't work for you

create-forge 0.3.x stays installable and supported for at least 90 days and at least one further tagged create-forge release past the 0.4.0 cutover. Pin back while you wait for a fix:

uv tool install "create-forge==0.3.2"

create-forge 0.3.2 resolves forge-template>=0.4.1,<0.5 and keeps generating exactly as it did before the cutover.

Recovering from a bad update

Both update routes require a clean, committed working tree before writing anything, and a failed or interrupted engine-native update never leaves half-applied changes staged. If an update leaves your tree in a state you want to discard entirely:

git restore . && git clean -fd

This restores every tracked file to its last commit and removes any new untracked files the update added — the same recovery create-forge itself prints if an engine-native update is interrupted (for example with Ctrl-C). Run it from the project root before retrying.

Missing an example or found an unclear step? Send documentation feedback.