rig repos

Manage the R package repositories that rig configures for your R installations.

rig sets up the repositories R uses to install packages (the repos option in R), typically a CRAN mirror and the Posit Public Package Manager (P3M). These are configured per R version, and you can control them when installing R (see the --with-repos and --without-repos options of rig add) or afterwards with the subcommands here: rig repos enable and rig repos disable turn repositories on and off for an R version.

Besides the repositories built into rig, you can add your own CRAN-like repositories with rig repos add, and enable them for the R versions that need them.

Changing the repositories of an R version updates the files of the R installation. In admin mode on Linux and Windows these belong to the administrator, so rig asks for administrator rights; in user mode, and usually for admin users on macOS, it does not.

To look up the packages the repositories offer, see rig pkg .

Subcommands

add: Add a custom R package repository
available: List available R package repositories
disable: Disable R package repositories for an R version
enable: Enable R package repositories for an R version
list: List configured R package repositories
rm: Remove a custom R package repository
setup: Set up R package repositories
status: Check the configured R package repositories

`rig repos add`

Add a CRAN-like package repository to rig, e.g. your company’s internal CRAN mirror, or the r-universe of your organization.

rig stores the repository in its configuration file, so you only need to add it once. It is not used by any R version until you enable it, either with --enable here or later with rig repos enable. After that it is just like the repositories built into rig: it shows up in rig repos available, and you can enable it with --with-repos when you install a new R version with rig add or call rig repos setup.

The name of the repository must start with a letter or a number, and can contain letters, numbers and ., _, /, -. It cannot be the name of a repository that is built into rig. Use --force to replace a custom repository of the same name.

The URL must start with https://, http:// or file://. It is the URL that you would put into the repos option in R, i.e. the directory that has the src/contrib directory in it, and the bin directory, if the repository has binary packages.

With --enable rig enables the repository for the default R version, or the R versions you list with --r-version, or all of them with --all-versions. --enable --all-versions also enables the repository for the R versions you install later, the same way as CRAN. To undo this, add the repository again with --force, without --all-versions. You can still turn it off for some R versions with rig repos disable, or for a new R version with --without-repos when installing it.

rig updates the files of the R installation. If you cannot write them, which is typical in admin mode on Linux and Windows, rig asks for administrator rights, e.g. your password for sudo.

Usage

rig repos add [OPTIONS] <name> <url>

Arguments

<name>: Name of the repository, e.g. ‘acme’
<url>: URL of the repository, e.g. ‘https://cran.acme.com’

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
--all-versions: With --enable, enable the repository for all R versions, also the ones installed later
--description <description>: Longer description of the repository
--enable: Also enable the repository, see rig repos enable
--force: Replace the repository if it already exists
-h, --help: Print help (see a summary with ‘-h’)
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
-r, --r-version <r-version>: With --enable, R version to enable the repository for (default: the default R version), can be repeated
--title <title>: Short title of the repository
--user: Run in user mode (overrides RIG_MODE and config)

Examples

# Add a repository, without enabling it
rig repos add acme https://cran.acme.com --title "Acme CRAN mirror"

# Add a repository and enable it for the default R version
rig repos add acme-universe https://acme.r-universe.dev --enable

# Add a repository and enable it for all R versions, also the ones
# installed later
rig repos add acme https://cran.acme.com --enable --all-versions

`rig repos available`

List the package repositories that rig knows about and can set up.

These are the repositories built into rig, plus the ones you added with rig repos add. You can enable them with --with-repos when running rig add or rig repos setup, or with rig repos enable.

Without arguments rig prints one row per repository: its name, whether it is part of the default repository set, whether it is built in or custom, and its title. A custom repository is part of the default set, i.e. new R versions get it, if you added it with rig repos add --enable --all-versions.

Pass a repository name to see its description and its URLs, together with the platforms, architectures and R versions each URL applies to. Repository names are matched case insensitively.

Usage

rig repos available [OPTIONS] [name]

Arguments

[name]: Repository to show in detail, e.g. ‘P3M’ (case insensitive)

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
-h, --help: Print help (see a summary with ‘-h’)
--json: JSON output
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user: Run in user mode (overrides RIG_MODE and config)

Examples

# List all repositories rig knows about
rig repos available

# Show the URLs of one repository
rig repos available P3M

