How It Works

directus/default/
  schema/            # the schema, one JSON file per collection
  data/              # configuration records, one JSON file per resource
  id_map.json        # which target record each committed record became

Resolve identity 1 of 1: directus_roles source "Editor" — sr1 matches multiple target records
  Use "Editor" — t1           (Same synced values as source; only the ID differs)
  Use "Editor" — t2           (icon: source "edit", target "star")
  Create a separate record    (Adds one record; leaves every existing match unchanged)
  Abort the push              (Applies no remote changes)
``` Your answer lands in the identity map, so each question is asked exactly once. That's why the map belongs in git: commit it whenever a push changes it, and teammates and CI inherit every decision already made.

One map file serves any number of instances. Internally it is keyed by source and target URL, so pushing the same files to staging and to production writes two independent sets of mappings; neither overwrites the other. Deleting the file is safe to the extent that matching starts over: named records re-match by their identifying fields, and records without one can duplicate on the next push. The same applies to repointing a profile at a new domain: the mappings are keyed by URL, so the old URL's decisions no longer apply and matching starts fresh for the new one.

## How a push applies

A push applies in two phases, schema first, and begins by showing you the full plan and asking (unless you pass `--yes`).

1. **Schema.** Before applying, the push re-checks that the target's schema still matches what the plan was computed against. If someone changed the target between preview and apply, the push stops rather than apply a stale plan.
2. **Data.** Configuration records import in a single server-side transaction once the schema is in place.

The two phases are not one transaction. If the data import fails after the schema applied, the target holds the new schema and the old configuration, and the CLI says so plainly:

The guidance is the same in every partial-failure case: run `d6s sync diff` to see where the target actually stands, then push again. A re-run applies only what is still missing, and a completed push re-run reports "nothing to push" after verifying that against the target, not assuming it.

## Push modes and deletions

A push mode answers one question: what happens to things that exist on the target but not in your files?

- **`merge`** (the default) creates and updates, and never deletes. Not in the schema phase, not in the data phase.
- **`add`** only creates records; it never touches an existing one. Its schema phase behaves exactly like `merge`: the mode only changes what happens to data.
- **`mirror`** makes the target match the files exactly, which means deleting what the files no longer contain, within whatever scope the files cover.

Deleting always requires its own explicit consent, separate from confirming the push. Interactively, a mirror push lists what would be lost and asks you to type the profile name. Non-interactively it requires the `--dangerously-allow-delete` flag; `--yes` never authorizes a deletion. The gate is a backstop as well as a policy: even if a supposedly additive push somehow carried a deletion, it would still be refused without consent.

Because a mirror push makes the target match the files _exactly_, run it against a freshly pulled state. A mirror from stale files applies the stale state, including deleting things that only look obsolete because the files are old.

## The version gate

Schema changes require the files' Directus version and the target's version to match exactly, patch release included, because the server refuses cross-version schema diffs; historically, some patches change the schema format.

`--allow-version-drift` asks the server to proceed anyway and warns you loudly; the CLI never translates schema between versions. Projects configured with `"schema": false` skip the schema phase and this gate entirely.

## The safety model

The rules above add up to a small set of promises, each of which you can watch hold in the [Quickstart](/guides/environment-sync/quickstart):

- **`pull` is read-only on the source.** Every request it makes is a read; it changes nothing on the instance it snapshots. (The one exception: a profile that authenticates with a saved login session refreshes that session when it is close to expiring.)
- **`diff` applies nothing.** The schema comparison is a preview, and the data plan comes from the target server dry-running the import inside a transaction and rolling it back, so the plan is the server's own answer, not a client-side guess.
- **Deletions are gated.** Only `mirror` deletes, always behind its own consent, and `--yes` never covers it.
- **Identity is never guessed.** An ambiguous record match prompts in a terminal and refuses in CI.
- **Stored secrets never enter your repository.** Built-in secret columns and fields marked concealed, hashed, or encrypted are stripped at export, with [one warned exception](/guides/environment-sync/secrets-and-limitations#the-one-blind-spot).
- **Failures are loud.** Hand-edited files, cut-short exports, version mismatches, and unreachable instances stop the command with a named error instead of degrading silently. An export the source itself left incomplete is marked as such and refused at mirror push.