R Package

The repos R package wraps the same Bash scripts used by the command-line tool, so every feature available at the terminal is also available from R.

The package ships its own bundled copy of the CLI scripts, so all R functions work without requiring repos to be installed on your system PATH.

Installation

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

System requirements: bash, git, curl, and jq 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.

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 uses its own bundled copy of the CLI for all R functions. However, if you also want to use repos directly from your terminal, this function installs the CLI system-wide. Detects the operating system and prints the recommended installation command for that platform. On Linux and macOS, passing run = TRUE will also execute the installer. On Windows, only instructions are printed.

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 version of the repos CLI bundled inside this package.

repos_bundled_cli_version()

Returns: A character string with the bundled CLI version (e.g. "1.1.0").

Examples:

library(repos)

repos_bundled_cli_version()  # e.g. "1.1.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 script (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 vscode-workspace-add.sh
)

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 script (0 for success).

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 authentication.

repos_codespace(
  file         = NULL,  # path to a custom list file (default: repos.list)
  devcontainer = NULL,  # path(s) to devcontainer.json
  permissions  = NULL,  # "all" or "contents" — passed to codespaces-auth-add.sh
  tool         = NULL,  # force tool for codespaces-auth-add.sh ("jq" or "python")
  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 codespaces-auth-add.sh
)

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`	`"all"` or `"contents"`
`tool`	`character`	`NULL`	Force `"jq"` or `"python"` for auth helper
`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 script (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.sh
  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 run-pipeline.sh
)

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 script (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.

GitHub Authentication

repos_codespace() needs a GitHub token with Codespaces permissions. Provide it via the GH_TOKEN environment variable or via the gh CLI:

Sys.setenv(GH_TOKEN = "your_personal_access_token")
repos_codespace()

Or set it in your shell before starting R:

export GH_TOKEN="your_personal_access_token"

Bundled CLI vs. System CLI

The R package ships a bundled copy of the Bash scripts that it uses for all R functions (repos_run(), repos_workspace(), etc.). This bundled version is independent of any repos binary you may have installed on your system PATH.

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. The R package bundles its own copies of the Bash scripts, so all R functions (repos_run(), repos_workspace(), etc.) work without the repos command being on your PATH.

If you also want to run repos clone, repos run, etc. directly from a terminal, install the CLI separately. The easiest way is to 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()

GitHub Authentication

Bundled CLI vs. System 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?