install.packages("here")## Usage The here package creates paths relative to the top-level directory. The package displays the top-level of the current project on load or any time you call `here()`:
here::i_am("README.Rmd") #> here() starts at /home/kirill/git/R/here here() #> [1] "/home/kirill/git/R/here"You can build a path relative to the top-level directory in order to read or write a file:
here("inst", "demo-project", "data", "penguins.csv") #> [1] "/home/kirill/git/R/here/inst/demo-project/data/penguins.csv" readr::write_csv(palmerpenguins::penguins, here("inst", "demo-project", "data", "penguins.csv"))These relative paths work regardless of where the associated source file lives inside your project, like analysis projects with data and reports in different subdirectories. See the included [demo project](https://github.com/r-lib/here/tree/master/inst/demo-project) for an example.  *Illustration by [Allison Horst](https://github.com/allisonhorst)* ------------------------------------------------------------------------ ## Code of Conduct Please note that the here project is released with a [Contributor Code of Conduct](https://here.r-lib.org/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. here/man/ 0000755 0001762 0000144 00000000000 13754151372 011760 5 ustar ligges users here/man/dr_here.Rd 0000644 0001762 0000144 00000001030 13754151372 013651 0 ustar ligges users % Generated by roxygen2: do not edit by hand % Please edit documentation in R/dr_here.R \name{dr_here} \alias{dr_here} \title{Situation report} \usage{ dr_here(show_reason = TRUE) } \arguments{ \item{show_reason}{\verb{[logical(1)]}\cr Include reason in output of \code{dr_here()}, defaults to \code{TRUE}.} } \description{ \code{dr_here()} shows a message that by default also includes the reason why \code{here()} is set to a particular directory. Use this function if \code{here()} gives unexpected results. } \examples{ dr_here() } here/man/here.Rd 0000644 0001762 0000144 00000004415 13754151372 013176 0 ustar ligges users % Generated by roxygen2: do not edit by hand % Please edit documentation in R/here.R \name{here} \alias{here} \title{Find your files} \usage{ here(...) } \arguments{ \item{...}{\verb{[character]}\cr Path components below the project root, can be empty. Each argument should be a string containing one or more path components separated by a forward slash \code{"/"}.} } \description{ \code{here()} uses a reasonable heuristics to find your project's files, based on the current working directory at the time when the package is loaded. Use it as a drop-in replacement for \code{\link[=file.path]{file.path()}}, it will always locate the files relative to your project root. } \details{ This package is intended for interactive use only. Use \code{\link[rprojroot:root_criterion]{rprojroot::has_file()}} or the other functions in the \pkg{rprojroot} package for more control, or for package development. If \code{here()} raises an error or otherwise behaves unexpectedly, you may have attached \pkg{plyr} or another package after \pkg{here}. Correct this using \href{https://conflicted.r-lib.org/}{the \pkg{conflicted} package}, or use \code{here::here("data", "df.rda")}. } \examples{ here() \dontrun{ here("some", "path", "below", "your", "project", "root.txt") here("some/path/below/your/project/root.txt") } } \section{Project root}{ The project root is established with a call to \verb{here::}\code{\link[=i_am]{i_am()}}. Although not recommended, it can be changed by calling \code{here::i_am()} again. In the absence of such a call (e.g. for a new project), starting with the current working directory during package load time, the directory hierarchy is walked upwards until a directory with at least one of the following conditions is found: \itemize{ \item contains a file \code{.here} \item contains a file matching \verb{[.]Rproj$} with contents matching \verb{^Version: } in the first line \item contains a file \code{DESCRIPTION} with contents matching \verb{^Package: } \item contains a file \code{remake.yml} \item contains a file \code{.projectile} \item contains a directory \code{.git} \item contains a file \code{.git} with contents matching \verb{^gitdir: } \item contains a directory \code{.svn} } In either case, \code{here()} appends its arguments as path components to the root directory. } here/man/set_here.Rd 0000644 0001762 0000144 00000002247 13754150007 014044 0 ustar ligges users % Generated by roxygen2: do not edit by hand % Please edit documentation in R/set_here.R \name{set_here} \alias{set_here} \title{Add a marker file to a project} \usage{ set_here(path = ".", verbose = TRUE) } \arguments{ \item{path}{\verb{[character(1)]}\cr Directory where to create \code{.here} file, defaults to the current directory.} \item{verbose}{\verb{[logical(1)]}\cr Verbose output, defaults to \code{TRUE}.} } \description{ \ifelse{html}{\out{
}}{\strong{Superseded}}
}
\details{
\code{set_here()} creates an empty file named \code{.here}, by default
in the current directory.
When here encounters such a file, it uses the
directory that contains this file as root.
This is useful if none of the default criteria apply.
You need to restart the R session so that \code{here()}
picks up the newly created file.
}
\section{Life cycle}{
\code{set_here()} should no longer be necessary
if all scripts and reports in a project call \code{\link[=i_am]{i_am()}},
which is now the recommended workflow for declaring the project root.
}
\keyword{internal}
here/man/i_am.Rd 0000644 0001762 0000144 00000004304 13754150007 013147 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/i_am.R
\name{i_am}
\alias{i_am}
\title{Declare location of current script or report}
\usage{
i_am(path, ..., uuid = NULL)
}
\arguments{
\item{path}{\verb{[character(1)]}\cr
The path to the current script or report, relative to the project root.
Passing an absolute path raises an error.}
\item{...}{Must be empty, reserved for future use.}
\item{uuid}{\verb{[character(1)]}\cr
\ifelse{html}{\out{
}}{\strong{Experimental}})`
If not \code{NULL}, a unique string that is matched
against the first 100 lines of the file.
Use \code{\link[uuid:UUIDgenerate]{uuid::UUIDgenerate()}} to create a unique string
that can be used as a \code{uuid} argument.}
}
\value{
This function is called for its side effects.
}
\description{
Add a call to \code{here::i_am("The here package enables easy file referencing by using the top-level directory of a file project to easily build file paths. This article demonstrates the case where the working directory is set to a subdirectory of the project root, for instance when rendering an R Markdown document that lives in a subdirectory. See vignette("here") for a more general introduction.
For demonstration, this article uses a data analysis project that lives in /tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project on my machine. This is the project root. The path will most likely be different on your machine, the here package helps deal with this situation.
The project has the following structure:
#> /tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project
#> ├── analysis
#> │ └── report.Rmd
#> ├── data
#> │ └── penguins.csv
#> ├── demo-project.Rproj
#> └── prepare
#> └── penguins.RWhen report.Rmd is rendered, the working directory is internally set to <project root>/analysis by rmarkdown:
setwd(file.path(project_path, "analysis"))getwd()
#> [1] "/tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project/analysis"However, penguins.csv still lives in the data/ subdirectory. The report requires the penguins.csv file to work.
To render report.Rmd, you would have to ensure the path to penguins.csv is relative to the analysis/ directory - i.e., ../data/penguins.csv. The chunks would knit properly, but could not be run in the console since the working directory in the console isn’t analysis/.
The here package circumvents this issue by always referring to the project root:
here::i_am("analysis/report.Rmd")
#> here() starts at /tmp/RtmpnoXhd8/Rinst301434451937/here/demo-projectAll files accessed by report.Rmd should be referred to using here():
library(here)
here("data", "penguins.csv")
#> [1] "/tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project/data/penguins.csv"
here("data/penguins.csv")
#> [1] "/tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project/data/penguins.csv"This ensures that penguins.csv can be read both when the report is knit and when the code is run interactively in the console.
The here package enables easy file referencing by using the top-level directory of a file project to easily build file paths. This is in contrast to using setwd(), which is fragile and dependent on the way you order your files on your computer. Read more about project-oriented workflows:
What They Forgot to Teach You About R: “Project-oriented workflow” chapter by Jenny Bryan and Jim Hester
“Project-oriented workflow” blog post by Jenny Bryan
R for data science: “Workflow: projects” chapter by Hadley Wickham
For demonstration, this article uses a data analysis project that lives in /tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project on my machine. This is the project root. The path will most likely be different on your machine, the here package helps deal with this situation.
The project has the following structure:
#> /tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project
#> ├── analysis
#> │ └── report.Rmd
#> ├── data
#> │ └── penguins.csv
#> ├── demo-project.Rproj
#> └── prepare
#> └── penguins.RYou can review the project on GitHub and also download a copy.
To start working on this project in RStudio, open the demo-project.Rproj file. This ensures that the working directory is set to /tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project, the project root. Opening only the .R or the .Rmd file may be insufficient!
Other development environments may have a different notion of a project. Either way, it is important that the working directory is set to the project root or a subdirectory of that path. You can check with:
setwd(project_path)getwd()
#> [1] "/tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project"(See vignette("rmarkdown") for an example where the working directory is set to a subdirectory on start.)
The intended use is to add a call to here::i_am() at the beginning of your script or in the first chunk of your rmarkdown report.1 This achieves the following:
The first argument to here::i_am() should be the path to the current file, relative to the project root. The penguins.R script uses:
here::i_am("prepare/penguins.R")
#> here() starts at /tmp/RtmpnoXhd8/Rinst301434451937/here/demo-projecthere::i_am() displays the top-level directory of the current project. Because the project has a prepare/ directory in its root that contains penguins.R, it is correctly inferred as the project root.
After here::i_am(), insert library(here) to make the here() function available:3
library(here)The top-level directory is also returned from the here() function:
here()
#> [1] "/tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project"One important distinction from the working directory is that this remains stable even if the working directory is changed:
setwd("analysis")
getwd()
#> [1] "/tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project/analysis"
here()
#> [1] "/tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project"
setwd("..")(I suggest to steer clear from ever changing the working directory. This may not always be feasible, in particular if the working directory is changed by code that you do not control.)
You can build a path relative to the top-level directory in order to build the full path to a file:
here("data", "penguins.csv")
#> [1] "/tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project/data/penguins.csv"
readr::read_csv(
here("data", "penguins.csv"),
col_types = list(.default = readr::col_guess()),
n_max = 3
)
#> # A tibble: 3 x 8
#> species island bill_length_mm bill_depth_mm flipper_length_… body_mass_g sex
#> <chr> <chr> <dbl> <dbl> <dbl> <dbl> <chr>
#> 1 Adelie Torge… 39.1 18.7 181 3750 male
#> 2 Adelie Torge… 39.5 17.4 186 3800 fema…
#> 3 Adelie Torge… 40.3 18 195 3250 fema…
#> # … with 1 more variable: year <dbl>This works regardless of where the associated source file lives inside your project. With here(), the path will always be relative to the top-level project directory.
here() works very similarly to file.path() or fs::path(), you can pass path components or entire subpaths:
here("data/penguins.csv")
#> [1] "/tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project/data/penguins.csv"As seen above, here() returns absolute paths (starting with /, <drive letter>:\ or \\). This makes it safe to pass these paths to other functions, even if the working directory is changed along the way.
As of version 1.0.0, absolute paths passed to here() are returned unchanged. This means that you can safely use both absolute and project-relative paths in here().
data_path <- here("data")
here(data_path)
#> [1] "/tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project/data"
here(data_path, "penguins.csv")
#> [1] "/tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project/data/penguins.csv"The dr_here() function explains the reasoning behind choosing the project root:
dr_here()
#> here() starts at /tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project.
#> - This directory contains a file "prepare/penguins.R"
#> - Initial working directory: /tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project
#> - Current working directory: /tmp/RtmpnoXhd8/Rinst301434451937/here/demo-projectThe show_reason argument can be set to FALSE to reduce the output to one line:
dr_here(show_reason = FALSE)
#> here() starts at /tmp/RtmpnoXhd8/Rinst301434451937/here/demo-projectThe declaration of the active file via here::i_am() also protects against accidentally running the script from a working directory outside of your project. The example below calls here::i_am() from the temporary directory, which is clearly outside our project:
withr::with_dir(tempdir(), {
print(getwd())
here::i_am("prepare/penguins.R")
})
#> [1] "/tmp/RtmpHuFWzz"
#> Error: Could not find associated project in working directory or any parent directory.
#> - Path in project: prepare/penguins.R
#> - Current working directory: /tmp/RtmpHuFWzz
#> Please open the project associated with this file and try again.This can also happen when a file has been renamed or moved without updating the here::i_am() call. In the future, a helper function will assist with installing and updating suitably formatted here::i_am() calls in your scripts and reports.
Other packages also export a here() function. Loading these packages after loading here masks our here() function:
library(plyr)
#>
#> Attaching package: 'plyr'
#> The following object is masked from 'package:here':
#>
#> here
here()
#> Error in here(): argument "f" is missing, with no defaultOne way to work around this problem is to use here::here():
here::here()
#> [1] "/tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project"The conflicted package offers an alternative: it detects that here() is exported from more than one package and allows you to use neither until you indicate a preference.
library(conflicted)
here()
#> Error: [conflicted] `here` found in 2 packages.
#> Either pick the one you want with `::`
#> * plyr::here
#> * here::here
#> Or declare a preference with `conflict_prefer()`
#> * conflict_prefer("here", "plyr")
#> * conflict_prefer("here", "here")
conflicted::conflict_prefer("here", "here")
#> [conflicted] Will prefer here::here over any other package
here()
#> [1] "/tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project"To eliminate potential confusion, here::i_am() accepts a uuid argument. The idea is that each script and report calls here::i_am() very early (in the first 100 lines) with a universally unique identifier. Even if a file location is reused across projects (e.g. two projects contain a “prepare/data.R” file), the files can be identified correctly if the uuid argument in the here::i_am() call is different.
If a uuid argument is passed to here::i_am():
here::i_am() call that passes this very uuid is among those 100 lines, and will be matcheduuid is not found in the textUse uuid::UUIDgenerate() to create universally unique identifiers:
uuid::UUIDgenerate()
#> [1] "36f421ac-2d53-46d4-bfad-a0ac96491443"Ensure that the uuid arguments are actually unique across your files! In the future, a helper function will assist with installing and updating suitably formatted here::i_am() calls in your scripts and reports.
It is advisable to start a fresh R session as often as possible, especially before focusing on another project. There still may be legitimate cases when it is desirable to reset the project root.
To start, let’s create a temporary project for demonstration:
temp_project_path <- tempfile()
dir.create(temp_project_path)
scripts_path <- file.path(temp_project_path, "scripts")
dir.create(scripts_path)
script_path <- file.path(scripts_path, "script.R")
writeLines(
c(
'here::i_am("scripts/script.R")',
'print("Hello, world!")'
),
script_path
)
fs::dir_tree(temp_project_path)
#> /tmp/RtmpHuFWzz/file30547d5e00ca
#> └── scripts
#> └── script.R
writeLines(readLines(script_path))
#> here::i_am("scripts/script.R")
#> print("Hello, world!")The script.R file contains a call to here::i_am() to declare its location. Running it from the current working directory will fail:
source(script_path, echo = TRUE)
#>
#> > here::i_am("scripts/script.R")
#> Error: Could not find associated project in working directory or any parent directory.
#> - Path in project: scripts/script.R
#> - Current working directory: /tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project
#> Please open the project associated with this file and try again.To reset the project root mid-session, change the working directory with setwd(). Now, the subsequent call to here::i_am() from within script.R works:
setwd(temp_project_path)source(script_path, echo = TRUE)
#>
#> > here::i_am("scripts/script.R")
#> here() starts at /tmp/RtmpHuFWzz/file30547d5e00ca
#>
#> > print("Hello, world!")
#> [1] "Hello, world!"To reiterate: a fresh session is almost always the better, cleaner, safer, and more robust solution. Use this approach only as a last resort.
The here package has a very simple and restricted interface, by design. The underlying logic is provided by the much more powerful rprojroot package. If the default behavior of here does not suit your workflow for one reason or another, the rprojroot package may be a better alternative. It is also recommended to import rprojroot and not here from other packages.
The following example shows how to find an RStudio project starting from a directory:
library(rprojroot)
find_root(is_rstudio_project, file.path(project_path, "analysis"))
#> [1] "/tmp/RtmpnoXhd8/Rinst301434451937/here/demo-project"Arbitrary criteria can be defined. See vignette("rprojroot", package = "rprojroot") for an introduction.
Prior to version 1.0.0, it was recommended to attach the here package via library(here). This still works, but is no longer the recommended approach.↩︎
library(here) no longer emits an informative message if here::i_am() has been called before.↩︎
library(here) emits a message that may be confusing if followed by the message from here::i_am().↩︎