R Package

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

Installation

install.packages("devtools")
devtools::install_github("MiguelRodo/repos")

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

library(repos)

repos_clone()

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

repos_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]).

repos_clone() supports explicit fetch modes:

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

Step 3 — Open in your IDE (optional)

Generate a VS Code multi-root workspace file:

repos_workspace()

See repos_workspace() below for all options.

Step 4 — Run a pipeline

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

repos_run()          # executes run.sh in every repo

See repos_run() below for all options.

API Reference

`repos_install_cli()`

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

repos_install_cli(
  run = FALSE  # if TRUE, run the installer automatically
)

Parameters

Parameter	Type	Default	Description
`run`	`logical`	`FALSE`	If `TRUE`, attempt to run the installer automatically

Details

The R 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: Invisibly returns NULL.

Examples:

library(repos)

# Print installation instructions for your OS
repos_install_cli()

# Print instructions AND run the installer
repos_install_cli(run = TRUE)

`repos_bundled_cli_version()`

Return the repos CLI version targeted by this package.

repos_bundled_cli_version()

Returns: A character string with the targeted CLI version (e.g. "2.0.0").

Examples:

library(repos)

repos_bundled_cli_version()  # e.g. "2.0.0"

`repos_installed_cli_version()`

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

repos_installed_cli_version()

Returns: A character string with the installed CLI version, or NULL.

Examples:

library(repos)

ver <- repos_installed_cli_version()
if (is.null(ver)) {
  message("repos CLI is not installed on this system.")
} else {
  message("Installed CLI version: ", ver)
}

`repos()`

Top-level dispatcher that delegates to the appropriate subcommand.

repos(command, ...)

Parameters

Parameter	Type	Description
`command`	`character`	`"clone"`, `"workspace"`, `"codespace"`, `"codespaces"`, or `"run"`
`...`		Forwarded to the corresponding function

Returns: Invisibly returns the exit status of the command (0 for success).

Examples:

library(repos)

repos("clone")
repos("workspace")
repos("codespace")
repos("run")
repos("run", script = "build.sh")

`repos_workspace()`

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

repos_workspace(
  file       = NULL,   # path to a custom list file (default: repos.list)
  debug      = FALSE,  # write debug output to stderr
  debug_file = NULL,   # write debug output to a file (TRUE = auto-name, or a path)
  ...                  # additional raw flags forwarded to repos workspace
)

Parameters

Parameter	Type	Default	Description
`file`	`character`	`NULL`	Path to repos list file (default: `repos.list`)
`debug`	`logical`	`FALSE`	Print debug output to stderr
`debug_file`	`logical` or `character`	`NULL`	Write debug output to a file
`...`			Additional raw flags forwarded as-is

Returns: Invisibly returns the exit status of the command (0 for success).

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

Examples:

library(repos)

# Generate workspace from default repos.list
repos_workspace()

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

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

`repos_codespace()`

Configure GitHub Codespaces devcontainer.json.

repos_codespace(
  file         = NULL,  # path to a custom list file (default: repos.list)
  devcontainer = NULL,  # path(s) to devcontainer.json
  permissions  = NULL,  # "default", "all", or "contents"
  tool         = NULL,  # deprecated; ignored
  debug        = FALSE, # write debug output to stderr
  debug_file   = NULL,  # write debug output to a file (TRUE = auto-name, or a path)
  ...                   # additional raw flags forwarded to repos codespace
)

Parameters

Parameter	Type	Default	Description
`file`	`character`	`NULL`	Path to repos list file (default: `repos.list`)
`devcontainer`	`character` or `character vector`	`NULL`	Path(s) to `devcontainer.json`
`permissions`	`character`	`NULL`	`"default"`, `"all"`, or `"contents"`
`tool`	`character`	`NULL`	Deprecated; ignored
`debug`	`logical`	`FALSE`	Print debug output to stderr
`debug_file`	`logical` or `character`	`NULL`	Write debug output to a file
`...`			Additional raw flags forwarded as-is

Returns: Invisibly returns the exit status of the command (0 for success).

Examples:

library(repos)

# Configure with default devcontainer path
repos_codespace()

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

# Multiple devcontainer paths
repos_codespace(devcontainer = c("path1/devcontainer.json",
                                 "path2/devcontainer.json"))

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

`repos_run()`

Execute a script inside each cloned repository.

repos_run(
  file             = NULL,   # path to a custom list file (default: repos.list)
  script           = NULL,   # script to run in each repo (default: run.sh)
  include          = NULL,   # repo name(s) to include
  exclude          = NULL,   # repo name(s) to skip
  ensure_setup     = FALSE,  # clone repos first (via repos clone)
  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
  ...                        # additional raw flags forwarded to repos run
)

Parameters

Parameter	Type	Default	Description
`file`	`character`	`NULL`	Path to repos list file (default: `repos.list`)
`script`	`character`	`NULL`	Script file to run in each repo (default: `run.sh`)
`include`	`character` or `character vector`	`NULL`	Only run in these repos
`exclude`	`character` or `character vector`	`NULL`	Skip these repos
`ensure_setup`	`logical`	`FALSE`	Clone repos first (via `repos clone`)
`skip_deps`	`logical`	`FALSE`	Skip R dependency installation
`dry_run`	`logical`	`FALSE`	Preview without executing
`verbose`	`logical`	`FALSE`	Verbose logging
`continue_on_error`	`logical`	`FALSE`	Continue past failures
`...`			Additional raw flags forwarded as-is

Returns: Invisibly returns the exit status of the command (0 for success).

Examples:

library(repos)

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

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

# Only run in specific repos
repos_run(include = c("backend", "frontend"))

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

# Continue even if one repo fails
repos_run(continue_on_error = TRUE)

# Preview without running
repos_run(dry_run = TRUE)

# Ensure repos are cloned before running
repos_run(ensure_setup = TRUE)

# Combine options
repos_run(script = "test.sh", verbose = TRUE, ensure_setup = TRUE)

# Backward compatibility — raw flag passing still works
repos_run("--script", "build.sh", "--dry-run")

For the full description, see Running Pipelines.

Target CLI version vs. installed CLI

You can inspect both versions at any time:

library(repos)

repos_bundled_cli_version()     # version bundled in the package
repos_installed_cli_version()   # system PATH version, or NULL

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

No. Installing the package does not install the repos command on your PATH. Install the CLI separately, then call repos_install_cli() from R:

library(repos)

# Print OS-appropriate installation instructions
repos_install_cli()

# Or print instructions AND run the installer automatically
repos_install_cli(run = TRUE)

See repos_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

repos_install_cli()

repos_bundled_cli_version()

repos_installed_cli_version()

repos()

repos_workspace()

repos_codespace()

repos_run()

Target CLI version vs. installed CLI

Does installing the R package also install the repos CLI?

Step 1 — Create a `repos.list` file

`repos_install_cli()`

`repos_bundled_cli_version()`

`repos_installed_cli_version()`

`repos()`

`repos_workspace()`

`repos_codespace()`

`repos_run()`

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