clone Command

What It’s For

Recover missing local repositories without re-adding them to workspace configuration, or complete a partial coordinated worktree after creating only some child repositories.

What It Does

Detects repositories already defined in .arashi/config.json that are missing on disk.
Lets you choose which missing repositories to clone in interactive mode.
Clones all missing repositories in non-interactive mode with --all.
Inside a coordinated worktree, adds missing child repositories as worktrees on the current branch when a local source repository is available.
Falls back to normal remote clone behavior outside coordinated worktrees or when no source repository is available.
Reconciles managed ignore rules before materializing a configured repository path.
Skips repositories that are already present locally.

Usage

aw clone [options]

Key Options

--all clone all missing configured repositories without selection prompts.
--base <branch> override the effective base for every selected missing child.
--repo-base <repository=branch> override one selected child; the option is repeatable.
-j, --json output machine-readable results for non-interactive clone runs.

Examples

# Pick from missing repositories interactively
aw clone

# Clone every missing configured repository
aw clone --all

# Complete a partial coordinated worktree from inside it
cd .arashi/worktrees/feature/auth-refresh
aw clone

# Clone every missing repository from a release base
aw clone --all --base release

# Override one selected child's release base
aw clone --all --base release --repo-base api=api/release

# Clone every missing repository and emit JSON
aw clone --all --json

Choosing bases for clone

Configured clone shares root baseBranch and repos.<name>.baseBranch with configured create. For a one-off run, --base <branch> overrides every selected child and repeatable --repo-base <repository=branch> overrides named children. Exact precedence is repository CLI, invocation CLI, repository config, workspace config, then legacy omitted behavior. @meta is invalid for clone because clone selects missing children only.

From the main configured workspace, a child with an effective base is cloned on that local branch tracking origin/<base>. With no effective policy, clone preserves the remote default branch behavior. Inside a coordinated worktree, the current coordinated target branch remains the checked-out branch. If that target is missing, the target is created from the effective base and materializes the child on the coordinated target branch, not the base branch; an existing target is reused without reset, rebase, or ancestry assertion. The same alignment applies when no canonical source child is available and materialization comes from the configured remote.

Arashi validates malformed, duplicate, unknown, and unselected overrides plus every selected base before managed-ignore or filesystem mutation. A missing base reports every affected selected child and no selected repository is cloned or materialized. Human output identifies each requested branch and stable source. When any selected repository has an effective base policy, JSON success reports the complete ordered selected set at data.base, using repository-cli, cli, repository-config, workspace-config, or legacy-omitted. When every selected repository uses legacy-omitted behavior, data.base is absent. Preflight failures report affected records at error.details.repositories.

Each JSON base record includes repositoryName, normalized requestedBranch when one applies, and source. CLONE_BASE_PREFLIGHT_FAILED records include repositoryName, requestedBranch, source, the configured gitUrl, and reason, but no resolved ref/OID or attemptedRefs. Selector errors use BASE_BRANCH_POLICY_INVALID with issues at error.details.issues.

Notes

clone only works on repositories already configured in the workspace.
If no repositories are missing, the command exits successfully with no clone action.
From inside a coordinated worktree, clone uses the current branch for child worktrees so completed repositories stay aligned with the parent worktree.
If the matching source repository cannot be found locally, clone uses the configured remote URL instead.
If you’re in a non-interactive environment, use --all.
JSON mode does not prompt; combine --json with explicit selection flags such as --all.
Before cloning, Arashi honors any effective tracked, repository-local, or global rule. If a safe managed path is still unignored, it uses the stored clone-local scope or the repository-local default; scope none warns without writing.
Repeated reconciliation is idempotent. If no clone is retained after failure, ignore and preference changes are restored; when some selected repositories succeed, required reconciliation is retained and reported with the partial result.
A fresh clone has no shared ignore preference because arashi.ignoreScope is clone-local. It therefore defaults to the common repository’s local exclude file and does not unexpectedly change tracked .gitignore.
When a configured remote already uses SSH, clone keeps every configured SSH URL byte-for-byte. An SSH preference can still convert a conventional HTTPS remote to SSH, but Arashi never converts an SSH URL to HTTPS because an alias has no trustworthy automatic HTTPS mapping.

Troubleshooting SSH Remotes

Git and OpenSSH resolve the host and authenticate. Arashi does not read, resolve, or edit ~/.ssh/config, identity files, or keys, and it does not run a separate SSH connectivity probe. If an alias cannot be resolved or authenticated, review the underlying Git error and test the same remote with Git in your local environment.

For configuration shared across machines, commit a canonical remote URL. A machine that needs a local SSH alias can rewrite that canonical host globally with Git, for example:

git config --global url."git@work-github:".insteadOf "[email protected]:"

Use global rather than repository-local Git configuration because the rewrite must be available before a missing repository is cloned.

In a multi-repository clone, a failed alias is reported for that repository and Arashi continues with the remaining selected repositories. Successful clones are retained under the existing partial-success contract. For an add failure, Arashi uses the existing rollback boundary described in the add command reference.

Agent Notes

Use aw status --json or aw status --verbose to discover missing configured repositories before completing a partial workspace.
Prefer aw clone --all --json when automation should complete every missing child repository without prompts.
Inspect managed ignore warnings and final changed/restored state in JSON results instead of editing Git ignore files directly.

clone requires configured mode and persisted child repositories. From standalone mode, run ordinary aw init to upgrade; see the One Repository.