Update Workflow

This guide explains how to check for updates and apply them to your inherited repositories.

Workflow Overview

The update workflow follows a check-review-apply pattern:

1. Check for available updates
2. Review changes before applying
3. Apply with confidence

Checking for Updates

See if any inherited repositories have newer versions available:

common-repo check --updates

This compares your pinned refs against available tags in each repository. Output shows:

• Current ref for each inherited repo
• Available newer versions
• Whether updates are compatible (minor/patch) or breaking (major)

Reviewing Changes

Before updating refs, preview what would change in your files:

# Update refs without applying
common-repo update --dry-run

# See file differences after updating
common-repo diff

The --dry-run flag shows which refs would change without modifying your config file.

Applying Updates

Compatible Updates (Safe)

Update to the latest compatible versions (same major version):

common-repo update

This updates minor and patch versions only. For example, v1.2.0 might update to v1.3.5 but not v2.0.0.

Latest Updates (Breaking)

Include breaking changes when updating:

common-repo update --latest

This updates to the newest available version regardless of major version changes.

Skip Confirmation

For scripting or CI, skip the confirmation prompt:

common-repo update --yes

Selective Updates

Update only specific upstream repos using glob patterns:

# Update repos matching a pattern
common-repo update --filter "github.com/org/*"

# Update multiple patterns (OR logic)
common-repo update --filter "*/*/ci-*" --filter "*/*/linter-*"

# Combine with other flags
common-repo update --filter "github.com/org/*" --latest --dry-run

Patterns match against the repository URL (with scheme stripped) combined with the optional path. For example:

Pattern examples:

• github.com/org/* - repos under a specific org
• */*/ci-* - any repo with “ci-” prefix
• github.com/** - all GitHub repos

Complete Example

A typical update session:

# Step 1: Check what's available
common-repo check --updates

# Step 2: Preview ref changes
common-repo update --dry-run

# Step 3: Apply ref updates to config
common-repo update

# Step 4: Preview file changes
common-repo diff

# Step 5: Apply file changes with dry-run first
common-repo apply --dry-run

# Step 6: Apply for real
common-repo apply

Semantic Versioning

common-repo understands semantic versioning when comparing refs:

The --compatible flag (default) follows semver: patch and minor updates are safe, major updates may contain breaking changes.

Tips

Pin to specific versions for production stability:

- repo:
    url: https://github.com/your-org/configs
    ref: v2.1.0  # Pinned version

Use branches for development or always-latest behavior:

- repo:
    url: https://github.com/your-org/configs
    ref: main  # Tracks branch HEAD

Check updates in CI to catch drift:

# Fails if updates are available
common-repo check --updates || echo "Updates available"