Skip to content

cub variant sync

cub variant sync

Give one variant the configuration and links of another

Synopsis

Give the target variant's units the source variant's configuration, and the target the source's links it does not have.

Promotion carries a change down from a variant's upstream. Two variants of the same base are not each other's upstream, so promotion cannot carry one's configuration to the other; this does. Each variant is named as / or by its space slug.

Units are paired by slug. Each pair is merged as one squashed diff of the source unit from its first revision to its head: everything that has happened to it since it was made. A unit made empty and then given its content has an empty first revision, so that is the whole of its configuration. For a clone, whose first revision is what its upstream gave it, it is the source variant's own changes and the upgrades it took, and what the clone started with stays as the target has it: compare with --dry-run --include-config-data. The merge is like any other: a path the target protects keeps the target's value, and the change is reported as a conflict.

A source unit the target does not have is cloned from the source unit's upstream first, as promotion clones a unit its upstream added, and moved into the target's namespace when the target space records one; then it is merged like the rest. One with no upstream is skipped.

Then each of the source's links that the target has no link of the same slug for is copied: from the target's unit of the same slug, and to the target's unit of the same slug when the link is within the source variant, or to the same unit when it leads out of it. A copy keeps what the link resolves and its UpstreamLinkID, and starts with no merge history or delete gates. UpgradeUnit links are not copied: each is its unit's upstream, which this does not change. A link the target has a link of the same slug for is left alone, and the target's links the source does not have are kept.

--protect protects the paths each merge wrote, so that a later upgrade from the target's upstream does not write the upstream's values back over them. It is a step of its own after each merge, since a merge is itself subject to protection and cannot protect what it writes. A resource the merge added whole has no path of its own, and is protected as a whole; the Protected column counts it as one.

The table says, for each unit, what was done and whether its configuration now says what the source's does: the same documents with the same values, whatever the order of their keys or the style of their lists, for YAML and JSON, and the same text for other formats. A path the target protects keeps it from matching.

Examples: 

  # What syncing staging-2 to staging would do
  cub variant sync app/staging app/staging-2 --dry-run

  # Sync it, protecting what the sync changes against the base's later upgrades
  cub variant sync app/staging app/staging-2 --protect --change-desc "Sync from staging"

  # Each unit's changes, path by path
  cub variant sync app/staging app/staging-2 --dry-run -o mutations

cub variant sync <source-variant> <target-variant> [flags]

Options

      --change-desc string    change description recorded on the units the sync writes
      --dry-run               report what the sync would do without changing anything
  -h, --help                  help for sync
      --include-config-data   return the configuration each merge produces, or with --dry-run would produce, as ConfigData in structured output (-o json, -o yaml, -o jq=...)
  -o, --output string         Output format. One of: json, yaml, name, wide, mutations, jq=<expr>, yq=<expr>, custom-columns=<spec>
      --protect               protect the paths each merge writes, so a later upgrade from the target's upstream does not overwrite them
      --quiet                 No default output.
      --timeout string        completion timeout as a duration with units, such as 10s or 2m (default "10m0s")
      --verbose               Detailed output, additive with default output
      --wait                  wait for completion (default true)

Options inherited from parent commands

      --context string   The context to use for this command
      --debug            Debug output

SEE ALSO