restore {packrat}

Apply the most recent snapshot to the library

Description

Applies the most recent snapshot to the project's private library.

Usage

restore(
  project = NULL,
  overwrite.dirty = FALSE,
  prompt = interactive(),
  dry.run = FALSE,
  restart = !dry.run
)

Arguments

project

The project directory. When in packrat mode, if this is NULL, then the directory associated with the current packrat project is used. Otherwise, the project directory specified is used.

overwrite.dirty

A dirty package is one that has been changed since the last snapshot or restore. Packrat will leave these alone by default. If you want to guarantee that restore will put you in the exact state represented by the snapshot being applied, use overwrite.dirty = TRUE.

prompt

TRUE to prompt before performing potentially destructive changes (package removals or downgrades); FALSE to perform these operations without confirmation.

dry.run

If TRUE, compute the changes to your packrat state that would be made if a restore was performed, without actually executing them.

restart

If TRUE, restart the R session after restoring.

Details

restore works by adding, removing, and changing packages so that the set of installed packages and their versions matches the snapshot exactly.

There are three common use cases for restore:

• Hydrate: Use restore after copying a project to a new machine to populate the library on that machine.

• Sync: Use restore to apply library changes made by a collaborator to your own library. (In general, you want to run restore whenever you pick up a change to packrat.lock)

• Rollback: Use restore to undo accidental changes made to the library since the last snapshot.

restore cannot make changes to packages that are currently loaded. If changes are necessary to currently loaded packages, you will need to restart R to apply the changes (restore will let you know when this is necessary). It is recommended that you do this as soon as possible, because any library changes made between running restore and restarting R will be lost.

Note

restore can be destructive; it will remove packages that were not in the snapshot, and it will replace newer packages with older versions if that's what the snapshot indicates. restore will warn you before attempting to remove or downgrade a package (if prompt is TRUE), but will always perform upgrades and new installations without prompting.

restore works only on the private package library created by packrat; if you have other libraries on your path, they will be unaffected.

The restart parameter will only result in a restart of R when the R environment packrat is running within makes available a restart function via getOption("restart").

To install packages hosted in private repositories on GitHub, GitLab, and Bitbucket, you must either set the option packrat.authenticated.downloads.use.renv to TRUE and ensure that curl is available on your system, or ensure that the httr package is available in your R library.

In addition, you must make credentials for your provider available in the appropriate environment variable(s): GITHUB_PAT, GITLAB_PAT, and/or BITBUCKET_USERNAME and BITBUCKET_PASSWORD. These environment variables are hidden from package installation subprocesses.

Packrat does not support installation from enterprise instances of GitHub, GitLab, or Bitbucket.

Packrat selects a tar binary with the following heuristic: If a TAR environment variable exists, Packrat will use that. Otherwise, it will either look for a tar binary on the PATH on Unix, or look for the system tar on Windows. If no binary is found in those locations, it will use R's internal tar implementation, which may cause errors with long filenames.

See Also

snapshot, the command that creates the snapshots applied with restore.

status to view the differences between the most recent snapshot and the library.