Table of Contents

Content migrations

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Generated from docs/reference/commands/content-migrations.md at v10.1.0 – edit the repository, not this wiki.

Content migrations

The migrations a release may require of an instance's content, and recording that they ran.

`migrate list`

List every migration document under instructions/migrations/.

Synopsis

wikitool migrate list [--json]

Options

  --json      Print the migrations as JSON
  -h, --help  Show this message and exit.

Examples

tools/wikitool migrate list

Behaviour

Lists every migration document under instructions/migrations/, oldest target first, with its kind and obligation.
Never fails. Read-only and exempt from the Iteration Budget Gate.

Properties

Changes files: no
Idempotent: yes
Atomic: Read-only
Counts toward the session call budget: no
Can reach the network: no

Exit codes

0 - success

See also

wikitool migrate status - which of them this instance still owes
instructions/migrate-corpus.md - how a migration is run

`migrate status`

Show the migrations this instance still owes, in the order they must run.

Synopsis

wikitool migrate status [--json]

Options

  --json      Print the chain as JSON
  -h, --help  Show this message and exit.

Examples

tools/wikitool migrate status
tools/wikitool migrate status --json

Behaviour

Shows every required migration whose migrates_to lies in (kb_version, VERSION], in the order it must run.
offered migrations are listed separately above the chain: they never block, never count as owed, and are bounded by the applied ledger rather than by kb_version - taking one does not move the version.
With a release stamp present, also reports which shipped files this instance has since edited (from the per-file sha256 in .wikitool-release.json) - which says whether an offer may be copied over or has to be reconciled by hand. Without a stamp that question is reported as unanswerable rather than answered.
Exits 1 only when the content version is undeclared (.wikitool-kb.json missing) or VERSION is unreadable; it never guesses the content's shape.
Read-only, safe to retry freely, and exempt from the Iteration Budget Gate.

Properties

Changes files: no
Idempotent: yes
Atomic: Read-only
Counts toward the session call budget: no
Can reach the network: no

Exit codes

0 - success
1 - .wikitool-kb.json is missing - the content version is undeclared
1 - VERSION is unreadable

See also

wikitool migrate done - records one as applied
instructions/migrate-corpus.md - how a migration is run
instructions/upgrade-instance.md - where an upgrade checks this

`migrate verify`

Compare kb/ against a git revision on the invariants a content migration must not change.

Synopsis

wikitool migrate verify --from <rev> [--path P ...] [--expect-body-change] [--json] [--fail-on-error]

Options

  --from <str>          Git revision to compare against, e.g. HEAD  [required]
  --path <str>          Limit to a subtree, repeatable (e.g. kb/concepts)
  --expect-body-change  Also report pages whose body did not change at all
  --json                Print the diff as JSON
  --fail-on-error       Exit 1 if any invariant changed
  -h, --help            Show this message and exit.

Examples

tools/wikitool migrate verify --from HEAD
tools/wikitool migrate verify --from HEAD --path kb/concepts --expect-body-change

Behaviour

Compares kb/ against the revision --from on the invariants a content migration must not change: wikilink and citation counts (not sets), footnote definitions, H1, structural frontmatter, and the count of generated-region marker pairs.
Pages are matched by title, not path, so a page move (or move --reconcile) relocated compares as itself - reported separately as moved - rather than as a removed-and-added pair.
Reports added and removed pages without failing on them.
--expect-body-change additionally flags a page whose body did not change at all.
Not migration-specific: worth running after any bulk rewrite.
Exits 0 whatever it finds unless --fail-on-error is passed.
Read-only and exempt from the Iteration Budget Gate.

Properties

Changes files: no
Idempotent: yes
Atomic: Read-only
Counts toward the session call budget: no
Can reach the network: no

Exit codes

0 - success
1 - Only with --fail-on-error: an invariant changed
1 - --from is not a revision in this repository

See also

instructions/migrate-corpus.md - where a migration runs this
wikitool lint - the single-revision checks

`migrate done`

Record one migration as applied, advancing kb_version in .wikitool-kb.json.

Synopsis

wikitool migrate done <version> [--pages N] [--dry-run]

Options

Arguments:
  version  The migration's target version, e.g. 1.4.0  [required]

Options:
  --pages <int>  How many pages it touched
  --dry-run      Report without writing
  -h, --help     Show this message and exit.

Examples

tools/wikitool migrate done 7.0.0 --pages 42 --dry-run
tools/wikitool migrate done 7.0.0 --pages 42

Behaviour

Records one migration as applied, advancing kb_version in .wikitool-kb.json to its target.
Refuses any required version that is not the next link in the chain.
An offered migration is recorded in the applied ledger without moving kb_version and with no ordering rule applied. Re-recording one already in the ledger is a no-op, not an error - idempotent and safe to repeat.
Not idempotent for a required migration: it advances the chain.
--dry-run reports without writing.

Properties

Changes files: yes
Idempotent: no
Atomic: Yes - single file write
Counts toward the session call budget: yes
Can reach the network: no

Exit codes

0 - success
1 - Unknown version, no .wikitool-kb.json, or nothing outstanding
1 - A required version that is not the next link in the chain

See also

wikitool migrate status - the order to apply them in
instructions/migrate-corpus.md - the migration procedure

`migrate baseline`

Declare kb_version once, for an instance predating .wikitool-kb.json.

Synopsis

wikitool migrate baseline <version> [--force]

Options

Arguments:
  version  The shape this instance's content is already in  [required]

Options:
  --force     Overwrite an existing declaration (not a substitute for `done`)
  -h, --help  Show this message and exit.

Examples

tools/wikitool migrate baseline 6.2.0

Behaviour

Declares kb_version once, for an instance predating .wikitool-kb.json.
Refuses to overwrite an existing declaration without --force. Advancing the version after a migration is migrate done, which checks the chain; this command does not.
Safe to re-run with the same version.

Properties

Changes files: yes
Idempotent: yes
Atomic: Yes - single file write
Counts toward the session call budget: yes
Can reach the network: no

Exit codes

0 - success
1 - Unparseable version
1 - A declaration already exists and --force was not passed

See also

wikitool migrate done - advances the version after a migration
wikitool migrate status - what is owed from the declared version