renv_getting_started.qmd

---
title: "{renv}: Easy Start"
engine: knitr
---

This page provides the basic steps to starting a project with the {renv} package, and how to update the `renv.lock` file as you add new packages to your project. This page will be followed by a more detailed explanation of the package's functionality in the [Starting Details](starting_details.html) page.

# Initiating {renv}

When using or adding {renv} to one of your projects, you will likely enter from one of two approaches: either from a new project with RStudio, or by adding {renv} to an already existing (or non-RStudio) project.

Either approach should yield the following results in the directory you're working within:

-   Creation of a `renv.lock` file and a `renv` folder
-   Creation of or additions to the `.Rbuildignore` and `.Rprofile` files
-   A `renv` folder will be created in the project directory (for {renv} version 1.0.0 and above)

For most purposes, one will only need to have a passing understanding of the `renv.lock` file which records the packages used in the project and their versions. The `renv` folder is where the packages are stored, and the `.Rbuildignore` and `.Rprofile` files are used to ensure that the project is reproducible and that the correct packages are loaded when the project is opened.

::: {.callout-warning title="Git and `renv` Notice"}
**The `renv` folder comes with a .gitignore file. This file should be respected if you are using git with your project--do not override or force track items in the `renv` folder.** A more detailed explanation is available in the Advanced Topics section, but TL;DR: the project library should always be rebuilt from the `renv.lock` file.
:::

## With a New RStudio Project

When initiating a new project from within RStudio such as a typical .Rproj, a Quarto website, a new R package or similar, you can follow the approximate directions below to check the box that you would like to "Use renv with your project."

1. `File`
2. `New Project`
3. `New Directory`
4. `New Project`
5. `[x] Use renv with this project`



::: center-larger
{{< video assets/img/renv_init_new_project.mp4 >}}
:::

## From an Existing Project or Folder

In essentially all other scenarios, one can initiate {renv} for a project by navigating to your project/folder and running the two commands below.

``` r
install.packages("renv")

library(renv)
init()
```

::: center-larger
{{< video assets/img/renv_init_existing_project.mp4 >}}
:::

# Check Status of Project

After initiating {renv} in your project, you should see a message indicating that your project is in a "consistent state." In short, this means that {renv} has detected the following:

-   That all packages detected in the project are listed in the `renv.lock` file
-   That all packages in the `renv.lock` file are actually installed in the project
-   That all installed packages are the correct version

As you further develop your project, the packages you use may change or you may not have all required packages downloaded (particularly if you're collaborating with others). You can check the status of your project at any time by running the `renv::status()` function.

``` r
status()
```

If your project is in a consistent state, you will see the following message:

``` r
The project is already in a consistent state.
```

If your project is not in a consistent state, you will see a message indicating what is wrong with the project, and a potential remedy for the inconsistent state. For example, if you have a package that is not listed in the `renv.lock` file, you will see a message like the following:

``` r
The project is out of sync with the lockfile.
- Packages that are not in the lockfile:
    - {package_name}
```

# Updating `renv.lock`

As you write additional `.R`, `.Rmd`, and/or `.qmd` files for your project, you will presumably employ more and more functions from foreign packages, and these new packages should be captured in the `renv.lock` file. This can be done by "snapshotting" the project which will initiate a search for calls to `library()`, `require()` and namespaced calls to functions e.g. `package::function()`.

``` r
snapshot()
```

Running the `snapshot()` function will capture new packages used in your project, *and* it will update the package versions in the `renv.lock` file if you have installed new versions to the project you are working in.

::: center-larger
{{< video assets/img/renv_status_snapshot.mp4 >}}
:::

This is essentially 80% of the work you will ever need to put into creating a project that also uses {renv}. The other major component of using this package will be "restoring" libraries for either your own projects or for projects shared by others using `renv::restore()`. This is discussed next in [Restoring A Project](restoring_a_project.html), but **we strongly recommend reading the details of [Understanding {renv}](starting_details.html) first.**