diff --git a/R/checkout.R b/R/checkout.R index 8ec8f7454..2db7f31c0 100644 --- a/R/checkout.R +++ b/R/checkout.R @@ -11,6 +11,15 @@ #' packages used in a particular renv project to the package versions #' provided by a particular snapshot. #' +#' Note that calling `renv::checkout()` will also install the version of `renv` +#' available as of the requested snapshot date, which might be older or lack +#' features available in the currently-installed version of `renv`. In addition, +#' the project's `renv/activate.R` script will be re-generated after checkout. +#' If this is undesired, you can re-install a newer version of `renv` after +#' checkout from your regular \R package repository. +#' +#' @section Caveats: +#' #' If your library contains packages installed from other remote sources (e.g. #' GitHub), but a version of a package of the same name is provided by the #' repositories being checked out, then please be aware that the package will be @@ -33,6 +42,10 @@ #' [Package Manager](https://packagemanager.rstudio.com/) instance will be #' used. Ignored if `repos` is non-`NULL`. #' +#' @param restart Should the \R session be restarted after the new +#' packages have been checked out? When `NULL` (the default), the +#' session is restarted if the "restore" action was taken. +#' #' @param actions The action(s) to perform with the requested repositories. #' This can either be "snapshot", in which `renv` will generate a lockfile #' based on the latest versions of the packages available from `repos`, or @@ -52,6 +65,9 @@ #' # only check out some subset of packages (and their recursive dependencies) #' renv::checkout(packages = "dplyr", date = "2023-01-02") #' +#' # generate a lockfile based on a snapshot date +#' renv::checkout(date = "2023-01-02", actions = "snapshot") +#' #' } #' @export checkout <- function(repos = NULL, @@ -60,6 +76,7 @@ checkout <- function(repos = NULL, date = NULL, clean = FALSE, actions = "restore", + restart = NULL, project = NULL) { renv_consent_check() @@ -89,14 +106,35 @@ checkout <- function(repos = NULL, lockfile$Packages <- records if ("restore" %in% actions) { + + # install the requested packages restore(lockfile = lockfile, clean = clean) - lockfile <- snapshot(packages = packages, lockfile = NULL) + + # re-generate the activate script + args <- c("--vanilla", "-s", "-e", shQuote("renv::activate()")) + r(args) + + # update the renv lockfile record + local({ + renv_scope_options(renv.verbose = FALSE) + record( + records = renv_lockfile_records(lockfile)["renv"], + project = project + ) + }) + } + # re-generate the lockfile if requested if ("snapshot" %in% actions) { - renv_lockfile_write(lockfile, file = renv_lockfile_path(project)) + snapshot(project) } + # try to restart the session if we installed some packages + restart <- restart %||% "restore" %in% actions + if (restart) + renv_restart_request(project = project, reason = "renv has been updated") + invisible(lockfile) } diff --git a/R/roxygen.R b/R/roxygen.R index 97c80bdbd..aa9bb73c3 100644 --- a/R/roxygen.R +++ b/R/roxygen.R @@ -38,6 +38,8 @@ #' #' @param profile The profile to be activated. See #' `vignette("profiles", package = "renv")` for more information. +#' When `NULL` (the default), the profile is not changed. Use +#' `profile = "default"` to revert to the default `renv` profile. #' #' @param dependencies A vector of DESCRIPTION field names that should be used #' for package dependency resolution. When `NULL` (the default), the value diff --git a/man/activate.Rd b/man/activate.Rd index fa253d136..9796ccdd0 100644 --- a/man/activate.Rd +++ b/man/activate.Rd @@ -15,7 +15,9 @@ be used. If no project is currently active, then the current working directory is used instead.} \item{profile}{The profile to be activated. See -\code{vignette("profiles", package = "renv")} for more information.} +\code{vignette("profiles", package = "renv")} for more information. +When \code{NULL} (the default), the profile is not changed. Use +\code{profile = "default"} to revert to the default \code{renv} profile.} \item{clean}{If \code{TRUE}, will also remove the \verb{renv/} directory and the lockfile.} diff --git a/man/checkout.Rd b/man/checkout.Rd index 632e6a074..affaf8a9e 100644 --- a/man/checkout.Rd +++ b/man/checkout.Rd @@ -11,6 +11,7 @@ checkout( date = NULL, clean = FALSE, actions = "restore", + restart = NULL, project = NULL ) } @@ -41,6 +42,10 @@ based on the latest versions of the packages available from \code{repos}, or \code{c("snapshot", "restore")} if you'd like to generate a lockfile and install those packages in a single call.} +\item{restart}{Should the \R session be restarted after the new +packages have been checked out? When \code{NULL} (the default), the +session is restarted if the "restore" action was taken.} + \item{project}{The project directory. If \code{NULL}, then the active project will be used. If no project is currently active, then the current working directory is used instead.} @@ -57,6 +62,16 @@ renv project. In this way, you can upgrade (or downgrade) all of the packages used in a particular renv project to the package versions provided by a particular snapshot. +Note that calling \code{renv::checkout()} will also install the version of \code{renv} +available as of the requested snapshot date, which might be older or lack +features available in the currently-installed version of \code{renv}. In addition, +the project's \code{renv/activate.R} script will be re-generated after checkout. +If this is undesired, you can re-install a newer version of \code{renv} after +checkout from your regular \R package repository. +} +\section{Caveats}{ + + If your library contains packages installed from other remote sources (e.g. GitHub), but a version of a package of the same name is provided by the repositories being checked out, then please be aware that the package will be @@ -65,6 +80,7 @@ be a concern if your project uses \R packages from GitHub whose name matches that of an existing CRAN package, but is otherwise unrelated to the package on CRAN. } + \examples{ \dontrun{ @@ -77,5 +93,8 @@ renv::checkout(repos = c(PPM = "https://packagemanager.rstudio.com/cran/2023-01- # only check out some subset of packages (and their recursive dependencies) renv::checkout(packages = "dplyr", date = "2023-01-02") +# generate a lockfile based on a snapshot date +renv::checkout(date = "2023-01-02", actions = "snapshot") + } } diff --git a/man/init.Rd b/man/init.Rd index 6111b9117..4242d21b9 100644 --- a/man/init.Rd +++ b/man/init.Rd @@ -26,7 +26,9 @@ changed to match the requested project directory.} are matched to \code{...}, renv will signal an error.} \item{profile}{The profile to be activated. See -\code{vignette("profiles", package = "renv")} for more information.} +\code{vignette("profiles", package = "renv")} for more information. +When \code{NULL} (the default), the profile is not changed. Use +\code{profile = "default"} to revert to the default \code{renv} profile.} \item{settings}{A list of \link{settings} to be used with the newly-initialized project.} diff --git a/man/load.Rd b/man/load.Rd index a7fd35cbb..b745615b6 100644 --- a/man/load.Rd +++ b/man/load.Rd @@ -14,7 +14,9 @@ directory is used instead.} \item{quiet}{Boolean; be quiet during load?} \item{profile}{The profile to be activated. See -\code{vignette("profiles", package = "renv")} for more information.} +\code{vignette("profiles", package = "renv")} for more information. +When \code{NULL} (the default), the profile is not changed. Use +\code{profile = "default"} to revert to the default \code{renv} profile.} \item{...}{Unused arguments, reserved for future expansion. If any arguments are matched to \code{...}, renv will signal an error.}