cub unit conflicts

Show, apply, or dismiss a unit's outstanding merge conflicts

Synopsis

Work with the parts of the last merge's patch that were not applied.

A merge reports a conflict for every change it could not make: a path the downstream owns (Subtracted), a path the downstream protects (ProtectedPath), a path that could not be located in this unit (UnresolvedPath), and each downstream change displaced by an upstream deletion (DeleteShadowed). The merged data is correct as it stands -- a conflict says what the source wanted to change and couldn't.

Guarded is one of those, for a value the source wanted to write at a path carrying a guard -- a recorded reason its value is what it is -- that the merge was not cleared for. The conflict names the guard, so the report says which reason stopped it rather than only that something did.

GuardWithheld is the other half, and is about a guard rather than a value: the source changed the guards at a path and this merge was not cleared for the guards this unit already has there, so the guard change did not propagate. Reported because a base that adds a policy exception and a variant that silently does not receive it is exactly the failure guards exist to prevent, and the data merging cleanly would otherwise hide it. Applying one writes the guard change rather than any configuration data.

ExclusiveWithheld is one of those, for a change that could not be made because this unit owns a field mutually exclusive with it -- the source switched a volume to a secret and this unit had already chosen an emptyDir. Applying it performs the switch. ExclusiveCleared reports the opposite: the source's change applied and a value this unit had was removed to make room for it, because keeping both is a resource that will not apply. It carries the removed value.

The conflicts stay on the unit until they are dealt with, so a merge that dropped half its patch is still visible afterwards rather than only in the response of the request that ran it. The next merge replaces them with its own, and a merge that lands cleanly clears them.

With no flags this lists the outstanding conflicts. --apply replays the changes they withheld, with every path eligible so nothing filters them out a second time. --dismiss drops them without touching the configuration data. Both act on every outstanding conflict unless --reason, --path, or --resource narrows the selection, and both take --dry-run, which reports what the request would do and writes nothing.

Applying changes the configuration data, so the unit goes through the same trigger pass as any other change and may pick up an ApplyGate. --wait, on by default, waits for that pass to finish before returning.

Examples:

  # What did the last merge fail to apply?
  cub unit conflicts my-unit

  # What would taking the upstream's value do to this unit?
  cub unit conflicts my-unit --apply --dry-run -o mutations

  # Apply the upstream changes that were withheld because this unit owns the path
  cub unit conflicts my-unit --apply --reason Subtracted

  # Accept the current state and stop reporting them
  cub unit conflicts my-unit --dismiss

  # Which units in the space merged with paths the patch could not locate?
  cub unit list --where "Conflicts.*.Reason = 'UnresolvedPath'"

cub unit conflicts <unit-slug> [--apply | --dismiss] [--reason REASON] [--path PATH] [--resource NAME] [flags]

Options

      --apply             apply the changes the selected conflicts withheld
      --dismiss           drop the selected conflicts without changing the configuration data
      --dry-run           dry run mode: report what --apply or --dismiss would do without writing anything
  -h, --help              help for conflicts
  -o, --output string     Output format. One of: json, yaml, name, wide, mutations, jq=<expr>, yq=<expr>, custom-columns=<spec>
      --path string       select conflicts at this path
      --quiet             No default output.
      --reason string     select conflicts with this reason: Subtracted, DeleteShadowed, ProtectedPath, UnresolvedPath, ExclusiveWithheld, or ExclusiveCleared
      --resource string   select conflicts on this resource, by name
      --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
      --space string     space to operate in, by slug or UUID. Omitted, a list or bulk operation spans the organization and a single entity is named as <space>/<slug>

cub unit conflicts