compare Command

Show what changes would be made without applying them (dry-run).

Syntax

koji-habitude compare [OPTIONS] DATA [DATA...]

Description

The compare command performs the same processing as apply but without making any changes to the Koji hub. It provides detailed change analysis and dependency reporting, making it ideal for:

  • Previewing changes before applying them

  • Validating your YAML definitions

  • Understanding what would change in your Koji instance

  • Checking for phantom dependencies

In addition to the change report that this command produces, it will also display a resolver report, which will include any dependency references that are used but not defined in the data set.

The command will:

  1. Load all templates and data files

  2. Resolve dependencies between objects

  3. Connect to the Koji hub instance

  4. Compare local definitions with remote state

  5. Display a summary of differences

  6. Show resolver report (including any phantom dependencies)

This is a safe, read-only operation that never modifies the Koji instance.

Options

DATA

One or more directories or files containing YAML object definitions. Required. Can be repeated multiple times.

--templates PATH, -t PATH

Location to find templates that are not available in DATA directories. Can be repeated multiple times.

--recursive, -r

Search template and data directories recursively for YAML files.

--profile PROFILE, -p PROFILE

Koji profile to use for connection. Default: koji.

--show-unchanged

Show objects that don’t need any changes in the summary output. By default, only objects with differences are shown.

Examples

Compare a data directory against Koji, using templates from the templates directory, and object definitions from the data directory:

koji-habitude compare -t templates/ data/

Show all objects including unchanged ones:

koji-habitude compare --show-unchanged data/

Use Cases

  • Pre-Flight Check: Always run compare before apply to review changes

  • Validation: Verify your YAML definitions are correct before deployment

  • Change Review: Review proposed changes as part of a code review process

  • Dependency Analysis: Identify missing dependencies (phantoms) before applying

Exit Codes

  • 0 - No phantom dependencies detected

  • 1 - Phantom dependencies found (objects referenced but not defined)