# Preview changes with `kix diff`

Use `kix diff` to preview how the rendered cluster differs from the resources
currently running in Kubernetes. The command reads live state but does not
apply changes.

## Compare desired and live resources

Start from a cluster that matches what is deployed. Kix compares only the
fields it applied, so an unchanged cluster reports nothing and exits 0:

<Command {...diffClean} />

Now change the production message in the cluster definition and run the same
command:

<Command {...diffChange} />

The report names the ConfigMap you edited and shows the changed value. The
resources marked "via dependency" have no content change of their own. Their
identity hash moves because they depend on the ConfigMap, so Kix will
re-stamp them on the next deploy.

## Read the diff

The report is grouped by package, and each line tells you something different:

* A package marked added or removed appears on only one side.
* A resource marked `~` has a content change, shown as a diff of the fields
  that differ.
* A resource marked "via dependency" has no content change of its own. Only
  its identity hash moved, because something it depends on changed.
* A cluster-level group collects resources that belong to no package, such as
  namespaces and custom resource definitions.
* An activation line names the deployment record this change would create.

Read the packages you edited first, then the dependent resources, which tell
you how far the rollout reaches. A non-empty diff exits with status 2, which
lets CI tell a change from a clean comparison.

## Select the flake and context

By default, Kix evaluates the current directory and reads the current kubectl
context. Set either input explicitly when needed:

<Command
  commands={[
  "kix diff how-to-application --flake ./infrastructure --context kind-kix-demo",
]}
/>

The flake supplies the desired manifests. The Kubernetes context supplies the
live manifests being compared.

## Produce review-friendly output

Select Markdown output when attaching the result to a pull request or change
review:

<Command expandable {...diffMarkdown} />

Redirect it into a file for the job to publish:

<Command commands={["kix diff how-to-application --output markdown > kix-diff.md"]} cwd="kix-examples/" />

Use JSON when another program will process the result:

<Command commands={["kix diff how-to-application --output json > kix-diff.json"]} cwd="kix-examples/" />

## Confirm a clean result

After deploying the intended change, run the command again. A clean result
confirms that Kix does not currently plan another content change.

`kix diff` compares the fields Kix applied. Use `kix drift` when you need to
know who else owns a field and what they changed.

:::note[Related guides]
See [Generate PR-review Markdown from `kix diff`](/docs/v0.1/how-to/policy-ci-and-compliance/generate-pr-review-markdown-from-kix-diff/)
for CI usage and [Reconcile drift](/docs/v0.1/how-to/operate-a-cluster/reconcile-drift/)
when live resources need to be reapplied.
:::