Land a change across several repositories¶

Some features don't fit in one repo: an API in repo A, the SDK that calls it in repo B, the docs in repo C. Shipping them needs to be coordinated — A and B must land together, or in a defined order, never half-done. TOVIO's answer is the meta-change: a group of per-repo changes that land atomically or in sequence.

A coordinated saga, not a distributed transaction

tovio meta is built: members in repositories checked out on your machine pass the same pre-land gate tovio land uses, and members attached with --forge land through an authenticated PREPARE / COMMIT / RELEASE saga on their home Forge, which drives that Forge's normal proposal-land path. Progress is persisted after each member, so a partial outcome is resumable. What TOVIO does not do is a two-phase commit across object stores — see the warning below.

Most teams never need this

TOVIO's path-scoped permissions make a monorepo a first-class option — one repo, per-team path access, and no cross-repo primitive required. Meta-changes are for organizations that keep repos separate by choice or constraint. If you can monorepo, that's the simpler answer.

Why a primitive at all¶

Git has no native answer here. Submodules are widely disliked, and hand-coordinating several pull requests across repos is error-prone — someone always lands one and forgets the other. A meta-change leverages TOVIO's stable Change IDs: it references each member by its per-repo Change ID, so rebases and amendments in any member repo never break the linkage.

Group your changes¶

Create a meta-change with a land strategy — atomic is the default — then attach one (or more) change per repo. The name you give is the meta-change's local id; a member's repository defaults to the current one, and --repo <path> names another local checkout.

$ tovio meta create pagination
✓ Created meta-change `pagination` (atomic land) — attach members with `tovio meta attach pagination <chg:…>`

$ tovio meta attach pagination chg:a3f7b2 --repo ../api
$ tovio meta attach pagination chg:c91d04 --repo ../sdk
$ tovio meta attach pagination chg:e22a18 --repo ../docs
✓ Attached chg:e22a18 (repo ../docs) to `pagination` — 3 member(s)

A member that lives on another Forge is attached with its home Forge and the lane the proposal targets (--target defaults to main):

$ tovio meta attach pagination chg:c91d04 --forge forge.example.dev:7743 --cert relay-cert.der --target main

A meta-change is local working-copy state, like locks and isolation pins — it never enters the synced object store. tovio meta list shows the ones recorded in this repo.

Track the combined state¶

tovio meta show reports the group's strategy and state, and each member's landability — the same conflict-free predicate tovio land applies. A member whose repo is not reachable from this machine and has no Forge endpoint reports unknown, never a false landable:

$ tovio meta show pagination
Meta-change: pagination  [atomic land · open]
  • chg:a3f7b2 [../api]
      landability: landable (blake3:9c1e…)
  • chg:c91d04 [../sdk]
      landability: landable (blake3:44d0…)
  • chg:e22a18 [../docs]
      landability: conflicted — 1 unresolved conflict(s)

Proposal approvals and required checks are not evaluated by show; each member's Forge enforces them at land time, because COMMIT runs that Forge's ordinary proposal-land gate.

Land atomically — all or nothing¶

With the default atomic strategy every member must pass its pre-land gate — PREPARE completes for every member — before any member lands. If any one fails, the whole meta-land is refused and nothing moves.

$ tovio meta land pagination
✓ `pagination` is now fully landed — 3 member(s) landed this land

If a member isn't ready, you get a clear refusal naming the blocker — and nothing lands:

$ tovio meta land pagination
• `pagination` remains open — no member could be landed this land
  halted at chg:e22a18 (repo ../docs): 1 unresolved conflict(s)

Land in sequence¶

When one repo must land after another — B can't ship until A's contract is published — create the meta-change with the sequenced strategy. Members land one at a time in attachment order; a failure halts the sequence at that member and leaves the group partially_landed, with a resume prompt.

$ tovio meta create pagination --sequenced
$ tovio meta land pagination
⚠ `pagination` is partially_landed — 1 member(s) landed this land, 2 outstanding
    outstanding: chg:c91d04
    outstanding: chg:e22a18
  resume the rest with `tovio meta resume pagination` (re-attempts only the outstanding members)
  halted at chg:c91d04 (repo ../sdk): 1 unresolved conflict(s)

Fix the blocker, then tovio meta resume pagination re-attempts only the members not yet landed. It is idempotent — resuming a fully-landed meta-change simply reports it as landed.

\"Atomic\" is a coordinated gate, not a distributed transaction

Honest limitation: TOVIO does not do a two-phase commit across separate object stores. Atomic means every member is verified landable (PREPARE), then the members are landed (COMMIT). If the process crashes mid-land, any already-landed members stay landed and the rest stay open (partially_landed). That state is recoverable with tovio meta resume — it never corrupts any repo. True cross-store atomicity would require a shared transaction log TOVIO deliberately avoids.

Reviewing a meta-change¶

Review stays per repository: each member is proposed and reviewed in its own repo, under that repo's clearance — so a protected file in one member renders redacted just as it would in a single-repo review — and each repo's lane protection applies to its own member. There is no separate meta-level proposal object today.

Recap¶

tovio meta create <name> [--atomic | --sequenced] then tovio meta attach <name> <chg:…> [--repo <path>] [--forge <addr> --cert <der> --target <lane>] — group per-repo changes.
tovio meta show <name> — strategy, state (open / partially_landed / landed), and each member's landability; tovio meta list — every meta-change in this repo.
tovio meta land <name> — atomic (all-or-none) by default; sequenced lands in attachment order and halts on failure as partially_landed; tovio meta resume <name> finishes the rest.
"Atomic" is a coordinated PREPARE/COMMIT saga, not a distributed transaction — crashes are recoverable, never corrupting.
Members are tracked by stable Change ID, so rebases and amendments don't break the linkage.

Where to next¶

The per-repo gates each member must pass: lane protection.
How redacted review works for protected files: propose and review.
Why a monorepo may be the simpler choice: the core concepts.

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure