Skip to content

UC009: Updating a Repository

Overview

repo update regenerates all generator-owned files in an already initialized repository to the latest version provided by the generator. The project configuration is read exclusively from .repo.yaml — no CLI arguments determine the project type. Developer-owned files (source code, README.md, tests, migrations, Makefile.local) are never modified.

Goal

  • What problem does this use case solve?
  • The generator evolves over time: guidelines are refined, CI/CD templates are improved, Makefile targets are updated. repo update propagates these improvements to existing repositories without requiring a full re-initialization.
  • It keeps all projects on a consistent baseline, reducing technical debt and simplifying maintenance.
  • What does it explicitly NOT do (scope boundary)?
  • Does not change the project type, language, or CI system — these are fixed in .repo.yaml.
  • Does not modify developer-owned files (source code, README.md, tests, migrations, Makefile.local).
  • Does not create a backup — Git is the backup. Requires a clean working tree as a precondition.
  • Does not handle merge conflicts; the developer reviews and resolves changes via git diff.

Preconditions

  • .repo.yaml exists in the target repository (created by repo init).
  • The Git working tree is clean (no uncommitted or untracked changes).

Options

Flag Short Default Description
--targetpath -t current directory Path to the repository to update
--dry-run false List files that would change without writing them

--dry-run is not a safety net (use git restore for that) but enables read-only drift detection — useful in CI pipelines to assert that a repository is up to date.

Transaction Boundary

No transaction. Files are written sequentially. On error, only a subset of files may have been updated; the developer uses git restore to roll back.

Further Details

For main success scenario, extensions (alternate flows), and BDD scenarios be referred to the corresponding feature file (BDD specification and executable test).