Skip to content

Introduction and Global Options

rv aims to provide users with commands that make package management and installation simple. To accomplish this, we have various “types” of commands which give users the ability to set up and configure their projects, install packages, and inspect their project status and other information.

rv is able to create new projects, initialize an existing project, and even migrate an existing renv project. All of which will set users up with a project that is immediately ready to install packages into isolated, project-specific libraries.

  • rv init - Initialize a new or existing project with the necessary project infrastructure.
  • rv migrate renv - Initialize an existing renv project by migrating the renv.lock to an rv config file.

In other R tools, individual packages are installed and removed through separate commands (i.e. install.packages() and remove.packages()) In rv, a project is synchronized across the config file, lock file, and the project library, performing whatever actions, including installation and removal of packages and dependencies, is necessary to reach the synchronized state.

Every time a package is changed - added, removed, new version, source changed - the lockfile is automatically updated to reflect the new state of the project library.

  • rv sync - The basic command to install packages
  • rv upgrade - Install packages while ignoring the lockfile

As mentioned in the Configuration File section, rv uses a configuration file to provide users a way to declare the desired state of the project. While this configuration file was designed and intended to be manually edited, rv allows you to add simple dependencies to the config file.

In other R tools, packages are installed and any consequence is up to the user to reconcile. With rv, users have the ability to see what will happen before it occurs, giving power to the users to reconcile any potential issues without changing your current project. This concept persists across other commands, like add and upgrade, with the --dry-run flag, but two commands to specifically indicate the status of the project, displaying the information differently depending on your needs.

  • rv plan - Show the results if you were to run rv sync. A more granular view.
  • rv summary - Inspect your project on a global level, indicating information like how packages need to be installed and the source of packages.

In addition to the project’s status, rv provides commands to see information regarding the project.

  • rv tree - Show the dependency tree for the project’s dependencies
  • rv cache - Returns the cache directories used in the project
  • rv library - Returns the relative path to the library in UNIX-format
  • rv info - Returns simple information about the project. Primarily used for project activation
  • rv sysdeps - List the system dependencies needed by the dependency tree (only for Ubuntu/Debian)

A few other commands which can be used occasionally to effect your project:

Each command has the following global options:

  • --config-file - the path to a config file. Defaults to rproject.toml in the current directory. Unless otherwise specified in the config file, the library will be synced at the level of the config file, not in the working directory.
  • --verbose (-v) - increase the logging verbosity
  • --quiet (-q) - decrease logging verbosity
  • --json - print the output as JSON format. This will ignore the --verbose and --quiet flag and not log anything.