Upgrade config and repository formats

Manifest and settings migrations

Dotweave migrates a config file when it reads it. There is no separate upgrade command: the first command that opens an older manifest.jsonc or settings.jsonc brings the file forward, one version step at a time.

Before rewriting, Dotweave writes a backup next to the original file, named <filename>.v<originalVersion>.bak. Migrating a version 7 manifest therefore leaves manifest.jsonc.v7.bak, and a version 2 settings file leaves settings.jsonc.v2.bak. The rewrite itself is atomic, and it runs only after the migrated result passes semantic validation, so an invalid migration is never persisted.

manifest.jsonc is at version 9; versions 7 and 8 are accepted and migrated. settings.jsonc is at version 3, and version 2 is accepted and migrated.

The manifest step from 7 to 8 hoists profile names into a registry. Profile names used to live only on individual entries; the migration collects them into a top-level profiles array, sorted, with default left out because that profile is implicit. The settings step from 2 to 3 drops a legacy age section.

A rewrite reformats the file from the parsed data, so hand-written comments and your original key order do not survive it. Copy anything you want to keep out of the .bak file afterwards.

Repository format 0 to 1

The repository format is separate from the manifest version. It versions how artifacts are laid out on disk rather than how the manifest is structured, and it is recorded as repositoryFormat in manifest.jsonc. The current format is 2; an absent field means format 0.

Format 0 stored a tracked symlink as a real symlink under profiles/. Format 1 stores it as a regular <name>.dotweave.symlink metadata file holding the POSIX link target, which travels between platforms through git. The migration walks everything under profiles/ and converts each physical symlink it finds. It is idempotent: once no physical symlinks remain, running it again does nothing.

Unlike a config migration, this one touches the filesystem, and it runs during a non-dry-run dotweave push only. dotweave push --dry-run skips it. dotweave track and dotweave untrack write the existing format marker back rather than claiming an upgrade they did not perform. One real dotweave push is therefore the way to migrate a repository forward.

Commit the sync directory and leave it clean before the first push on a new Dotweave version. A format migration rewrites files under profiles/, and a clean tree keeps that rewrite reviewable as a single git diff.

Repository format 1 to 2

Format 1 stored a symlink target exactly as the operating system reported it. A link created with an absolute target inside your home directory therefore committed a path containing your user name, such as C:/Users/you/.agents/AGENTS.md, and pulling it on another machine recreated that same dangling path. Format 2 stores such a target as ~/.agents/AGENTS.md, and pull expands the ~ against the home directory of the machine doing the pull.

The migration rewrites each .dotweave.symlink file whose target sits inside the home directory of the machine running it. Relative targets and targets outside the home directory are left exactly as they were, and a file already in the portable form is not rewritten at all. Like the format 0 migration, it runs during a non-dry-run dotweave push and is idempotent.

Upgrade every machine before the first format 2 push. An older Dotweave reads repositoryFormat first and fails with REPO_FORMAT_NEWER, which is deliberate: without the upgrade it would create a literal ~ directory instead of resolving the target.

Until that push runs, dotweave status lists the affected symlinks under push changes while reporting the local side as up to date. Both readings are correct — the repository needs rewriting, the link on disk does not.

When a repository is too new or too old

Dotweave checks the repository format on every config read, so a command fails immediately instead of half-reading a repository it does not understand.

Repository format <n> is newer than this CLI supports means another machine already migrated the repository. Upgrade Dotweave on this machine; Dotweave does not downgrade a repository.

The opposite case is a repository below the oldest format this CLI still supports. Run an older Dotweave release, do one dotweave push there to migrate the repository forward, then upgrade again. No released format sits below the current floor, so this failure cannot happen today; it exists for the release that eventually drops format 0.

Implementation and reference

The version, repositoryFormat, and profiles fields are documented with their types and defaults in manifest.jsonc, and the global fields in settings.jsonc. The artifact layout that the format migration rewrites is described in Directory and repository layout.

Read Error messages for the exact text of every migration failure, or Troubleshoot a broken sync when a command still fails after an upgrade.