`rig repos disable`

Disable one or more package repositories for R versions, so R does not use them to install packages. This works both for the repositories built into rig, e.g. P3M or CRAN, for the ones you added with rig repos add, and for the repositories that come with R itself, e.g. CRANextra or R-Forge. Repository names are matched case insensitively. Disabling a custom repository keeps it in rig, use rig repos rm to remove it completely.

By default rig disables the repositories for the default R version. Use --r-version (possibly more than once) to pick other R versions, or --all-versions for all of them.

rig remembers which repositories you enabled and disabled for each R version, and keeps them when it sets up the repositories again, e.g. with rig repos setup.

rig updates the files of the R installation. If you cannot write them, which is typical in admin mode on Linux and Windows, rig asks for administrator rights, e.g. your password for sudo.

Usage

rig repos disable [OPTIONS] <name>...

Arguments

<name>...: Name(s) of the repositories, e.g. ‘P3M’ (case insensitive)

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
--all-versions: Disable the repositories for all installed R versions
-h, --help: Print help (see a summary with ‘-h’)
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
-r, --r-version <r-version>: R version to disable the repositories for (default: the default R version), can be repeated
--user: Run in user mode (overrides RIG_MODE and config)

Examples

# Stop using P3M for the default R version
rig repos disable p3m

# Stop using a custom repository for R 4.4
rig repos disable acme -r 4.4

`rig repos enable`

Enable one or more package repositories for R versions. This works both for the repositories built into rig, e.g. Bioconductor or RHUB, and for the ones you added with rig repos add. See rig repos available for the list. It also works for the repositories that come with R itself, e.g. CRANextra or R-Forge, see rig repos list --all. Repository names are matched case insensitively.

By default rig enables the repositories for the default R version. Use --r-version (possibly more than once) to pick other R versions, or --all-versions for all of them. Each R version has its own set of repositories, so enabling a repository for one R version does not change the others.

rig remembers which repositories you enabled and disabled for each R version, and keeps them when it sets up the repositories again, e.g. with rig repos setup.

Some built-in repositories only have URLs for certain platforms, architectures or R versions, and rig fails if a repository cannot be used with an R version.

rig updates the files of the R installation. If you cannot write them, which is typical in admin mode on Linux and Windows, rig asks for administrator rights, e.g. your password for sudo.

Usage

rig repos enable [OPTIONS] <name>...

Arguments

<name>...: Name(s) of the repositories, e.g. ‘Bioconductor’ (case insensitive)

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
--all-versions: Enable the repositories for all installed R versions
-h, --help: Print help (see a summary with ‘-h’)
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
-r, --r-version <r-version>: R version to enable the repositories for (default: the default R version), can be repeated
--user: Run in user mode (overrides RIG_MODE and config)

Examples

# Enable Bioconductor for the default R version
rig repos enable bioconductor

# Enable a custom repository for two R versions
rig repos enable acme -r 4.5 -r 4.4

# Enable R-Forge, one of R's own repositories
rig repos enable r-forge

# Enable a custom repository for every R version
rig repos enable acme --all-versions

`rig repos list`

List the package repositories configured for an R version.

By default rig shows the repositories of the default R version; use --r-version to pick another. Add --all to include repositories that are not enabled, and --raw to show repository URLs without resolving the % variables in them.

The name column is the name that rig repos enable, rig repos disable and rig repos available use. Some of these, e.g. Bioconductor, have several entries in R’s repositories file; then the repo column shows the name of the entry. The E column marks the enabled repositories. The M column marks the repositories that have extended metadata: the full history of their packages, including archived versions, and binary package indices. rig uses these to resolve package versions and to find binary packages. In --json output name is the entry name, the group field is the name of the rig repository, or null, and the metadata field holds the base URL of the extended metadata, or null.

The list includes the custom repositories (see rig repos add) that are enabled for the R version, and the repositories that come with R itself, e.g. CRANextra and R-Forge; with --all also the ones that are not enabled. Use rig repos enable and rig repos disable to change it.

Usage

rig repos list [OPTIONS]

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
--all: Show all repositories, not just the enabled ones
-h, --help: Print help (see a summary with ‘-h’)
--json: JSON output
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
-r, --r-version <r-version>: R version to list repositories for, instead of the default
--raw: Do not resolve % variables in repository URLs.
--user: Run in user mode (overrides RIG_MODE and config)

