# atmos vendor diff

Show the changes between two versions (tags, branches, or commits) of a vendored Git
component, without a local checkout — useful for assessing impact before adopting a
new version.

## Usage

```shell
atmos vendor diff --component <name> [--type <type>] [--from <ref>] [--to <ref>] [--diff-file <path>]
atmos vendor diff --tags <tag1>,<tag2> [options]
atmos vendor diff --stack <stack> [--labels <key>=<value>] [options]
atmos vendor diff --labels <key>=<value> [options]
atmos vendor diff --labels <key1>=<value1>,<key2>=<value2> [options]
```

`--from` defaults to the component's current pinned version and `--to` defaults to the
latest tag. A missing or extra leading `v` is tolerated, so `2.0.0` resolves a `v2.0.0`
tag and vice versa.

If `--component` isn't declared in `vendor.yaml` — or no `vendor.yaml` exists — Atmos falls
back to the component's own `component.yaml`/`component.yml` manifest (found under
`Components.<type>.BasePath/<component>/`), matching
`atmos vendor pull`'s existing precedence:
`vendor.yaml` wins whenever it declares the component.

At least one selector is required: `--component` for a single target, `--tags` on its own, or
`--stack`/`--labels` for every component resolved from a stack (composable with each other, like
`atmos vendor pull`'s own `--stack`/`--labels`).
`--tags` is a separate, independent filter that composes with either base selector — or
stands on its own, filtering every component whose `vendor.yaml` source declares any of the
given tags — narrowing the diffed set to only components whose declared tags also match; a
component with no `vendor.yaml` entry (the common case for `--stack`) has no tags to match
and is excluded by a non-empty `--tags` filter. `--component` and `--stack`/`--labels` remain
mutually exclusive with each other. When a selector resolves to more than one component,
every match is diffed in turn under its own `## <component>` heading; a per-component
failure doesn't stop the rest.

## Examples

```shell
# Diff the current pinned version against the latest tag.
atmos vendor diff --component vpc

# Diff two specific versions.
atmos vendor diff -c vpc --from 1.0.0 --to 2.0.0

# Restrict the diff to a single file.
atmos vendor diff -c vpc --from 1.0.0 --to 2.0.0 --diff-file variables.tf

# Diff every component whose vendor.yaml source declares a given tag.
atmos vendor diff --tags networking

# Diff every component in a stack, or matching stack metadata.labels.
atmos vendor diff --stack dev-us-west-2
atmos vendor diff --labels tier=1

# Combine multiple selectors in one comma-separated --labels value.
atmos vendor diff --labels tier=1,cost-center=platform

# Diff a stack's components, narrowed further by declared vendor.yaml tags.
atmos vendor diff --stack dev-us-west-2 --tags networking
```

## Flags

- **`--component` / `-c` (string)** — The component to diff. Mutually exclusive with `--stack`/`--labels`. Composes with `--tags` (narrows to this component only if its declared `vendor.yaml` tags also match).
- **`--tags` (string)** — Diff only components whose `vendor.yaml` source declares any of these comma-separated tags (matches any). An independent filter: composes with `--component` or `--stack`/`--labels` to narrow further, or stands on its own.Environment variable: `ATMOS_VENDOR_TAGS`
- **`--stack` / `-s` (string)** — Diff every component belonging to the specified stack. Composes with `--labels` to narrow further, and with `--tags` to filter by declared source tags. Mutually exclusive with `--component`.
- **`--labels` (string)** — Diff every component whose stack `metadata.labels` match ALL of these `key=value` or `key:value` pairs — comma-separated in one flag value (`--labels tier=1,cost-center=platform`). Composes with `--stack` and `--tags`. Mutually exclusive with `--component`.Environment variable: `ATMOS_VENDOR_LABELS`
- **`--from` (string)** — Starting ref (tag, branch, or commit). Defaults to each component's current pinned version.
- **`--to` (string)** — Ending ref. Defaults to the latest tag.
- **`--diff-file` (string)** — Restrict the diff to a single file path within the component.
- **`--type` / `-t` (string, default `terraform`)** — Component type (`terraform`, `helmfile`, or `packer`), used when falling back to a per-component `component.yaml`, and to scope a `--stack`/`--labels` selection.
- **`--file` (string, default `./vendor.yaml`)** — The vendor manifest to read sources from (imports are followed).

:::note
Git sources only: `git::` sources, supported hosting-provider URLs, and explicit `git://` or `ssh://` repository URLs are recognized. Plain `file://` paths retain local-file semantics. The command performs a temporary clone (removed afterward); large
repositories take proportionally longer. Private repositories are not yet supported.
:::

## Try it out

### demo-vendoring

Copy the example into a new directory and make it your own:

```shell
atmos init examples/demo-vendoring
cd demo-vendoring
```

Compare the `weather` component's `main.tf` between two Atmos releases. Requires Git and network access. This file is unchanged between these releases, so no diff output is expected.

```shell
atmos vendor diff --component weather --from v1.200.0 --to v1.201.0 --diff-file examples/demo-library/weather/main.tf
```

- [Installation guide](/install)
- [Explore the example](/examples/demo-vendoring)
- [Initialization and repository settings](/cli/commands/init#examples-and-source-directories)