repos.list Reference

The repos.list file lists the repositories (and optionally branches) that repos clone will clone. Place it in the root of your project directory.

Basic Format

Each line is one repository:

owner/repo

Lines starting with # are comments and are ignored.

Cloning a Specific Branch

Append @branch to clone only that branch:

owner/repo@develop

Use @branch without a repository name to clone only that branch from the most recently listed repository (or the current repository if none has been listed yet):

owner/repo
@feature-x
@bugfix-123

If owner/repo is listed first, @feature-x and @bugfix-123 use that repository as the remote. If the file begins with bare @branch lines and no repository has been listed yet, the current local repository’s own remote is used as the fallback.

Hugging Face Repositories

Use the hf: prefix to download Hugging Face repositories:

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

hf://... and mixed-case HF prefixes are normalized to canonical hf:<path> format. In HF entries, @revision can be a branch, tag, or commit. Bare @revision lines use the same fallback semantics as Git entries.

Hugging Face entries require huggingface-cli:

pip install huggingface_hub[cli]

Custom Target Directory

Add a name after the repository to clone into a different directory:

owner/repo my-data

Worktrees

Add --worktree to an @branch line to create a Git worktree instead of a separate clone:

owner/repo
@feature-x --worktree
@bugfix-123 --worktree

This produces a full clone of owner/repo plus two worktrees.

If the file begins with a bare @branch --worktree line and no repository has been listed yet, the current local repository’s remote is used as the fallback source, and the worktree is placed alongside the current repository.

Visibility

Control whether new repositories are created as public or private:

owner/repo --public
owner/other-repo --private

Global Flags

Place a flag on its own line (with nothing else except optional comments) to apply it to every repository in the file. The entire file is scanned for global flags before any cloning begins, so placement does not matter — a global flag at the bottom of the file applies to repositories listed above it.

Flag	Effect
--public	Create all repositories as public by default
--private	Create all repositories as private by default (the default)
--codespaces	Configure Codespaces authentication for all repositories
--worktree	Use worktrees instead of separate clones for all @branch lines
--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 for all clone operations
--force	On a global-only flag line, make the other flag(s) on that line override conflicting per-line flags

Precedence rules:

1. repos clone CLI flags override repos.list global flags.
2. Per-line flags override both CLI and repos.list global flags by default.
3. repos clone --force ignores per-line flag overrides entirely.
4. A global line such as --fetch-single --force or --worktree --force forces that global setting to override conflicting per-line flags.

Per-line --public/--private flags always override the global default.

--fetch-single, --fetch-all-deferred, --fetch-all, and --depth <n> may also be specified per-line to override global clone behavior for a specific repository or @branch line.

Pipeline-only per-line skip

Use --dont-run on a repository line or @branch fallback line to keep that entry in the workspace but exclude it from repos run script mode:

myorg/backend
myorg/generated-data --dont-run
@staging --dont-run

--dont-run is ignored by clone/workspace/setup commands.

Example

--private        # default visibility for new repos
--codespaces     # set up Codespaces auth for all repos

myorg/backend
myorg/frontend@develop
@staging --worktree        # worktree of frontend at staging branch
myorg/docs --public        # override: create docs repo as public

After repos clone, the parent directory looks like:

workspace/
├── my-project/            # your project (contains repos.list)
├── backend/
├── frontend-develop/
├── frontend-staging/      # worktree
└── docs/