rv add examples

The rv add command supports a wide range of options for adding packages to your project. This page demonstrates various ways to use rv add with different package sources and configuration options.

Simple Package Addition

Add a package using the default behavior - creates a simple string dependency entry:

rv add dplyr

Result in rproject.toml:

dependencies = ["dplyr"]

Specifying a Repository

Add a package from a specific repository using the --repository flag:

rv add polars --repository RMV25Q3

Result in rproject.toml:

dependencies = [
    { name = "polars", repository = "RMV25Q3" }
]

This is useful when you need to install a package from a non-default repository, such as R-multiverse snapshots.

Force Source Installation

Force installation from source for all repositories:

rv add dplyr --force-source

Result in rproject.toml:

dependencies = [
    { name = "dplyr", force_source = true }
]

Combining Multiple Options

Combine repository targeting, force source, and install suggestions:

rv add dplyr --repository cran --force-source --install-suggestions

Result in rproject.toml:

dependencies = [
    { name = "dplyr", repository = "cran", force_source = true, install_suggestions = true }
]

Git Repository with Tag

Install from a git repository with a specific tag:

rv add my-pkg --git https://github.com/user/repo --tag v1.0.0

Result in rproject.toml:

dependencies = [
    { name = "my-pkg", git = "https://github.com/user/repo", tag = "v1.0.0" }
]

Git Repository with All Options

Install from a git repository with branch, subdirectory, and additional options:

rv add my-pkg --git https://github.com/user/repo --branch main --directory subpkg --install-suggestions --dependencies-only

Result in rproject.toml:

dependencies = [
    { name = "my-pkg", git = "https://github.com/user/repo", branch = "main",
      directory = "subpkg", install_suggestions = true, dependencies_only = true }
]

Git Repository Pinned to a Commit

Install from a git repository pinned to a specific commit SHA, using --commit instead of --tag/--branch:

rv add my-pkg --git https://github.com/user/repo --commit 9a8c5d2

Result in rproject.toml:

dependencies = [
    { name = "my-pkg", git = "https://github.com/user/repo", commit = "9a8c5d2" }
]

owner/repo Shorthand

As a shortcut for --git, a positional argument in the form owner/repo is resolved as a git source against https://github.com (or git_shorthand_base_url if configured). A reference and subdirectory can be appended with @. Since the package name isn’t given explicitly, rv fetches the repository’s DESCRIPTION file to determine it:

rv add r-lib/cli@v3.6.2

Result in rproject.toml:

dependencies = [
    { name = "cli", git = "https://github.com/r-lib/cli", tag = "v3.6.2" }
]

A typed reference plus subdirectory can be combined with tag:/branch:/commit::

rv add r-lib/usethis@tag:v2.2.3:r-package

Result in rproject.toml:

dependencies = [
    { name = "usethis", git = "https://github.com/r-lib/usethis", tag = "v2.2.3", directory = "r-package" }
]

See the rv add shorthand reference for the full syntax, including plain owner/repo (defaults to the repo’s HEAD).

With a Custom git_shorthand_base_url

If git_shorthand_base_url is set in rproject.toml (e.g. for a GitHub Enterprise host), the shorthand resolves against that base URL instead of https://github.com:

rproject.toml

[project]
name = "example"
r_version = "4.5"
repositories = [
    { alias = "PPM", url = "https://packagemanager.posit.co/cran/latest" },
]
git_shorthand_base_url = "https://git.mycompany.com/scm"
dependencies = [
    "dplyr",
]

rv add my-team/my-pkg@v1.2.0

Result in rproject.toml:

dependencies = [
    "dplyr",
    { name = "my-pkg", git = "https://git.mycompany.com/scm/my-team/my-pkg", tag = "v1.2.0" }
]

Local Path

Install a package from a local path:

rv add my-pkg --path ../my-package

Result in rproject.toml:

dependencies = [
    { name = "my-pkg", path = "../my-package" }
]

Package Archive URL

Install from a direct URL to a package archive:

rv add dplyr --url https://cran.r-project.org/src/contrib/Archive/dplyr/dplyr_1.1.3.tar.gz

Result in rproject.toml:

dependencies = [
    { name = "dplyr", url = "https://cran.r-project.org/src/contrib/Archive/dplyr/dplyr_1.1.3.tar.gz" }
]

Dependencies-Only Mode

Install only the dependencies of a package without installing the package itself. This is particularly useful when actively developing a package:

rv add my-dev-pkg --path . --dependencies-only

Result in rproject.toml:

dependencies = [
    { name = "my-dev-pkg", path = ".", dependencies_only = true }
]

This installs all dependencies of my-dev-pkg but not my-dev-pkg itself, which is ideal for development workflows.