repos clone

repos clone reads your repos.list file and clones all listed repositories into your current location, and adds them to .gitignore. It is the simplest way to get started — no GitHub account or token required for public repositories.

Basic Usage

repos clone

Options

Flag	Description
`-f <file>`	Use a different list file (default: `repos.list`)
`--worktree`	Make every `@branch` line use a worktree by default
`--fetch-all-deferred`	(Default) Fast `--single-branch` clone; wildcard refspec restored immediately
`--fetch-single`	Keep restricted single-branch refspec (CI/CD or metered connections)
`--fetch-all`	Full clone — all remote branches downloaded upfront
`--depth <n>`	Opt-in shallow clone depth (must be a positive integer)
`--force`	Ignore per-line flag overrides and enforce CLI flags
`--create`	Create and push missing branches referenced in `repos.list`
`--debug`	Enable debug output to stderr
`--debug-file [file]`	Enable debug output to file (auto-generate temp if no path given)

# Use a custom list file
repos clone -f my-repos.list

# CI/CD pipeline — strict single-branch isolation
repos clone --fetch-single

# Download everything upfront
repos clone --fetch-all

# Shallow clone (opt-in)
repos clone --depth 1

# Force all @branch lines to be worktrees, ignoring per-line flag overrides
repos clone --worktree --force

Default Fetch Behaviour

By default (--fetch-all-deferred), repos clone performs a fast --single-branch clone and then immediately restores the standard wildcard fetch refspec (+refs/heads/*:refs/remotes/origin/*). This means:

Initial clone is as fast as a --single-branch clone.
After the clone, running git fetch inside any cloned repo transparently downloads the rest of the history, and git checkout <other-branch> works without any manual config changes.

Use --fetch-single to opt out — for example in CI/CD pipelines where you only ever need one branch and want to minimise network traffic.

Flag Precedence

By default, CLI flags override repos.list global flags, and per-line flags are the most specific setting so they win over both. Add --force on the CLI to ignore per-line flag overrides entirely. Inside repos.list, a global-only line such as --fetch-single --force or --worktree --force forces that global setting to override conflicting per-line flags.

Missing Branches

When a requested branch does not exist on the remote, repos clone now fails by default and tells you to rerun with --create.

Use --create when you explicitly want repos clone to create and push missing branches for owner/repo@branch or @branch entries.

Hugging Face Repositories

You can include Hugging Face repositories in repos.list using the hf: prefix:

hf:datasets/huggingface/stack
hf:datasets/huggingface/stack@main

These entries are downloaded with huggingface-cli, so install it first:

pip install huggingface_hub[cli]

Fallback @branch / revision behavior is supported for HF entries in the same way as Git entries in repos.list.

Repository Layout

Repositories are cloned to the parent of your current directory:

workspace/
├── my-project/          # your project (contains repos.list)
├── backend/             # cloned from myorg/backend
├── frontend-develop/    # cloned from myorg/frontend@develop
└── docs/                # cloned from myorg/docs

What’s in repos.list?

repos.list lists the repositories (and optionally branches) to clone. See the repos.list reference for the full format, including cloning specific branches, creating worktrees, and setting per-repo visibility.

Authentication

repos clone delegates all network operations to the system git binary — it has no built-in credential store of its own. Authentication is therefore whatever git has available for the remote’s protocol.

SSH remotes (`git@host:…` or `ssh://…`)

Git uses your SSH key, either via an SSH agent (SSH_AUTH_SOCK) or through ~/.ssh/config. No token is needed.

HTTPS remotes

Git uses whatever credential helper is configured (git config --get credential.helper). Common options include Git Credential Manager, osxkeychain, wincred, or a custom script. This works for any host, including GitHub. Set one up with your hosting platform’s instructions; repos clone will work automatically once git can authenticate.

For GitHub specifically, two additional shortcuts are available:

# Option 1 — gh CLI (registers itself as a git credential helper automatically)
gh auth login

# Option 2 — personal-access token via environment variable
export GH_TOKEN="your_personal_access_token"

Note on GH_TOKEN: git does not read GH_TOKEN directly. It only prevents interactive prompts when gh is also configured as git’s credential helper (via gh auth login or gh auth setup-git), in which case gh reads GH_TOKEN from the environment and supplies the token to git on request.

Public repositories on any host can be cloned without any credentials.

Going further

repos clone only clones repositories. For IDE integration, two additional commands are available:

Generate a VS Code workspace: repos workspace
Configure GitHub Codespaces authentication: repos codespace

→ VS Code integration