Diff & Impact Analysis

Compare traceability data between different states of a project or needs.json files, similar to how Git compares commits.

Quick Start

Compare two needs.json files:

ubc diff --needs old.json --needs new.json      # first is baseline (old), second is new

Compare two projects:

ubc diff --project old_path --project new_path  # first is baseline (old), second is new

Compare project with needs.json:

ubc diff --project old_path --needs new.json    # first is baseline (old), second is new
ubc diff --needs old.json --project new_path    # order is always: old, new

Note

Order matters: The first input is always treated as the baseline (old state), and the second as the new state. This applies to all comparison modes.

Git-based comparisons:

# Run in current directory (expects ubproject.toml)
ubc diff git                                    # working directory vs HEAD
ubc diff git --staged                           # staging area vs HEAD
ubc diff git main develop                       # compare two branches

# Specify a project path in the repository
ubc diff git --project path/to/project          # working directory vs HEAD
ubc diff git main develop --project path/to/project

# Compare a needs.json file in the repository
ubc diff git --needs path/to/needs.json         # working directory vs HEAD
ubc diff git v1.0.0 v2.0.0 --needs path/to/needs.json

Output Formats

Results can be displayed in different formats:

Console output (default):

ubc diff --needs old.json --needs new.json

HTML report:

ubc diff --needs old.json --needs new.json --format html --outpath report.html
ubc diff --needs old.json --needs new.json --format html --html-theme dark --outpath report.html

Available themes: auto (default), light, dark

Understanding Impact Analysis

Impact analysis tracks how changes propagate through requirement links. When a need changes, the analysis follows incoming and outgoing links to identify all potentially affected needs.

How it works:

  1. Identifies new, removed, or changed needs

  2. Follows links from/to these needs up to the configured depth

  3. Builds chains showing the impact path (e.g., REQ-1 → implements → STORY-5 → depends_on → EPIC-2)

  4. Reports all affected needs with their link relationships

Use cases:

  • Understand the scope of a requirement change

  • Identify downstream tests affected by a feature change

  • Track upstream requirements when implementation changes

  • Generate change impact reports for reviews

Commands Reference

Basic Diff Command

Compare two files or projects:

# Compare two needs.json files
ubc diff --needs file1.json --needs file2.json

# Compare two projects
ubc diff --project path1 --project path2

# Mix: compare project with needs.json
ubc diff --project path --needs file.json

Git Diff Command

Compare Git references (branches, tags, commits):

# Compare working directory with HEAD (default: current directory)
ubc diff git
ubc diff git --project path

# Compare staging area with HEAD
ubc diff git --staged

# Compare two Git references
ubc diff git main develop
ubc diff git v1.0.0 HEAD
ubc diff git abc123 def456

# Work with needs.json in repository
ubc diff git --needs path/to/needs.json
ubc diff git main develop --needs path/to/needs.json

Impact Analysis Options

Track how changes affect linked requirements:

# Enable impact analysis
ubc diff --needs old.json --needs new.json --impact

# Configure impact tracking
ubc diff --needs old.json --needs new.json \
  --impact \
  --impact-depth 2 \
  --impact-direction both \
  --impact-max-chains 50

Options:

  • --impact — Enable impact analysis

  • --impact-depth N — Follow links up to N levels (default: 1)

  • --impact-direction {incoming|outgoing|both} — Link direction (default: both)

  • --impact-max-chains N — Max chains per changed need (default: 20, 0=unlimited)

Filter Options

Control which needs and fields are compared. All filter options can be used multiple times.

Need Type Filters:

# Only compare specific need types
ubc diff --needs old.json --needs new.json --allow-type req --allow-type story

# Exclude specific need types
ubc diff --needs old.json --needs new.json --deny-type internal

Field Filters:

# Only compare specific core fields (id, title, type, content, status, tags, links)
ubc diff --needs old.json --needs new.json --allow-core title --allow-core status

# Exclude core fields from comparison
ubc diff --needs old.json --needs new.json --deny-core tags

# Filter extra/custom fields
ubc diff --needs old.json --needs new.json --allow-extra my_field
ubc diff --needs old.json --needs new.json --deny-extra temp_field

Link Type Filters:

# Only compare specific link types
ubc diff --needs old.json --needs new.json --allow-link implements --allow-link depends_on

# Exclude link types from comparison
ubc diff --needs old.json --needs new.json --deny-link obsoletes

Note

Allow-filters (--allow-*) and deny-filters (--deny-*) are mutually exclusive for each category. Use allow-filters to start with an empty set and add specific items. Use deny-filters to start with all items and remove specific ones.

Common Workflows

Review changes before committing:

# See what changed in your working directory
ubc diff git --impact

# Check what's staged for commit
ubc diff git --staged --impact

Compare feature branches:

# Compare your branch against main
ubc diff git main feature/my-feature --impact --format html --outpath review.html

Release impact analysis:

# See all requirements affected between versions
ubc diff git v1.0.0 v2.0.0 \
  --impact \
  --impact-depth 3 \
  --allow-type requirement --allow-type specification

Track test impact:

# Find which tests are affected by requirement changes
ubc diff git main HEAD \
  --impact \
  --impact-direction outgoing \
  --allow-link tests \
  --deny-core tags

Compare documentation states:

# Compare exported needs.json files from different builds
ubc diff --needs old-build/needs.json --needs new-build/needs.json \
  --impact \
  --format html --html-theme light --outpath comparison.html