rcheckout

name	rcheckout
description	Recursively checkout a branch on the root repo + every nested git submodule, including detached HEAD or wrong-branch repos. Use when the user types `/rcheckout <branch>` or asks to "switch all submodules to <branch>" / "rcheckout <branch>". For monorepos with deeply nested submodules (e.g. myteam-alpha-root tree). Wraps `scripts/recursive-checkout.sh` from the atmux repo.

rcheckout — recursive submodule checkout

Switch the current repo and every nested submodule onto <branch>. Handles detached HEADs by attaching to the branch; creates the branch from origin/<branch> if it exists only on the remote.

Invocation

The user passes the target branch as the argument: /rcheckout myteam-alpha-dev.

Implementation

bash "$(git rev-parse --show-toplevel)/scripts/recursive-checkout.sh" "$BRANCH"

Where $BRANCH is the user-supplied argument. The script resolves the repo root from $PWD.

Branch arg is mandatory. Per ADR-035, there is no "config-mode" default that reads .gitmodules — the branch identifies the calling member, which .gitmodules cannot capture.

After running

Report the summary line (=== summary: N repo(s) failed... ===) and any per-repo WARN: lines. If all green, one-line confirmation. If any failures, show the affected repos so the user can decide whether to create the missing branches.

Related

• /rpull <branch> — recursive git pull --ff-only origin <branch> after checkout.
• /rpush <branch> — recursive git push origin <branch> (leaves-first ordering).

Operator-facing report format — attention + verdict markers

Per [[feedback-unambiguous-attention-and-verdict]] and the coordination-plugin precedent.

Verdict-derivation rules:

• ✅ every repo (root + submodules) ended up on <branch> cleanly.
• ⚠ most repos switched but some emitted WARN: (branch missing locally/remotely on specific submodules, attached from detached-HEAD with caveat).
• 🔴 root failed, OR ≥1 repo couldn't switch (branch missing everywhere, dirty working-tree blocking checkout).
• 👁 attaches when operator must decide: create the missing branch locally, stash dirty tree, accept partial-state.

Examples:

✅ /rcheckout myteam-beta-dev — root + 4 submodules switched cleanly

👁 ⚠ /rcheckout myteam-beta-dev — root switched, 1 submodule WARN
WARN: apps/foo/_charity-svc — branch missing local+origin, stayed on master
👁 Operator: create `myteam-beta-dev` in that submodule, or skip if intentional