Promotions

Promotions preview or copy authored definitions from one set to another, usually as part of an environment flow such as dev -> staging -> production.

Basic command#

Preview#

Run this command to preview what would change:

$ npx messagevisor promote --from=dev --to=staging

Apply#

By default, promote previews what would change and does not write files. Add --apply when you are ready to update the destination set:

$ npx messagevisor promote --from=dev --to=staging --apply

Filtering#

Use filters to promote only a subset of content:

$ npx messagevisor promote --from=dev --to=staging --includeMessages="checkout*"
$ npx messagevisor promote --from=dev --to=staging --locale=nl-NL
$ npx messagevisor promote --from=dev --to=staging --target=web

Conflict handling#

Use --conflicts to handle conflicts when both sets have content for the same slot:

$ npx messagevisor promote --from=dev --to=staging --conflicts=source --apply
$ npx messagevisor promote --from=dev --to=staging --conflicts=destination --apply
$ npx messagevisor promote --from=dev --to=staging --conflicts=fail --apply

Audit output#

Use --audit to generate an audit file for the promotion:

$ npx messagevisor promote --from=dev --to=staging --apply --audit=markdown

What promotion moves#

Promotions can move any promotable authored entity, including:

• locales
• attributes
• segments
• targets
• messages
• tests

The exact moved shape depends on:

• the source and destination sets
• filters you pass
• conflict behavior
• promotable flags in the content

Preview and apply#

Use preview first:

$ npx messagevisor promote --from=dev --to=staging
$ npx messagevisor promote --from=dev --to=staging --showUnchanged

Recommended pattern:

1. preview the promotion
2. review the output
3. run again with --apply
4. lint and test the destination set

Restricting allowed flows#

Use promotionFlows in messagevisor.config.js when you want to restrict which directions are allowed:

module.exports = {
  sets: true,
  promotionFlows: [
    { from: "dev", to: "staging" },
    { from: "staging", to: "production" },
  ],
};

This keeps promotion behavior aligned with your release model.

Useful filters and options#

Typical options include:

• --target=<target>
• --locale=<locale>
• --includeMessages=<pattern>
• --excludeMessages=<pattern>
• --excludeOverrides
• --conflicts=source|destination|fail
• --apply
• --audit=json|markdown
• --allowEmpty
• --showUnchanged

Use filters when you want to promote:

• one target's message set
• only certain locales
• only a subset of messages

Conflict handling#

Promotion is not a blunt file copy. It can merge nested authored structures.

Conflict handling matters because:

• arrays may need structural merging
• translations and tests can diverge between sets
• different teams may have changed the same content independently

Policy choices:

• source - values from the source set win when both sets have content
• destination - values in the destination set are preserved when both sets have content
• fail - the promotion stops and reports a conflict error instead of making any change

$ npx messagevisor promote --from=dev --to=staging --conflicts=source --apply
$ npx messagevisor promote --from=dev --to=staging --conflicts=destination --apply
$ npx messagevisor promote --from=dev --to=staging --conflicts=fail --apply

Use fail when you want promotions to stop instead of making a precedence choice for you. This is safest in automated pipelines where silent overwrites would be hard to notice.

Audit output#

Use --audit when you want a durable promotion record:

$ npx messagevisor promote --from=dev --to=staging --apply --audit=markdown

This is helpful for:

• release review
• change approval
• tracing exactly what moved between sets

For product and localization stakeholders, the audit file is often easier to review than a raw Git diff because it is scoped to the promotion operation: what moved, from where, and into which destination set.

After promotion#

A good post-promotion sequence is:

$ npx messagevisor lint --set=staging
$ npx messagevisor test --set=staging
$ npx messagevisor build --set=staging

That turns promotion into a reviewed, validated step instead of a blind file mutation.

Human review#

Promotions are still Git changes. A healthy production flow usually includes:

• a pull request that contains the promoted files
• a catalog link for the destination set
• promotion audit output when the change is release-sensitive
• lint, test, and build checks for the destination set

This gives engineers confidence that the artifact builds, and gives non-engineering reviewers a readable view of what will become live.

Edge cases and behavior notes#

Promotions respect configuration constraints#

If a flow is not allowed by promotionFlows, the command fails clearly rather than guessing what you meant.

Promotions and targets are different concerns#

Promotions move authored content between sets. Targets still decide how that content is sliced into runtime artifacts after the move.

Related#

• Sets
• Configuration
• Deployment
• CLI
• Catalog