---
title: "30.8 Migration: una migrate"
url: https://una-lang.org/en/docs/spec/30-packages/8-migration-una-migrate/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/30-packages.md
---

# 30.8 Migration: una migrate

`una --json migrate --dry-run` of a package `hello` of edition `0.3`, with a module and no `verification.lock`, prints one `una.migrate/1` document (rule 8):

```json
{
  "schema": "una.migrate/1",
  "dry_run": true,
  "written": [],
  "removed": [],
  "name": {"from": "hello", "to": "hello"},
  "edition": {"from": "0.3", "to": "0.4"},
  "default_lock": true,
  "comments_not_carried": [],
  "ita_una": "ita hello\n  version 0.1.0\n  edition 0.4\n",
  "ita_lock": "-- Written by `una ita`; do not edit.\nlock 1\n\nsolver\n  encoding \"una-smt-1\"\n  name \"z3\"\n  version \"5.1.0\"\n  logic \"QF_UFLIA\"\n  steps 5000000\n  seed 0\n",
  "diagnostics": []
}
```

1. **Edition 0.4 and later are not written in `una.toml`.** `una.toml` naming `edition = "0.4"`, or (ADR 0139) `edition = "0.5"`, is U7002 at the value, with the repair `una migrate`; the package is still checked in the edition it names. No released `una` accepted that form, so this changes no released form (ADR 0122 Question 8.1).
2. **`una migrate [path] [--dry-run] [--name <name>]`** moves the package at `path`, `.` by default, from `una.toml` and `verification.lock`, of any edition from `0.1` to `0.5`, to `ita.una` and `ita.lock` of edition `0.4`, or of edition `0.5` when `una.toml` names it, since no migration lowers an edition, and nothing else: a directory that already has `ita.una`, or that is not a package with `una.toml` and `src/`, is a usage error (exit code 2).
3. **What it maps.**

   | `una.toml` / `verification.lock` | `ita.una` / `ita.lock` |
   | --- | --- |
   | `[package] name = "events-example"` | `ita events_example`: `-` becomes `_`; a name that is still not a package name needs `--name` |
   | `version`, `edition`, `profile` | head lines; `edition` becomes `0.4`, or stays `0.5`; a version that is not `MAJOR.MINOR.PATCH` is refused; `profile` is written when it is `systems` |
   | `[labels] categories` | `labels`, one per line |
   | `[trusted] modules` | `trusted` |
   | `[escape_budget] checked_per_module` | `escapes`, `checked per module <n>`, when not 0 |
   | `[boundaries]` | `boundaries`, with `may` lines |
   | `[contracts]` | `contracts`, the clause strings as lines |
   | `[run] entry`, `grants` | `run`, `entry`, `grants` with one line per spec, as `files "data/" read, write` |
   | `[run] max_memory` | `max_memory`, in `run` after `entry` |
   | `verification.lock` | the `solver` section of `ita.lock`; the release's default when the package has none |

   A text is written with `"`, `\`, `{` and `}` escaped, and every control or bidirectional character as `\u{…}`.
4. **Comments.** A run of comment lines of `una.toml` directly before a table header or a key is carried, as `--` comments, above the line it becomes. Every other comment is listed in the output, with its line.
5. **Refusals.** An invalid `una.toml`, other than its edition `0.4` or `0.5`, or an invalid `verification.lock` is refused, with each problem printed, and nothing is written (exit code 2).
6. **Writing.** It writes `ita.una` and `ita.lock`, each through a temporary file and a rename, rewrites each module in the canonical form of edition `0.4` (`spec/15 §2`), which edition `0.5` keeps, reading it with the keywords of the edition it writes (#1744), then removes `una.toml` and `verification.lock`. The canonical form of edition `0.4` wraps long lines, which earlier editions never do (ADR 0125, amendment of 2026-10-25): a module that differs from that form is written through a temporary file and a rename, and listed in `written` by its path. For a module that was canonical in its own edition, the rewrite changes only white space. A module with a syntax error in that edition has no canonical form and is left as it is. The rewrite is one check of the package, as `una fmt` does.
7. **The clashes of the edition.** It then checks the package, with its modules rewritten, at tier 0 in the edition of the `ita.una` it wrote, and prints every diagnostic the change of edition causes, those the package has in that edition and not in its own, with their repairs, such as a function named `within` (U0103). It applies none: `una fix` does that. Its exit code is 0: the diagnostics are the next steps of the migration.
8. **Output.** `--dry-run` prints the two files and the diagnostics, and writes nothing. `--json` prints one document, `una.migrate/1`: `schema` first, then `dry_run`, `written`, `removed`, `name` (`from`, `to`), `edition` (`from`, `to`), `default_lock`, `comments_not_carried` (`line`, `text`), `ita_una` and `ita_lock` (the files' texts with `--dry-run`, `null` otherwise), and `diagnostics`.
