Python Package

The repos Python package is a thin wrapper around the repos Go CLI. Every wrapper call dispatches to the installed repos binary.

Installation

pip install git+https://github.com/MiguelRodo/repos.git

Or from a local clone:

git clone https://github.com/MiguelRodo/repos.git
cd repos
pip install .

System requirements: repos and git must be available on your PATH.

End-to-End Workflow

Step 1 — Create a `repos.list` file

Place a repos.list file in your project directory listing the repositories you want to manage (one per line):

myorg/data-curation
myorg/analysis
myorg/documentation

See the repos.list reference for the full syntax — branch pinning, worktrees, visibility flags, and more.

Step 2 — Clone repositories

from repos import clone

clone()

This reads repos.list and clones everything to the parent directory of your current location.

clone() also supports Hugging Face entries in repos.list using the hf: prefix (for example, hf:datasets/org/data@dev). This requires huggingface-cli (pip install huggingface_hub[cli]).

clone() supports explicit fetch modes:

from repos import clone

clone(fetch_mode="deferred")  # default: fast clone, then restore wildcard refspec
clone(fetch_mode="single")    # strict single-branch isolation
clone(fetch_mode="all")       # full clone (all branches upfront)
clone(depth=1)                # opt-in shallow clone

Step 3 — Open in your IDE (optional)

Generate a VS Code multi-root workspace file:

from repos import workspace

workspace()

Step 4 — Run a pipeline

Once the repositories are cloned, run a script inside each one:

from repos import run

run()          # executes run.sh in every repo

See run() below for all options.

API Reference

`install_cli()`

Print OS-appropriate instructions for installing the repos CLI globally, and optionally run the installer.

from repos import install_cli

install_cli(
    run=False  # if True, run the installer automatically
)

Parameters

Parameter	Type	Default	Description
`run`	`bool`	`False`	If `True`, attempt to run the installer automatically

Details

The Python package requires the repos binary to be installed on your system PATH. This helper prints installation instructions and can run the installer on Linux/macOS.

Returns: None

Examples:

from repos import install_cli

# Print installation instructions for your OS
install_cli()

# Print instructions AND run the installer
install_cli(run=True)

`bundled_cli_version()`

Return the repos CLI version targeted by this package.

from repos import bundled_cli_version

bundled_cli_version()

Returns: str — the targeted CLI version string (e.g. "2.0.0").

Examples:

from repos import bundled_cli_version

print(bundled_cli_version())  # e.g. "2.0.0"

`installed_cli_version()`

Return the version of the repos CLI installed on the system PATH, or None if not found.

from repos import installed_cli_version

installed_cli_version()

Returns: str or None — the system-installed CLI version, or None.

Examples:

from repos import installed_cli_version

ver = installed_cli_version()
if ver is None:
    print("repos CLI is not installed on this system.")
else:
    print(f"Installed CLI version: {ver}")

`workspace()`

Generate or update the VS Code multi-root workspace file.

from repos import workspace

workspace(
    file=None,            # path to a custom list file (default: repos.list)
    debug=False,          # write debug output to stderr
    debug_file=None,      # write debug output to a file (True = auto-name, or pass a path)
)

Parameters

Parameter	Type	Default	Description
`file`	`str`	`None`	Path to repos list file (default: `repos.list`)
`debug`	`bool`	`False`	Print debug output to stderr
`debug_file`	`bool` or `str`	`None`	Write debug output to a file

Returns: subprocess.CompletedProcess

Examples:

from repos import workspace

# Generate workspace from default repos.list
workspace()

# Use a custom list file
workspace(file="my-repos.list")

For the full description, see the VS Code integration guide.

`codespace()`

Configure GitHub Codespaces devcontainer.json.

from repos import codespace

codespace(
    file=None,            # path to a custom list file (default: repos.list)
    devcontainer=None,    # path(s) to devcontainer.json (str or list[str])
    permissions=None,     # "default", "all", or "contents"
    tool=None,            # deprecated; ignored
    debug=False,          # write debug output to stderr
    debug_file=None,      # write debug output to a file (True = auto-name, or pass a path)
)

Parameters