`rig repos rm`

Remove one or more repositories that you added with rig repos add. rig also removes them from every R version that uses them.

The repositories that are built into rig cannot be removed, use rig repos disable to stop using them.

If some R versions use the repositories, rig updates their files. If you cannot write them, which is typical in admin mode on Linux and Windows, rig asks for administrator rights, e.g. your password for sudo.

Usage

rig repos rm [OPTIONS] <name>...

Arguments

<name>...: Name(s) of the repositories to remove (case insensitive)

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
-h, --help: Print help (see a summary with ‘-h’)
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user: Run in user mode (overrides RIG_MODE and config)

Examples

rig repos rm acme

`rig repos setup`

Set up the package repositories for installed R versions.

By default rig configures the repositories for all installed R versions; use --r-version to restrict it to one. Use --with-repos and --without-repos to control which repositories are enabled, the same way as for rig add.

rig remembers the repositories enabled and disabled for each R version, with --with-repos, --without-repos, rig repos enable and rig repos disable, and applies them again every time. So rig repos setup without options keeps your choices, --with-repos=<names> and --without-repos=<names> add to them, and --without-repos without names starts over with no repositories (plus the ones in --with-repos).

rig updates the files of the R installation. If you cannot write them, which is typical in admin mode on Linux and Windows, rig asks for administrator rights, e.g. your password for sudo.

Usage

rig repos setup [OPTIONS]

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
-h, --help: Print help (see a summary with ‘-h’)
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
-r, --r-version <r-version>: R version to set up repositories for (default: all)
--user: Run in user mode (overrides RIG_MODE and config)
--with-repos=<with-repos>: Repositories to enable, in addition to the ones enabled by default. If --without-repos is also specified (without a value), then only these repositories will be enabled.
--without-repos[=<without-repos>]: Do not set up package repositories. Alternatively, specify which ones to skip, a comma-separated list. If --with-repos is also specified, then only the repositories in that argument will be enabled.

`rig repos status`

Check the package repositories configured for an R version: how quickly each one responds, whether it responds at all, what kinds of packages it serves, and how fresh its package index is.

rig checks the same repositories that rig repos list shows, in the same order. By default these are the repositories of the default R version; use --r-version to pick another one. Add --all to include repositories that are not enabled.

The report

For each repository rig prints:

ping: how long the repository took to answer a request for the package index. rig asks for the very index R would use on this machine, for the selected R version, so this is the latency you pay when installing a package. It is a HEAD request: the index itself is not downloaded, and the time does not depend on how large it is.
status: ok if the index is there. source only means the repository has no index for this platform and R version, but it does have source packages. Anything else is the HTTP status code the server returned, or why it returned nothing at all, e.g. timeout or cannot connect.
types: the package types the R installation’s repositories file declares for the repository: source, win (Windows binaries) and mac (macOS binaries). These are declarations, not measurements; the status column is what says whether the index for this platform is really there.
updated: the Last-Modified date of the package index, i.e. how fresh the repository’s view of the packages is.
url: the repository URL, with the Bioconductor %v and %bm variables resolved. Use --raw to print the URLs unresolved; rig still resolves them internally, since an unresolved URL cannot be checked.

A repository whose types column ends in * serves prebuilt Linux binaries as source packages. Linux binaries have no package type of their own in R, so a Posit Package Manager repository offers them from a distribution-specific URL instead, and rig recognizes those URLs.

The repositories are checked in parallel, so the command takes about as long as the slowest repository, not as long as all of them together. An unreachable repository is reported in its row; it does not fail the command.

Usage

rig repos status [OPTIONS]

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
--all: Check all repositories, not just the enabled ones
-h, --help: Print help (see a summary with ‘-h’)
--json: JSON output
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
-r, --r-version <r-version>: R version to check repositories for, instead of the default
--raw: Show repository URLs without resolving % variables.
--user: Run in user mode (overrides RIG_MODE and config)

Examples

# Check the repositories of the default R version
rig repos status

# Include repositories that are not enabled
rig repos status --all

# Check the repositories of another R version
rig repos status --r-version 4.4.1

# Machine readable output, with the exact URLs, statuses and timings
rig repos status --json