Skip to content

dft migrate

Update face YAML to the current release. Use it after upgrading Dataface when a dashboard reports that it uses older YAML syntax. The command recognizes syntax from the YAML shape; face YAML does not carry a version: field.

dft migrate [OPTIONS] [PATH]...

Arguments

Argument Description
PATH... Face YAML file or directory to migrate. Omit paths to scan the project root.

Options

Flag Description
--dry-run Report the files that would change without writing them.
--project-dir PATH Project root for resolving paths.

Preview and Apply a Migration

Start with a dry run, review the change in your working tree, then rerun without --dry-run to write it.

dft migrate --dry-run
dft migrate
git diff

For a targeted migration, pass a face file or a directory:

dft migrate faces/revenue.yml
dft migrate faces/

The command prints a summary of updated files, files that already use current syntax, and files that need manual repair. It exits with status 1 when any file cannot be migrated; files with independent, successful migrations are still written.

What Gets Rewritten

Dataface keeps immutable schemas for supported YAML grammars and checks them from newest to oldest. It uses the newest grammar the document matches, then applies every safe, structural migration between that grammar and the current one. A file that already matches the current grammar is left unchanged—even if it was created with an older Dataface release.

For example, a retired chart color key can move into the current style block:

# Before
charts:
  revenue:
    color: category

# After
charts:
  revenue:
    style:
      color: category

This recognition is not a claim about when you wrote the file. It only answers which supported grammar its current shape satisfies.

Manual Repair

dft migrate only performs declared, lossless structural changes. It stops for a file when a change would alter meaning, discard information, or conflict with an already-present destination key. The error names the path and migration that need attention. Make that repair yourself, then run dft validate to check the result.

dft migrate faces/revenue.yml
# Repair the path reported by the command.
dft validate faces/revenue.yml

The command does not make backups or offer rollback. Keep your dashboards in version control and use git diff to review the rewrite; use git revert if you need to undo a committed migration.