Parameter	Type	Default	Description
`file`	`str`	`None`	Path to repos list file (default: `repos.list`)
`devcontainer`	`str` or `list[str]`	`None`	Path(s) to `devcontainer.json`
`permissions`	`str`	`None`	`"default"`, `"all"`, or `"contents"`
`tool`	`str`	`None`	Deprecated; ignored
`debug`	`bool`	`False`	Print debug output to stderr
`debug_file`	`bool` or `str`	`None`	Write debug output to a file

Returns: subprocess.CompletedProcess

In script mode, repos listed with --dont-run are skipped. Hugging Face dataset/model entries are also skipped automatically.

Examples:

from repos import codespace

# Configure with default devcontainer path
codespace()

# Specify a devcontainer.json path
codespace(devcontainer=".devcontainer/devcontainer.json")

# Multiple devcontainer paths
codespace(devcontainer=[".devcontainer/devcontainer.json",
                        ".devcontainer/prebuild/devcontainer.json"])

For the full description, see the VS Code integration guide.

`run()`

Execute a script inside each cloned repository.

from repos import run

run(
    file=None,              # path to a custom list file (default: repos.list)
    script=None,            # script to run in each repo (default: run.sh)
    include=None,           # repo name(s) to include
    exclude=None,           # repo name(s) to skip
    ensure_setup=False,     # run setup() before executing scripts
    skip_deps=False,        # skip install-r-deps
    dry_run=False,          # print what would run without executing
    verbose=False,          # verbose logging
    continue_on_error=False # keep running after a failure
)

Parameters

Parameter	Type	Default	Description
`file`	`str`	`None`	Path to repos list file (default: `repos.list`)
`script`	`str`	`None`	Script file to run in each repo (default: `run.sh`)
`include`	`str` or `list[str]`	`None`	Only run in these repos
`exclude`	`str` or `list[str]`	`None`	Skip these repos
`ensure_setup`	`bool`	`False`	Clone repos first (via `repos clone`)
`skip_deps`	`bool`	`False`	Skip R dependency installation
`dry_run`	`bool`	`False`	Preview without executing
`verbose`	`bool`	`False`	Verbose logging
`continue_on_error`	`bool`	`False`	Continue past failures

Returns: subprocess.CompletedProcess

Examples:

from repos import run

# Run the default script (run.sh) in every repo
run()

# Run a custom script
run(script="build.sh")

# Only run in specific repos
run(include=["backend", "frontend"])

# Skip a repo
run(exclude="docs")

# Continue even if one repo fails
run(continue_on_error=True)

# Preview without running
run(dry_run=True)

# Ensure repos are cloned before running
run(ensure_setup=True)

# Combine options
run(script="test.sh", verbose=True, ensure_setup=True)

For the full behavioural description, see Running Pipelines.

Raw argument passing

If you need to pass flags not yet exposed as keyword arguments, use the raw helpers:

from repos import workspace_raw, codespace_raw, run_raw

workspace_raw("-f", "custom.list")

codespace_raw("-d", ".devcontainer/devcontainer.json")

run_raw("--script", "build.sh", "--dry-run")
run_raw("-f", "custom.list", "--continue-on-error")

These functions forward all positional arguments directly to the corresponding repos subcommand.

Target CLI version vs. installed CLI

You can inspect both versions at any time:

from repos import bundled_cli_version, installed_cli_version

print("Bundled:", bundled_cli_version())
print("System: ", installed_cli_version())  # None if not installed

Does installing the Python package also install the `repos` CLI?

No. Installing the package via pip does not place a repos command on your system PATH. Install the CLI separately before using the wrapper.

The easiest way is to call install_cli() from Python:

from repos import install_cli

# Print OS-appropriate installation instructions
install_cli()

# Or print instructions AND run the installer automatically
install_cli(run=True)

See install_cli() above for details, or visit the Installation guide for all options.

Installation

End-to-End Workflow

Step 1 — Create a repos.list file

Step 2 — Clone repositories

Step 3 — Open in your IDE (optional)

Step 4 — Run a pipeline

API Reference

install_cli()

bundled_cli_version()

installed_cli_version()

workspace()

codespace()

run()

Raw argument passing

Target CLI version vs. installed CLI

Does installing the Python package also install the repos CLI?

Step 1 — Create a `repos.list` file

`install_cli()`

`bundled_cli_version()`

`installed_cli_version()`

`workspace()`

`codespace()`

`run()`

Does installing the Python package also install the `repos` CLI?