Skip to main content

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.

atmos vendor diff --help

Usage​

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​

# 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. The command performs a temporary clone (removed afterward); large repositories take proportionally longer. Private repositories are not yet supported.

Try it out​

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

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.

atmos vendor diff --component weather --from v1.200.0 --to v1.201.0 --diff-file examples/demo-library/weather/main.tf
Explore the example →Initialization and repository settings