Multi-set workflows
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=stagingApply#
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 --applyFiltering#
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=webConflict 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 --applyAudit output#
Use --audit to generate an audit file for the promotion:
$ npx messagevisor promote --from=dev --to=staging --apply --audit=markdownWhat promotion moves#
Promotions can move any promotable authored entity, including:
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 --showUnchangedRecommended pattern:
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:
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 contentdestination- values in the destination set are preserved when both sets have contentfail- 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 --applyUse 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=markdownThis 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=stagingThat 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.

