# 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> --labels <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

# Repeat --labels to combine multiple selectors across occurrences.
atmos vendor diff --labels tier=1 --labels 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.
- **`--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, repeatable)**
  Diff every component whose stack 
  `metadata.labels`
   match ALL of these 
  `key=value`
   or 
  `key:value`
   pairs — comma-separated within one occurrence, and/or repeated for more (
  `--labels tier=1 --labels cost-center=platform`
  ). Composes with 
  `--stack`
   and 
  `--tags`
  . Mutually exclusive with 
  `--component`
  .
- **`--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. The command performs a temporary clone (removed afterward); large
repositories take proportionally longer. Private repositories are not yet supported.
:::