-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathrestoring_a_project.qmd
62 lines (36 loc) · 5.34 KB
/
restoring_a_project.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
---
title: "Restoring Another Project"
---
The discussion so far on using {renv} has been about initiating a project with {renv} and then updating the `renv.lock` file as you work on the project. This is generally the more complicated portion of the work you will ever need to do with {renv}. The other side of using {renv} is restoring a project that someone else has shared with you or restoring a project that you have shared with others. This is the topic of this page.
We will cover restoring a project from a GitHub repository, restoring a project from a lockfile, and restoring a project after upgrading R.
# When to `restore()`
## From a GitHub Repo
Restoring a project library from a GitHub repository is the most straightforward method to restore a project. A repo *should* always have all of the required files for restoring a project including the `renv.lock` file, the `renv` folder, the `*.Rproj` file, and the R scripts. Note that repos generally do not (and should not) contain the `renv/library` folder--this is intended behavior. The `renv/library` contains "symlinks" to the actual package files on your machine, and these symlinks are not portable across machines[^1]. Moreover, the `renv/library` folder can be quite large and is not necessary for restoring a project.
[^1]: See the [Caching chapter](caching.html) for more information on the `renv/library` folder.
The steps for restoring a project from a GitHub repository are as follows:
- Clone the repository to your local machine with `git clone`
- Open the `*.Rproj` file
- Run `renv::restore()`
There should not be anything else to do! The `renv.lock` file will be used to install the correct versions of the packages you need for the project.
## From a lockfile
You may encounter situations where it's not practical or possible to use a GitHub repository for your project, namely if your collaborators are not familiar with using GitHub. In these cases, you can both restore and share a project's depedencies using just the `renv.lock` file. This procedure for restoring contains just a few extra steps compared to the previous method, but should still look familiar:
- Obtain the `renv.lock` file from your collaborators.
- Place the `renv.lock` in the same directory as your project's `*.Rproj` file.
- Run `renv::status()`. The results will look similar to this:
``` r
renv::status()
#> This project does not appear to be using renv.
#> Use `renv::restore()` to install the packages defined in lockfile.
```
- Option 1: Run `renv::restore()`. If prompted, choose the option "Activate the project and use the project library." This will create all other necessary files and directories for a {renv} project.
- **Option 2: Run `renv::init()`. Choose the option to "Restore the project from the lockfile." This will do everything that `renv::restore()` does *and* install the packages at the same time.**
## After Upgrading R
Something that may come as a surprise is the need to restore a project after upgrading R. This occurs because the {renv} package creates a separate cache for each major and minor version of R that you use. A more detailed explanation of this can be found in the [caching chapter](caching.html), but a summarized version is also provided here.
<!-- When you upgrade R, the cache for the previous version of R is no longer valid. This is because the cache contains compiled binaries of packages that are specific to the version of R you are using. When you upgrade R, the compiled binaries are no longer valid and need to be recompiled. This is why you need to restore the project after upgrading R. -->
To first clarify "major" and "minor" upgrades: they refer to semantic versioning of software which is a way of providing version numbers to software using three numbers separated by periods: `major.minor.patch`. For example, an upgrade from R4.3.2 to 4.3.3. is a "patch" while an upgrade from R4.3 to R4.4 is a "minor" release. Minor releases occur approximately once per year, and, after installing a new minor release, you will need to restore your project.
If you install a new major or minor version of R, you will need to ensure that the version of R you are using is compatible with your project(s). There are two ways to achieve this:
The first option is to update your *project* to use the new version of R. This can be done by running `renv::update()` to update the packages in your project (particularly the base R packages that came with the new version of R), and then running `renv::snapshot()` to update the `renv.lock` file.
The second option is to switch between R versions using a tool like [rswitch](https://rud.is/rswitch/) or [rig](https://github.com/r-lib/rig). These tools are useful if you are working on multiple projects that require different versions of R, or if you have projects where it's not possible to update the version of R being used.
# When to `upgrade()` and `update()`
If you are working on a project and you want to update the packages in your project, you can run `renv::update()`. This will update the packages in your project to the latest versions that are compatible with the versions of the packages in your `renv.lock` file. If you want to update a specific package, you can run `renv::update("package_name")`.
If you want to update the `renv` package itself, you can run `renv::upgrade()`. This will update the `renv` package to the latest version available on CRAN.