Skip to main content

sync

CLI reference

Description

Typically this is the second command after init. It downloads new changes and updates the working tree in your local workspace. With no project paths, it synchronizes all projects in the manifest; optional path arguments limit sync to those folders.

When you run esysrepo sync, this is what happens for the manifest:

  • The first time sync runs on a local workspace, nothing should happen to the manifest repository because it should already be up to date

  • If the git repository holding the manifest has local changes, esysrepo aborts

  • If the git repository is detached, esysrepo aborts

  • If no branch was specified and the current HEAD can be fast-forwarded, the manifest repository is fast-forwarded; otherwise sync aborts

  • If a branch was specified and it exists, that branch is checked out; otherwise the same process as when no branch was specified is followed

And for every git repository in the manifest that is set to be synced:

  • If the repository is missing from the local workspace, it is cloned. If a branch was specified and exists in that repo, that branch is checked out

  • The update starts by checking for local changes. If changes are found, esysrepo aborts

  • If no branch was specified:

    • If the repository is detached, abort

    • Fetch the repository

    • Fast-forward the local HEAD when possible; otherwise abort

  • If a branch was specified and exists, that branch is checked out. Otherwise handle it as if no branch had been specified

Git submodules of each project follow manifest sync-s unless overridden by --recurse-submodules / --no-recurse-submodules (ADR-0032).

Usage

esysrepo sync [options ...] [path ...]

Options

Available options:

  • --force-sync: Overwrite an existing git directory if it needs to point to a different object directory. WARNING: this may cause loss of data. Accepted by the CLI but not implemented yet (sync warns and continues without it)
  • --job / -j N: Number of projects to fetch simultaneously (default 1)
  • --groups / -g LIST: Comma-separated list of groups to synchronize (no spaces)
  • --branch / -b BRANCH: Branch to check out across targeted repositories when it exists; repositories without that branch follow the normal sync path
  • --rev-set NAME: Native manifest revision-set name to apply for this sync
  • --alt / -a: Use the alternative address (alt_addr) for git repositories
  • --multi / -m: Use captured branches for changes spanning multiple repositories
  • --tui: Fullscreen Compact RepoSync progress dashboard (requires an interactive TTY and a build with FTXUI / Conan with_tui). Falls back to console progress when stdout is not a TTY
  • --tui-demo: Like --tui, plus a timed on-screen "Press Tab to cycle views" banner (also ESYSREPO_TUI_DEMO=1). Useful for scripted demos / GIF recordings
  • --phase-timing: Log per-repo GitHelper phase timings in milliseconds (overrides ESYSREPO_SYNC_PHASE_TIMING)
  • --no-phase-timing: Disable phase timing logs even if ESYSREPO_SYNC_PHASE_TIMING is set
  • --recurse-submodules: Also sync Git submodules of each project (overrides manifest sync-s)
  • --no-recurse-submodules: Do not sync Git submodules even if sync-s is set. When both recurse flags are present, --no-recurse-submodules wins
  • --folder / -f PATH: Workspace folder to sync (common option; default is the current directory)

Positional path arguments, if any, limit sync to those project folders.

Examples

To sync the manifest and all git repositories with four parallel jobs:

esysrepo sync -j4

To sync with the Compact progress dashboard:

esysrepo sync --tui -j4

To sync with the dashboard and the demo Tab hint banner:

esysrepo sync --tui-demo -j4

To sync only the manifest and a given list of groups:

esysrepo sync -g grp1,grp2,grp3

To apply a native revision-set while syncing:

esysrepo sync --rev-set develop -j4

To also sync Git submodules for this run:

esysrepo sync --recurse-submodules -j4

To sync only specific project folders:

esysrepo sync src/esysrepo src/esysbase

Details

Submodule recursion for sync follows Google Repo–compatible sync-s on <project> (and defaults), with CLI overrides --recurse-submodules / --no-recurse-submodules. See product ADR-0032.