Skip to main content

pin

CLI reference

Description

Pin a workspace repository revision by identity (not by path). Pins are stored under .esysrepo and overlay the manifest on the next sync so CI can force one leaf project to a known commit without editing the committed manifest (ADR-0021).

Exactly one identity selector is required when setting or clearing a pin:

  • --name: Manifest repository name
  • --project: Forge project path (e.g. GitLab CI_PROJECT_PATH)
  • --url: Repository clone URL
  • --ci: Detect identity and revision from the CI environment

When setting a pin with --name / --project / --url, --rev is required. With --ci, revision (and identity) come from the CI environment unless --rev overrides the SHA.

Usage

esysrepo pin [options ...]

Options

Available options:

  • --name NAME: Manifest repository name to pin
  • --project PATH: Forge project path (e.g. CI_PROJECT_PATH)
  • --url URL: Repository clone URL
  • --rev REV: Revision to pin (SHA preferred; required unless --ci, --list, or --clear with show semantics)
  • --ci: Detect identity and revision from the CI environment
  • --list: List all pins
  • --clear: Clear a pin (combine with an identity selector or --ci)
  • --rev-set NAME: Native manifest revision-set name
  • --folder / -f PATH: Workspace folder (common option; default is the current directory)

Examples

Pin by manifest name:

esysrepo pin --name esysrepo/esysrepo --rev a1b2c3d4e5f6

Pin from CI (identity + SHA from the environment):

esysrepo pin --ci

List pins:

esysrepo pin --list

Clear a pin:

esysrepo pin --clear --name esysrepo/esysrepo