Title: | A Simpler Way to Find Your Files |
---|---|
Description: | Constructs paths to your project's files. Declare the relative path of a file within your project with 'i_am()'. Use the 'here()' function as a drop-in replacement for 'file.path()', it will always locate the files relative to your project root. |
Authors: | Kirill Müller [aut, cre] , Jennifer Bryan [ctb] |
Maintainer: | Kirill Müller <[email protected]> |
License: | MIT + file LICENSE |
Version: | 1.0.1.9022 |
Built: | 2024-11-10 02:21:01 UTC |
Source: | https://github.com/r-lib/here |
dr_here()
shows a message that by default also includes the
reason why here()
is set to a particular directory.
Use this function if here()
gives unexpected results.
dr_here(show_reason = TRUE)
dr_here(show_reason = TRUE)
show_reason |
|
dr_here()
dr_here()
here()
uses 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 file.path()
, it will always locate the
files relative to your project root.
here(...)
here(...)
... |
|
This package is intended for interactive use only.
Use rprojroot::has_file()
or the other functions in
the rprojroot package for more control,
or for package development.
If here()
raises an error or otherwise behaves unexpectedly,
you may have attached plyr or another package
after here.
Correct this using
the conflicted package,
or use here::here("data", "df.rda")
.
The project root is established with a call to here::
i_am()
.
Although not recommended, it can be changed by calling 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:
contains a file .here
contains a file matching [.]Rproj$
with contents matching ^Version:
in the first line
contains a file DESCRIPTION
with contents matching ^Package:
contains a file remake.yml
contains a file .projectile
contains a directory .git
contains a file .git
with contents matching ^gitdir:
contains a directory .svn
In either case, here()
appends its arguments as path components
to the root directory.
here() ## Not run: here("some", "path", "below", "your", "project", "root.txt") here("some/path/below/your/project/root.txt") ## End(Not run)
here() ## Not run: here("some", "path", "below", "your", "project", "root.txt") here("some/path/below/your/project/root.txt") ## End(Not run)
Add a call to here::i_am("<project-relative path>.<ext>")
at the top of your R script or in the first chunk of your rmarkdown document.
This ensures that the project root is set up correctly:
subsequent calls to here()
will refer to the implied project root.
If the current working directory is outside of the project
where the script or report is intended to run, it will fail
with a descriptive message.
i_am(path, ..., uuid = NULL)
i_am(path, ..., uuid = NULL)
path |
|
... |
Must be empty, reserved for future use. |
uuid |
If not |
Relying on the project root determined with a project file,
the default for versions prior to 1.0.0,
only weakly protects against running a script from an arbitrary directory
outside the intended project.
The i_am()
function offers a stronger way to define the project root:
it will ensure that the project root actually contains a file in that location,
optionally checking for file contents that uniquely identify the file
via the nonce
argument.
This function will fail if the script or report is moved within the project.
Update the i_am()
call to reflect the new location.
If you use the nonce
argument for extra safety, be sure to change it
when you save an existing script or report under a new name.
This function is called for its side effects.
## Not run: here::i_am("prepare/penguins.R") here::i_am("analysis/report.Rmd", uuid = "f9e884084b84794d762a535f3facec85") ## End(Not run)
## Not run: here::i_am("prepare/penguins.R") here::i_am("analysis/report.Rmd", uuid = "f9e884084b84794d762a535f3facec85") ## End(Not run)