usethis/ 0000755 0001762 0000144 00000000000 14451404262 011740 5 ustar ligges users usethis/NAMESPACE 0000644 0001762 0000144 00000012144 14442324752 013166 0 ustar ligges users # Generated by roxygen2: do not edit by hand
S3method(format,github_remote_config)
S3method(print,github_remote_config)
S3method(print,sitrep)
export(browse_circleci)
export(browse_cran)
export(browse_github)
export(browse_github_actions)
export(browse_github_issues)
export(browse_github_pat)
export(browse_github_pulls)
export(browse_github_token)
export(browse_package)
export(browse_project)
export(browse_travis)
export(create_download_url)
export(create_from_github)
export(create_github_token)
export(create_package)
export(create_project)
export(create_tidy_package)
export(edit_file)
export(edit_git_config)
export(edit_git_ignore)
export(edit_pkgdown_config)
export(edit_r_buildignore)
export(edit_r_environ)
export(edit_r_makevars)
export(edit_r_profile)
export(edit_rstudio_prefs)
export(edit_rstudio_snippets)
export(edit_template)
export(gh_token_help)
export(git_branch_default)
export(git_credentials)
export(git_default_branch)
export(git_default_branch_configure)
export(git_default_branch_rediscover)
export(git_default_branch_rename)
export(git_protocol)
export(git_remotes)
export(git_sitrep)
export(git_vaccinate)
export(github_token)
export(issue_close_community)
export(issue_reprex_needed)
export(local_project)
export(pr_fetch)
export(pr_finish)
export(pr_forget)
export(pr_init)
export(pr_merge_main)
export(pr_pause)
export(pr_pull)
export(pr_pull_upstream)
export(pr_push)
export(pr_resume)
export(pr_sync)
export(pr_view)
export(proj_activate)
export(proj_get)
export(proj_path)
export(proj_set)
export(proj_sitrep)
export(rename_files)
export(tidy_label_colours)
export(tidy_label_descriptions)
export(tidy_labels)
export(tidy_labels_rename)
export(ui_code)
export(ui_code_block)
export(ui_done)
export(ui_field)
export(ui_info)
export(ui_line)
export(ui_nope)
export(ui_oops)
export(ui_path)
export(ui_silence)
export(ui_stop)
export(ui_todo)
export(ui_unset)
export(ui_value)
export(ui_warn)
export(ui_yeah)
export(use_addin)
export(use_agpl3_license)
export(use_agpl_license)
export(use_apache_license)
export(use_apl2_license)
export(use_appveyor)
export(use_appveyor_badge)
export(use_article)
export(use_author)
export(use_badge)
export(use_binder_badge)
export(use_bioc_badge)
export(use_blank_slate)
export(use_build_ignore)
export(use_c)
export(use_cc0_license)
export(use_ccby_license)
export(use_circleci)
export(use_circleci_badge)
export(use_citation)
export(use_code_of_conduct)
export(use_conflicted)
export(use_course)
export(use_coverage)
export(use_covr_ignore)
export(use_cpp11)
export(use_cran_badge)
export(use_cran_comments)
export(use_data)
export(use_data_raw)
export(use_data_table)
export(use_description)
export(use_description_defaults)
export(use_dev_package)
export(use_dev_version)
export(use_devtools)
export(use_directory)
export(use_git)
export(use_git_config)
export(use_git_credentials)
export(use_git_hook)
export(use_git_ignore)
export(use_git_protocol)
export(use_git_remote)
export(use_github)
export(use_github_action)
export(use_github_action_check_full)
export(use_github_action_check_release)
export(use_github_action_check_standard)
export(use_github_action_pr_commands)
export(use_github_actions)
export(use_github_actions_badge)
export(use_github_file)
export(use_github_labels)
export(use_github_links)
export(use_github_pages)
export(use_github_release)
export(use_gitlab_ci)
export(use_gpl3_license)
export(use_gpl_license)
export(use_import_from)
export(use_jenkins)
export(use_latest_dependencies)
export(use_lgpl_license)
export(use_lifecycle)
export(use_lifecycle_badge)
export(use_logo)
export(use_make)
export(use_mit_license)
export(use_namespace)
export(use_news_md)
export(use_package)
export(use_package_doc)
export(use_partial_warnings)
export(use_pipe)
export(use_pkgdown)
export(use_pkgdown_github_pages)
export(use_pkgdown_travis)
export(use_posit_cloud_badge)
export(use_proprietary_license)
export(use_r)
export(use_rcpp)
export(use_rcpp_armadillo)
export(use_rcpp_eigen)
export(use_readme_md)
export(use_readme_rmd)
export(use_release_issue)
export(use_reprex)
export(use_revdep)
export(use_rmarkdown_template)
export(use_roxygen_md)
export(use_rscloud_badge)
export(use_rstudio)
export(use_rstudio_preferences)
export(use_spell_check)
export(use_standalone)
export(use_template)
export(use_test)
export(use_testthat)
export(use_tibble)
export(use_tidy_ci)
export(use_tidy_coc)
export(use_tidy_contributing)
export(use_tidy_dependencies)
export(use_tidy_description)
export(use_tidy_eval)
export(use_tidy_github)
export(use_tidy_github_actions)
export(use_tidy_github_labels)
export(use_tidy_issue_template)
export(use_tidy_labels)
export(use_tidy_logo)
export(use_tidy_style)
export(use_tidy_support)
export(use_tidy_thanks)
export(use_tidy_upkeep_issue)
export(use_travis)
export(use_travis_badge)
export(use_tutorial)
export(use_upkeep_issue)
export(use_usethis)
export(use_version)
export(use_vignette)
export(use_zip)
export(with_project)
export(write_over)
export(write_union)
import(fs)
import(rlang)
importFrom(glue,glue)
importFrom(glue,glue_collapse)
importFrom(glue,glue_data)
importFrom(lifecycle,deprecated)
importFrom(purrr,map)
importFrom(purrr,map_chr)
importFrom(purrr,map_int)
importFrom(purrr,map_lgl)
usethis/LICENSE 0000644 0001762 0000144 00000000055 14420343677 012755 0 ustar ligges users YEAR: 2020
COPYRIGHT HOLDER: usethis authors
usethis/README.md 0000644 0001762 0000144 00000011740 14451314627 013227 0 ustar ligges users
# usethis
[](https://github.com/r-lib/usethis/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/r-lib/usethis?branch=main)
[](https://CRAN.R-project.org/package=usethis)
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
[](https://github.com/r-lib/usethis/actions/workflows/.github/workflows/R-CMD-check.yaml)
usethis is a workflow package: it automates repetitive tasks that arise
during project setup and development, both for R packages and
non-package projects.
## Installation
Install the released version of usethis from CRAN:
``` r
install.packages("usethis")
```
Or install the development version from GitHub with:
``` r
# install.packages("pak")
pak::pak("r-lib/usethis")
```
## Usage
Most `use_*()` functions operate on the *active project*: literally, a
directory on your computer. If you’ve just used usethis to create a new
package or project, that will be the active project. Otherwise, usethis
verifies that current working directory is or is below a valid project
directory and that becomes the active project. Use `proj_get()` or
`proj_sitrep()` to manually query the project and [read more in the
docs](https://usethis.r-lib.org/reference/proj_utils.html).
A few usethis functions have no strong connections to projects and will
expect you to provide a path.
usethis is quite chatty, explaining what it’s doing and assigning you
tasks. `✔` indicates something usethis has done for you. `●` indicates
that you’ll need to do some work yourself.
Below is a quick look at how usethis can help to set up a package. But
remember, many usethis functions are also applicable to analytical
projects that are not packages.
``` r
library(usethis)
# Create a new package -------------------------------------------------
path <- file.path(tempdir(), "mypkg")
create_package(path)
#> ✔ Creating '/tmp/RtmpPqIkgo/mypkg/'
#> ✔ Setting active project to '/private/tmp/RtmpPqIkgo/mypkg'
#> ✔ Creating 'R/'
#> ✔ Writing 'DESCRIPTION'
#> Package: mypkg
#> Title: What the Package Does (One Line, Title Case)
#> Version: 0.0.0.9000
#> Authors@R (parsed):
#> * First Last [aut, cre] (YOUR-ORCID-ID)
#> Description: What the package does (one paragraph).
#> License: `use_mit_license()`, `use_gpl3_license()` or friends to pick a
#> license
#> Encoding: UTF-8
#> Roxygen: list(markdown = TRUE)
#> RoxygenNote: 7.2.3
#> ✔ Writing 'NAMESPACE'
#> ✔ Setting active project to ''
# only needed since this session isn't interactive
proj_activate(path)
#> ✔ Setting active project to '/private/tmp/RtmpPqIkgo/mypkg'
#> ✔ Changing working directory to '/tmp/RtmpPqIkgo/mypkg/'
# Modify the description ----------------------------------------------
use_mit_license("My Name")
#> ✔ Adding 'MIT + file LICENSE' to License
#> ✔ Writing 'LICENSE'
#> ✔ Writing 'LICENSE.md'
#> ✔ Adding '^LICENSE\\.md$' to '.Rbuildignore'
use_package("ggplot2", "Suggests")
#> ✔ Adding 'ggplot2' to Suggests field in DESCRIPTION
#> • Use `requireNamespace("ggplot2", quietly = TRUE)` to test if package is installed
#> • Then directly refer to functions with `ggplot2::fun()`
# Set up other files -------------------------------------------------
use_readme_md()
#> ✔ Writing 'README.md'
#> • Update 'README.md' to include installation instructions.
use_news_md()
#> ✔ Writing 'NEWS.md'
use_test("my-test")
#> ✔ Adding 'testthat' to Suggests field in DESCRIPTION
#> ✔ Adding '3' to Config/testthat/edition
#> ✔ Creating 'tests/testthat/'
#> ✔ Writing 'tests/testthat.R'
#> ✔ Writing 'tests/testthat/test-my-test.R'
#> • Edit 'tests/testthat/test-my-test.R'
x <- 1
y <- 2
use_data(x, y)
#> ✔ Adding 'R' to Depends field in DESCRIPTION
#> ✔ Creating 'data/'
#> ✔ Setting LazyData to 'true' in 'DESCRIPTION'
#> ✔ Saving 'x', 'y' to 'data/x.rda', 'data/y.rda'
#> • Document your data (see 'https://r-pkgs.org/data.html')
# Use git ------------------------------------------------------------
use_git()
#> ✔ Initialising Git repo
#> ✔ Adding '.Rproj.user', '.Rhistory', '.Rdata', '.httr-oauth', '.DS_Store', '.quarto' to '.gitignore'
```
## Code of Conduct
Please note that the usethis project is released with a [Contributor
Code of Conduct](https://usethis.r-lib.org/CODE_OF_CONDUCT.html). By
contributing to this project, you agree to abide by its terms.
usethis/man/ 0000755 0001762 0000144 00000000000 14447377413 012527 5 ustar ligges users usethis/man/rename_files.Rd 0000644 0001762 0000144 00000001600 14420343677 015440 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rename-files.R
\name{rename_files}
\alias{rename_files}
\title{Automatically rename paired \verb{R/} and \verb{test/} files}
\usage{
rename_files(old, new)
}
\arguments{
\item{old, new}{Old and new file names (with or without extensions).}
}
\description{
\itemize{
\item Moves \verb{R/\{old\}.R} to \verb{R/\{new\}.R}
\item Moves \verb{src/\{old\}.*} to \verb{src/\{new\}.*}
\item Moves \verb{tests/testthat/test-\{old\}.R} to \verb{tests/testthat/test-\{new\}.R}
\item Moves \verb{tests/testthat/test-\{old\}-*.*} to \verb{tests/testthat/test-\{new\}-*.*}
and updates paths in the test file.
\item Removes \code{context()} calls from the test file, which are unnecessary
(and discouraged) as of testthat v2.1.0.
}
This is a potentially dangerous operation, so you must be using Git in
order to use this function.
}
usethis/man/usethis-package.Rd 0000644 0001762 0000144 00000002444 14442324752 016070 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/usethis-package.R
\docType{package}
\name{usethis-package}
\alias{usethis}
\alias{usethis-package}
\title{usethis: Automate Package and Project Setup}
\description{
\if{html}{\figure{logo.png}{options: style='float: right' alt='logo' width='120'}}
Automate package and project setup tasks that are otherwise performed manually. This includes setting up unit testing, test coverage, continuous integration, Git, 'GitHub', licenses, 'Rcpp', 'RStudio' projects, and more.
}
\seealso{
Useful links:
\itemize{
\item \url{https://usethis.r-lib.org}
\item \url{https://github.com/r-lib/usethis}
\item Report bugs at \url{https://github.com/r-lib/usethis/issues}
}
}
\author{
\strong{Maintainer}: Jennifer Bryan \email{jenny@posit.co} (\href{https://orcid.org/0000-0002-6983-2759}{ORCID})
Authors:
\itemize{
\item Hadley Wickham \email{hadley@posit.co} (\href{https://orcid.org/0000-0003-4757-117X}{ORCID})
\item Malcolm Barrett \email{malcolmbarrett@gmail.com} (\href{https://orcid.org/0000-0003-0299-5825}{ORCID})
\item Andy Teucher \email{andy.teucher@posit.co} (\href{https://orcid.org/0000-0002-7840-692X}{ORCID})
}
Other contributors:
\itemize{
\item Posit Software, PBC [copyright holder, funder]
}
}
\keyword{internal}
usethis/man/use_make.Rd 0000644 0001762 0000144 00000000542 14420343677 014604 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/make.R
\name{use_make}
\alias{use_make}
\title{Create Makefile}
\usage{
use_make()
}
\description{
\code{use_make()} adds a basic Makefile to the project root directory.
}
\seealso{
The \href{https://www.gnu.org/software/make/manual/html_node/}{documentation for GNU Make}.
}
usethis/man/browse_github_token.Rd 0000644 0001762 0000144 00000001615 14420343677 017060 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/usethis-defunct.R
\name{browse_github_token}
\alias{browse_github_token}
\alias{browse_github_pat}
\alias{github_token}
\alias{git_branch_default}
\title{Defunct GitHub functions}
\usage{
browse_github_token(...)
browse_github_pat(...)
github_token()
git_branch_default()
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#defunct}{\figure{lifecycle-defunct.svg}{options: alt='[Defunct]'}}}{\strong{[Defunct]}}
\itemize{
\item \code{browse_github_token()} and \code{browse_github_pat()} have been replaced by
\code{\link[=create_github_token]{create_github_token()}}.
\item \code{github_token()} has been replaced by \code{\link[gh:gh_token]{gh::gh_token()}}
\item \code{git_branch_default()} has been replaced by \code{\link[=git_default_branch]{git_default_branch()}}.
}
}
\keyword{internal}
usethis/man/use_git_ignore.Rd 0000644 0001762 0000144 00000001045 14420343677 016014 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/git.R
\name{use_git_ignore}
\alias{use_git_ignore}
\title{Tell Git to ignore files}
\usage{
use_git_ignore(ignores, directory = ".")
}
\arguments{
\item{ignores}{Character vector of ignores, specified as file globs.}
\item{directory}{Directory relative to active project to set ignores}
}
\description{
Tell Git to ignore files
}
\seealso{
Other git helpers:
\code{\link{use_git_config}()},
\code{\link{use_git_hook}()},
\code{\link{use_git}()}
}
\concept{git helpers}
usethis/man/use_blank_slate.Rd 0000644 0001762 0000144 00000001557 14420343677 016155 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rstudio.R
\name{use_blank_slate}
\alias{use_blank_slate}
\title{Don't save/load user workspace between sessions}
\usage{
use_blank_slate(scope = c("user", "project"))
}
\arguments{
\item{scope}{Edit globally for the current \strong{user}, or locally for the
current \strong{project}}
}
\description{
R can save and reload the user's workspace between sessions via an \code{.RData}
file in the current directory. However, long-term reproducibility is enhanced
when you turn this feature off and clear R's memory at every restart.
Starting with a blank slate provides timely feedback that encourages the
development of scripts that are complete and self-contained. More detail can
be found in the blog post \href{https://www.tidyverse.org/blog/2017/12/workflow-vs-script/}{Project-oriented workflow}.
}
usethis/man/use_rmarkdown_template.Rd 0000644 0001762 0000144 00000002234 14420343677 017566 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rmarkdown.R
\name{use_rmarkdown_template}
\alias{use_rmarkdown_template}
\title{Add an RMarkdown Template}
\usage{
use_rmarkdown_template(
template_name = "Template Name",
template_dir = NULL,
template_description = "A description of the template",
template_create_dir = FALSE
)
}
\arguments{
\item{template_name}{The name as printed in the template menu.}
\item{template_dir}{Name of the directory the template will live in within
\code{inst/rmarkdown/templates}. If none is provided by the user, it will be
created from \code{template_name}.}
\item{template_description}{Sets the value of \code{description} in
\code{template.yml}.}
\item{template_create_dir}{Sets the value of \code{create_dir} in \code{template.yml}.}
}
\description{
Adds files and directories necessary to add a custom rmarkdown template to
RStudio. It creates:
\itemize{
\item \code{inst/rmarkdown/templates/{{template_dir}}}. Main directory.
\item \code{skeleton/skeleton.Rmd}. Your template Rmd file.
\item \code{template.yml} with basic information filled in.
}
}
\examples{
\dontrun{
use_rmarkdown_template()
}
}
usethis/man/use_lifecycle.Rd 0000644 0001762 0000144 00000001337 14420343677 015631 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle.R
\name{use_lifecycle}
\alias{use_lifecycle}
\title{Use lifecycle badges}
\usage{
use_lifecycle()
}
\description{
This helper:
\itemize{
\item Adds lifecycle as a dependency.
\item Imports \code{\link[lifecycle:deprecated]{lifecycle::deprecated()}} for use in function arguments.
\item Copies the lifecycle badges into \code{man/figures}.
\item Reminds you how to use the badge syntax.
}
Learn more at \url{https://lifecycle.r-lib.org/articles/communicate.html}
}
\seealso{
\code{\link[=use_lifecycle_badge]{use_lifecycle_badge()}} to signal the
\href{https://lifecycle.r-lib.org/articles/stages.html}{lifecycle stage} of
your package as whole
}
usethis/man/use_author.Rd 0000644 0001762 0000144 00000005412 14442324752 015167 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/author.R
\name{use_author}
\alias{use_author}
\title{Add an author to the \code{Authors@R} field in DESCRIPTION}
\usage{
use_author(given = NULL, family = NULL, ..., role = "ctb")
}
\arguments{
\item{given}{a character vector with the \emph{given} names,
or a list thereof.}
\item{family}{a character string with the \emph{family} name,
or a list thereof.}
\item{...}{
Arguments passed on to \code{\link[utils:person]{utils::person}}
\describe{
\item{\code{middle}}{a character string with the collapsed middle name(s).
Deprecated, see \bold{Details}.}
\item{\code{email}}{a character string (or vector) giving an e-mail address
(each),
or a list thereof.}
\item{\code{comment}}{a character string (or vector) providing comments,
or a list thereof.}
\item{\code{first}}{a character string giving the first name.
Deprecated, see \bold{Details}.}
\item{\code{last}}{a character string giving the last name.
Deprecated, see \bold{Details}.}
}}
\item{role}{a character vector specifying the role(s) of the person
(see \bold{Details}),
or a list thereof.}
}
\description{
\code{use_author()} adds a person to the \code{Authors@R} field of the DESCRIPTION
file, creating that field if necessary. It will not modify, e.g., the role(s)
or email of an existing author (judged using their "Given Family" name). For
that we recommend editing DESCRIPTION directly. Or, for programmatic use,
consider calling the more specialized functions available in the \pkg{desc}
package directly.
\code{use_author()} also surfaces two other situations you might want to address:
\itemize{
\item Explicit use of the fields \code{Author} or \code{Maintainer}. We recommend switching
to the more modern \code{Authors@R} field instead, because it offers richer
metadata for various downstream uses. (Note that \code{Authors@R} is \emph{eventually}
processed to create \code{Author} and \code{Maintainer} fields, but only when the
\code{tar.gz} is built from package source.)
\item Presence of the fake author placed by \code{\link[=create_package]{create_package()}} and
\code{\link[=use_description]{use_description()}}. This happens when \pkg{usethis} has to create a
DESCRIPTION file and the user hasn't given any author information via the
\code{fields} argument or the global option \code{"usethis.description"}. The
placeholder looks something like \verb{First Last [aut, cre] (YOUR-ORCID-ID)} and \code{use_author()} offers to remove it in interactive
sessions.
}
}
\examples{
\dontrun{
use_author(
given = "Lucy",
family = "van Pelt",
role = c("aut", "cre"),
email = "lucy@example.com",
comment = c(ORCID = "LUCY-ORCID-ID")
)
use_author("Charlie", "Brown")
}
}
usethis/man/pull-requests.Rd 0000644 0001762 0000144 00000023603 14420343677 015643 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pr.R
\name{pull-requests}
\alias{pull-requests}
\alias{pr_init}
\alias{pr_resume}
\alias{pr_fetch}
\alias{pr_push}
\alias{pr_pull}
\alias{pr_merge_main}
\alias{pr_view}
\alias{pr_pause}
\alias{pr_finish}
\alias{pr_forget}
\title{Helpers for GitHub pull requests}
\usage{
pr_init(branch)
pr_resume(branch = NULL)
pr_fetch(number = NULL, target = c("source", "primary"))
pr_push()
pr_pull()
pr_merge_main()
pr_view(number = NULL, target = c("source", "primary"))
pr_pause()
pr_finish(number = NULL, target = c("source", "primary"))
pr_forget()
}
\arguments{
\item{branch}{Name of a new or existing local branch. If creating a new
branch, note this should usually consist of lower case letters, numbers,
and \code{-}.}
\item{number}{Number of PR.}
\item{target}{Which repo to target? This is only a question in the case of a
fork. In a fork, there is some slim chance that you want to consider pull
requests against your fork (the primary repo, i.e. \code{origin}) instead of
those against the source repo (i.e. \code{upstream}, which is the default).}
}
\description{
The \verb{pr_*} family of functions is designed to make working with GitHub pull
requests (PRs) as painless as possible for both contributors and package
maintainers.
To use the \verb{pr_*} functions, your project must be a Git repo and have one of
these GitHub remote configurations:
\itemize{
\item "ours": You can push to the GitHub remote configured as \code{origin} and it's
not a fork.
\item "fork": You can push to the GitHub remote configured as \code{origin}, it's a
fork, and its parent is configured as \code{upstream}. \code{origin} points to your
\strong{personal} copy and \code{upstream} points to the \strong{source repo}.
}
"Ours" and "fork" are two of several GitHub remote configurations examined in
\href{https://happygitwithr.com/common-remote-setups.html}{Common remote setups}
in Happy Git and GitHub for the useR.
The \href{https://usethis.r-lib.org/articles/articles/pr-functions.html}{Pull Request Helpers}
article walks through the process of making a pull request with the \verb{pr_*}
functions.
The \verb{pr_*} functions also use your Git/GitHub credentials to carry out
various remote operations; see below for more about auth. The \verb{pr_*}
functions also proactively check for agreement re: the default branch in your
local repo and the source repo. See \code{\link[=git_default_branch]{git_default_branch()}} for more.
}
\section{Git/GitHub Authentication}{
Many usethis functions, including those documented here, potentially interact
with GitHub in two different ways:
\itemize{
\item Via the GitHub REST API. Examples: create a repo, a fork, or a pull
request.
\item As a conventional Git remote. Examples: clone, fetch, or push.
}
Therefore two types of auth can happen and your credentials must be
discoverable. Which credentials do we mean?
\itemize{
\item A GitHub personal access token (PAT) must be discoverable by the gh
package, which is used for GitHub operations via the REST API. See
\code{\link[=gh_token_help]{gh_token_help()}} for more about getting and configuring a PAT.
\item If you use the HTTPS protocol for Git remotes, your PAT is also used for
Git operations, such as \verb{git push}. Usethis uses the gert package for this,
so the PAT must be discoverable by gert. Generally gert and gh will
discover and use the same PAT. This ability to "kill two birds with one
stone" is why HTTPS + PAT is our recommended auth strategy for those new
to Git and GitHub and PRs.
\item If you use SSH remotes, your SSH keys must also be discoverable, in
addition to your PAT. The public key must be added to your GitHub account.
}
Git/GitHub credential management is covered in a dedicated article:
\href{https://usethis.r-lib.org/articles/articles/git-credentials.html}{Managing Git(Hub) Credentials}
}
\section{For contributors}{
To contribute to a package, first use \code{create_from_github("OWNER/REPO")}.
This forks the source repository and checks out a local copy.
Next use \code{pr_init()} to create a branch for your PR. It is best practice to
never make commits to the default branch branch of a fork (usually named
\code{main} or \code{master}), because you do not own it. A pull request should always
come from a feature branch. It will be much easier to pull upstream changes
from the fork parent if you only allow yourself to work in feature branches.
It is also much easier for a maintainer to explore and extend your PR if you
create a feature branch.
Work locally, in your branch, making changes to files, and committing your
work. Once you're ready to create the PR, run \code{pr_push()} to push your local
branch to GitHub, and open a webpage that lets you initiate the PR (or draft
PR).
To learn more about the process of making a pull request, read the \href{https://usethis.r-lib.org/articles/articles/pr-functions.html}{Pull Request Helpers}
vignette.
If you are lucky, your PR will be perfect, and the maintainer will accept it.
You can then run \code{pr_finish()} to delete your PR branch. In most cases,
however, the maintainer will ask you to make some changes. Make the changes,
then run \code{pr_push()} to update your PR.
It's also possible that the maintainer will contribute some code to your PR:
to get those changes back onto your computer, run \code{pr_pull()}. It can also
happen that other changes have occurred in the package since you first
created your PR. You might need to merge the default branch (usually named
\code{main} or \code{master}) into your PR branch. Do that by running
\code{pr_merge_main()}: this makes sure that your PR is compatible with the
primary repo's main line of development. Both \code{pr_pull()} and
\code{pr_merge_main()} can result in merge conflicts, so be prepared to resolve
before continuing.
}
\section{For maintainers}{
To download a PR locally so that you can experiment with it, run
\code{pr_fetch()} and select the PR or, if you already know its number, call
\verb{pr_fetch()}. If you make changes, run \code{pr_push()} to push them
back to GitHub. After you have merged the PR, run \code{pr_finish()} to delete the
local branch and remove the remote associated with the contributor's fork.
}
\section{Overview of all the functions}{
\itemize{
\item \code{pr_init()}: As a contributor, start work on a new PR by ensuring that
your local repo is up-to-date, then creating and checking out a new branch.
Nothing is pushed to or created on GitHub until you call \code{pr_push()}.
\item \code{pr_fetch()}: As a maintainer, review or contribute changes to an existing
PR by creating a local branch that tracks the remote PR. \code{pr_fetch()} does as
little work as possible, so you can also use it to resume work on an PR that
already has a local branch (where it will also ensure your local branch is
up-to-date). If called with no arguments, up to 9 open PRs are offered for
interactive selection.
\item \code{pr_resume()}: Resume work on a PR by switching to an existing local branch
and pulling any changes from its upstream tracking branch, if it has one. If
called with no arguments, up to 9 local branches are offered for interactive
selection, with a preference for branches connected to PRs and for branches
with recent activity.
\item \code{pr_push()}: The first time it's called, a PR branch is pushed to GitHub
and you're taken to a webpage where a new PR (or draft PR) can be created.
This also sets up the local branch to track its remote counterpart.
Subsequent calls to \code{pr_push()} make sure the local branch has all the remote
changes and, if so, pushes local changes, thereby updating the PR.
\item \code{pr_pull()}: Pulls changes from the local branch's remote tracking branch.
If a maintainer has extended your PR, this is how you bring those changes
back into your local work.
\item \code{pr_merge_main()}: Pulls changes from the default branch of the source repo
into the current local branch. This can be used when the local branch is the
default branch or when it's a PR branch.
\item \code{pr_pause()}: Makes sure you're up-to-date with any remote changes in the
PR. Then switches back to the default branch and pulls from the source repo.
Use \code{pr_resume()} with name of branch or use \code{pr_fetch()} to resume using PR
number.
\item \code{pr_view()}: Visits the PR associated with the current branch in the
browser (default) or the specific PR identified by \code{number}.
(FYI \code{\link[=browse_github_pulls]{browse_github_pulls()}} is a handy way to visit the list of all PRs for
the current project.)
\item \code{pr_forget()}: Does local clean up when the current branch is an actual or
notional PR that you want to abandon. Maybe you initiated it yourself, via
\code{pr_init()}, or you used \code{pr_fetch()} to explore a PR from GitHub. Only does
\emph{local} operations: does not update or delete any remote branches, nor does
it close any PRs. Alerts the user to any uncommitted or unpushed work that is
at risk of being lost. If user chooses to proceed, switches back to the
default branch, pulls changes from source repo, and deletes local PR branch.
Any associated Git remote is deleted, if the "forgotten" PR was the only
branch using it.
\item \code{pr_finish()}: Does post-PR clean up, but does NOT actually merge or close
a PR (maintainer should do this in the browser). If \code{number} is not given,
infers the PR from the upstream tracking branch of the current branch. If
\code{number} is given, it does not matter whether the PR exists locally. If PR
exists locally, alerts the user to uncommitted or unpushed changes, then
switches back to the default branch, pulls changes from source repo, and
deletes local PR branch. If the PR came from an external fork, any associated
Git remote is deleted, provided it's not in use by any other local branches.
If the PR has been merged and user has permission, deletes the remote branch
(this is the only remote operation that \code{pr_finish()} potentially does).
}
}
\examples{
\dontrun{
pr_fetch(123)
}
}
usethis/man/use_vignette.Rd 0000644 0001762 0000144 00000002304 14420343677 015512 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vignette.R
\name{use_vignette}
\alias{use_vignette}
\alias{use_article}
\title{Create a vignette or article}
\usage{
use_vignette(name, title = name)
use_article(name, title = name)
}
\arguments{
\item{name}{Base for file name to use for new vignette. Should consist only
of numbers, letters, \verb{_} and \code{-}. Lower case is recommended.}
\item{title}{The title of the vignette.}
}
\description{
Creates a new vignette or article in \verb{vignettes/}. Articles are a special
type of vignette that appear on pkgdown websites, but are not included
in the package itself (because they are added to \code{.Rbuildignore}
automatically).
}
\section{General setup}{
\itemize{
\item Adds needed packages to \code{DESCRIPTION}.
\item Adds \code{inst/doc} to \code{.gitignore} so built vignettes aren't tracked.
\item Adds \verb{vignettes/*.html} and \verb{vignettes/*.R} to \code{.gitignore} so
you never accidentally track rendered vignettes.
}
}
\examples{
\dontrun{
use_vignette("how-to-do-stuff", "How to do stuff")
}
}
\seealso{
The \href{https://r-pkgs.org/vignettes.html}{vignettes chapter} of
\href{https://r-pkgs.org}{R Packages}.
}
usethis/man/pr_pull_upstream.Rd 0000644 0001762 0000144 00000001270 14420343677 016407 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/usethis-defunct.R
\name{pr_pull_upstream}
\alias{pr_pull_upstream}
\alias{pr_sync}
\title{Defunct PR functions}
\usage{
pr_pull_upstream()
pr_sync()
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#defunct}{\figure{lifecycle-defunct.svg}{options: alt='[Defunct]'}}}{\strong{[Defunct]}}
\itemize{
\item \code{pr_pull_upstream()} has been replaced by \code{\link[=pr_merge_main]{pr_merge_main()}}.
\item \code{pr_sync()} has been replaced by \code{\link[=pr_pull]{pr_pull()}} + \code{\link[=pr_merge_main]{pr_merge_main()}} + \code{\link[=pr_push]{pr_push()}}
}
}
\keyword{internal}
usethis/man/issue-this.Rd 0000644 0001762 0000144 00000002554 14420343677 015115 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/issue.R
\name{issue-this}
\alias{issue-this}
\alias{issue_close_community}
\alias{issue_reprex_needed}
\title{Helpers for GitHub issues}
\usage{
issue_close_community(number, reprex = FALSE)
issue_reprex_needed(number)
}
\arguments{
\item{number}{Issue number}
\item{reprex}{Does the issue also need a reprex?}
}
\description{
The \verb{issue_*} family of functions allows you to perform common operations on
GitHub issues from within R. They're designed to help you efficiently deal
with large numbers of issues, particularly motivated by the challenges faced
by the tidyverse team.
\itemize{
\item \code{issue_close_community()} closes an issue, because it's not a bug report or
feature request, and points the author towards RStudio Community as a
better place to discuss usage (\url{https://community.rstudio.com}).
\item \code{issue_reprex_needed()} labels the issue with the "reprex" label and
gives the author some advice about what is needed.
}
}
\section{Saved replies}{
Unlike GitHub's "saved replies", these functions can:
\itemize{
\item Be shared between people
\item Perform other actions, like labelling, or closing
\item Have additional arguments
\item Include randomness (like friendly gifs)
}
}
\examples{
\dontrun{
issue_close_community(12, reprex = TRUE)
issue_reprex_needed(241)
}
}
usethis/man/use_jenkins.Rd 0000644 0001762 0000144 00000001204 14420343677 015324 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/jenkins.R
\name{use_jenkins}
\alias{use_jenkins}
\title{Create Jenkinsfile for Jenkins CI Pipelines}
\usage{
use_jenkins()
}
\description{
\code{use_jenkins()} adds a basic Jenkinsfile for R packages to the project root
directory. The Jenkinsfile stages take advantage of calls to \code{make}, and so
calling this function will also run \code{use_make()} if a Makefile does not
already exist at the project root.
}
\seealso{
The \href{https://www.jenkins.io/doc/book/pipeline/jenkinsfile/}{documentation on Jenkins Pipelines}.
\code{\link[=use_make]{use_make()}}
}
usethis/man/use_addin.Rd 0000644 0001762 0000144 00000001222 14420343677 014742 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/addin.R
\name{use_addin}
\alias{use_addin}
\title{Add minimal RStudio Addin binding}
\usage{
use_addin(addin = "new_addin", open = rlang::is_interactive())
}
\arguments{
\item{addin}{Name of the addin function, which should be defined in the
\code{R} folder.}
\item{open}{Open the newly created file for editing? Happens in RStudio, if
applicable, or via \code{\link[utils:file.edit]{utils::file.edit()}} otherwise.}
}
\description{
This function helps you add a minimal
\href{https://rstudio.github.io/rstudioaddins/}{RStudio Addin} binding to
\code{inst/rstudio/addins.dcf}.
}
usethis/man/use_github_actions.Rd 0000644 0001762 0000144 00000003052 14420343677 016670 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/usethis-defunct.R
\name{use_github_actions}
\alias{use_github_actions}
\alias{use_github_action_check_release}
\alias{use_github_action_check_standard}
\alias{use_github_action_pr_commands}
\alias{use_github_action_check_full}
\title{Defunct GitHub Actions workflows}
\usage{
use_github_actions()
use_github_action_check_release(
save_as = "R-CMD-check.yaml",
ref = NULL,
ignore = TRUE,
open = FALSE
)
use_github_action_check_standard(
save_as = "R-CMD-check.yaml",
ref = NULL,
ignore = TRUE,
open = FALSE
)
use_github_action_pr_commands(
save_as = "pr-commands.yaml",
ref = NULL,
ignore = TRUE,
open = FALSE
)
use_github_action_check_full(
save_as = "R-CMD-check.yaml",
ignore = TRUE,
open = FALSE,
repo_spec = NULL
)
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
\itemize{
\item \code{use_github_actions()} is deprecated because it was just an alias
for \code{\link[=use_github_action_check_release]{use_github_action_check_release()}}.
\item \code{use_github_action_check_full()} is overkill for most packages and is
not recommended.
\item \code{use_github_action_check_release()}, \code{use_github_action_check_standard()},
and \code{use_github_action_pr_commands()} are deprecated in favor of
\code{\link[=use_github_action]{use_github_action()}}, which can now suggest specific workflows to use.
}
}
\keyword{internal}
usethis/man/use_cran_comments.Rd 0000644 0001762 0000144 00000001454 14420343677 016522 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cran.R
\name{use_cran_comments}
\alias{use_cran_comments}
\title{CRAN submission comments}
\usage{
use_cran_comments(open = rlang::is_interactive())
}
\arguments{
\item{open}{Open the newly created file for editing? Happens in RStudio, if
applicable, or via \code{\link[utils:file.edit]{utils::file.edit()}} otherwise.}
}
\description{
Creates \code{cran-comments.md}, a template for your communications with CRAN when
submitting a package. The goal is to clearly communicate the steps you have
taken to check your package on a wide range of operating systems. If you are
submitting an update to a package that is used by other packages, you also
need to summarize the results of your \link[=use_revdep]{reverse dependency checks}.
}
usethis/man/use_upkeep_issue.Rd 0000644 0001762 0000144 00000001743 14442324752 016371 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/upkeep.R
\name{use_upkeep_issue}
\alias{use_upkeep_issue}
\title{Create an upkeep checklist in a GitHub issue}
\usage{
use_upkeep_issue(year = NULL)
}
\arguments{
\item{year}{Year you are performing the upkeep, used in the issue title.
Defaults to current year}
}
\description{
This opens an issue in your package repository with a checklist of tasks for
regular maintenance of your package. This is a fairly opinionated list of
tasks but we believe taking care of them will generally make your package
better, easier to maintain, and more enjoyable for your users. Some of the
tasks are meant to be performed only once (and once completed shouldn't show
up in subsequent lists), and some should be reviewed periodically. The
tidyverse team uses a similar function \code{\link[=use_tidy_upkeep_issue]{use_tidy_upkeep_issue()}} for our
annual package Spring Cleaning.
}
\examples{
\dontrun{
use_upkeep_issue(2023)
}
}
usethis/man/use_tibble.Rd 0000644 0001762 0000144 00000002714 14420343677 015133 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tibble.R
\name{use_tibble}
\alias{use_tibble}
\title{Prepare to return a tibble}
\usage{
use_tibble()
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#questioning}{\figure{lifecycle-questioning.svg}{options: alt='[Questioning]'}}}{\strong{[Questioning]}}
Does minimum setup such that a tibble returned by your package
is handled using the tibble method for generics like \code{print()} or \code{[}.
Presumably you care about this if you've chosen to store and expose an
object with class \code{tbl_df}. Specifically:
\itemize{
\item Check that the active package uses roxygen2
\item Add the tibble package to "Imports" in \code{DESCRIPTION}
\item Prepare the roxygen directive necessary to import at least one function
from tibble:
\itemize{
\item If possible, the directive is inserted into existing package-level
documentation, i.e. the roxygen snippet created by \code{\link[=use_package_doc]{use_package_doc()}}
\item Otherwise, we issue advice on where the user should add the directive
}
}
This is necessary when your package returns a stored data object that has
class \code{tbl_df}, but the package code does not make direct use of functions
from the tibble package. If you do nothing, the tibble namespace is not
necessarily loaded and your tibble may therefore be printed and subsetted
like a base \code{data.frame}.
}
\examples{
\dontrun{
use_tibble()
}
}
usethis/man/use_citation.Rd 0000644 0001762 0000144 00000000442 13676400413 015472 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/citation.R
\name{use_citation}
\alias{use_citation}
\title{Create a CITATION template}
\usage{
use_citation()
}
\description{
Use this if you want to encourage users of your package to cite an
article or book.
}
usethis/man/use_directory.Rd 0000644 0001762 0000144 00000001271 13676400413 015665 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/directory.R
\name{use_directory}
\alias{use_directory}
\title{Use a directory}
\usage{
use_directory(path, ignore = FALSE)
}
\arguments{
\item{path}{Path of the directory to create, relative to the project.}
\item{ignore}{Should the newly created file be added to \code{.Rbuildignore}?}
}
\description{
\code{use_directory()} creates a directory (if it does not already exist) in the
project's top-level directory. This function powers many of the other \code{use_}
functions such as \code{\link[=use_data]{use_data()}} and \code{\link[=use_vignette]{use_vignette()}}.
}
\examples{
\dontrun{
use_directory("inst")
}
}
usethis/man/badges.Rd 0000644 0001762 0000144 00000005717 14442324752 014246 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/badge.R
\name{badges}
\alias{badges}
\alias{use_badge}
\alias{use_cran_badge}
\alias{use_bioc_badge}
\alias{use_lifecycle_badge}
\alias{use_binder_badge}
\alias{use_posit_cloud_badge}
\alias{use_rscloud_badge}
\title{README badges}
\usage{
use_badge(badge_name, href, src)
use_cran_badge()
use_bioc_badge()
use_lifecycle_badge(stage)
use_binder_badge(ref = git_default_branch(), urlpath = NULL)
use_posit_cloud_badge(url)
use_rscloud_badge(url)
}
\arguments{
\item{badge_name}{Badge name. Used in error message and alt text}
\item{href, src}{Badge link and image src}
\item{stage}{Stage of the package lifecycle. One of "experimental",
"stable", "superseded", or "deprecated".}
\item{ref}{A Git branch, tag, or SHA}
\item{urlpath}{An optional \code{urlpath} component to add to the link, e.g.
\code{"rstudio"} to open an RStudio IDE instead of a Jupyter notebook. See the
\href{https://mybinder.readthedocs.io/en/latest/howto/user_interface.html}{binder documentation}
for additional examples.}
\item{url}{A link to an existing \href{https://posit.cloud}{Posit Cloud}
project. See the \href{https://posit.cloud/learn/guide#project-settings-access}{Posit Cloud documentation}
for details on how to set project access and obtain a project link.}
}
\description{
These helpers produce the markdown text you need in your README to include
badges that report information, such as the CRAN version or test coverage,
and link out to relevant external resources. To add badges automatically
ensure your badge block starts with a line containing only
\verb{} and ends with a line containing only
\verb{}.
}
\details{
\itemize{
\item \code{use_badge()}: a general helper used in all badge functions
\item \code{use_bioc_badge()}: badge indicates \href{https://bioconductor.org/developers/}{BioConductor build status}
\item \code{use_cran_badge()}: badge indicates what version of your package is
available on CRAN, powered by \url{https://www.r-pkg.org}
\item \code{use_lifecycle_badge()}: badge declares the developmental stage of a
package according to \url{https://lifecycle.r-lib.org/articles/stages.html}.
\item \code{use_binder_badge()}: badge indicates that your repository can be launched
in an executable environment on \url{https://mybinder.org/}
\item \code{use_posit_cloud_badge()}: badge indicates that your repository can be launched
in a \href{https://posit.cloud}{Posit Cloud} project
\item \code{use_rscloud_badge()}: \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}: Use
\code{\link[=use_posit_cloud_badge]{use_posit_cloud_badge()}} instead.
}
}
\examples{
\dontrun{
use_cran_badge()
use_lifecycle_badge("stable")
}
}
\seealso{
Functions that configure continuous integration, such as
\code{\link[=use_github_actions]{use_github_actions()}}, also create badges.
}
usethis/man/use_latest_dependencies.Rd 0000644 0001762 0000144 00000001375 14420343677 017676 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/latest-dependencies.R
\name{use_latest_dependencies}
\alias{use_latest_dependencies}
\title{Use "latest" versions of all dependencies}
\usage{
use_latest_dependencies(overwrite = TRUE, source = c("CRAN", "local"))
}
\arguments{
\item{overwrite}{By default (\code{TRUE}), all dependencies will be modified.
Set to \code{FALSE} to only modify dependencies without version
specifications.}
\item{source}{Use "CRAN" or "local" package versions.}
}
\description{
Pins minimum versions of all \code{Imports} and \code{Depends} dependencies to latest
ones (as determined by \code{source}). Useful for the tidyverse package, but
should otherwise be used with extreme care.
}
\keyword{internal}
usethis/man/git_sitrep.Rd 0000644 0001762 0000144 00000001321 14420343677 015160 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/git.R
\name{git_sitrep}
\alias{git_sitrep}
\title{Git/GitHub sitrep}
\usage{
git_sitrep(tool = c("git", "github"), scope = c("user", "project"))
}
\arguments{
\item{tool}{Report for \strong{git}, or \strong{github}}
\item{scope}{Report globally for the current \strong{user}, or locally for the
current \strong{project}}
}
\description{
Get a situation report on your current Git/GitHub status. Useful for
diagnosing problems. The default is to report all values; provide values
for \code{tool} or \code{scope} to be more specific.
}
\examples{
\dontrun{
# report all
git_sitrep()
# report git for current user
git_sitrep("git", "user")
}
}
usethis/man/use_release_issue.Rd 0000644 0001762 0000144 00000003102 14420343677 016512 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/release.R
\name{use_release_issue}
\alias{use_release_issue}
\title{Create a release checklist in a GitHub issue}
\usage{
use_release_issue(version = NULL)
}
\arguments{
\item{version}{Optional version number for release. If unspecified, you can
make an interactive choice.}
}
\description{
When preparing to release a package to CRAN there are quite a few steps that
need to be performed, and some of the steps can take multiple hours. This
function creates a checklist in a GitHub issue to:
\itemize{
\item Help you keep track of where you are in the process
\item Feel a sense of satisfaction as you progress towards final submission
\item Help watchers of your package stay informed.
}
The checklist contains a generic set of steps that we've found to be helpful,
based on the type of release ("patch", "minor", or "major"). You're
encouraged to edit the issue to customize this list to meet your needs.
\subsection{Customization}{
\itemize{
\item If you want to consistently add extra bullets for every release, you can
include your own custom bullets by providing an (unexported)
\code{release_bullets()} function that returns a character vector.
(For historical reasons, \code{release_questions()} is also supported).
\item If you want to check additional packages in the revdep check process,
provide an (unexported) \code{release_extra_revdeps()} function that
returns a character vector. This is currently only supported for
Posit internal check tooling.
}
}
}
\examples{
\dontrun{
use_release_issue("2.0.0")
}
}
usethis/man/use_github_file.Rd 0000644 0001762 0000144 00000005224 14420343677 016152 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/use_github_file.R
\name{use_github_file}
\alias{use_github_file}
\title{Copy a file from any GitHub repo into the current project}
\usage{
use_github_file(
repo_spec,
path = NULL,
save_as = NULL,
ref = NULL,
ignore = FALSE,
open = FALSE,
overwrite = FALSE,
host = NULL
)
}
\arguments{
\item{repo_spec}{A string identifying the GitHub repo or, alternatively, a
GitHub file URL. Acceptable forms:
\itemize{
\item Plain \code{OWNER/REPO} spec
\item A blob URL, such as \code{"https://github.com/OWNER/REPO/blob/REF/path/to/some/file"}
\item A raw URL, such as \code{"https://raw.githubusercontent.com/OWNER/REPO/REF/path/to/some/file"}
}
In the case of a URL, the \code{path}, \code{ref}, and \code{host} are extracted from it, in
addition to the \code{repo_spec}.}
\item{path}{Path of file to copy, relative to the GitHub repo it lives in.
This is extracted from \code{repo_spec} when user provides a URL.}
\item{save_as}{Path of file to create, relative to root of active project.
Defaults to the last part of \code{path}, in the sense of \code{basename(path)} or
\code{fs::path_file(path)}.}
\item{ref}{The name of a branch, tag, or commit. By default, the file at
\code{path} will be copied from its current state in the repo's default branch.
This is extracted from \code{repo_spec} when user provides a URL.}
\item{ignore}{Should the newly created file be added to \code{.Rbuildignore}?}
\item{open}{Open the newly created file for editing? Happens in RStudio, if
applicable, or via \code{\link[utils:file.edit]{utils::file.edit()}} otherwise.}
\item{overwrite}{Force overwrite of existing file?}
\item{host}{GitHub host to target, passed to the \code{.api_url} argument of
\code{\link[gh:gh]{gh::gh()}}. If unspecified, gh defaults to "https://api.github.com",
although gh's default can be customised by setting the GITHUB_API_URL
environment variable.
For a hypothetical GitHub Enterprise instance, either
"https://github.acme.com/api/v3" or "https://github.acme.com" is
acceptable.}
}
\value{
A logical indicator of whether a file was written, invisibly.
}
\description{
Gets the content of a file from GitHub, from any repo the user can read, and
writes it into the active project. This function wraps an endpoint of the
GitHub API which supports specifying a target reference (i.e. branch, tag,
or commit) and which follows symlinks.
}
\examples{
\dontrun{
use_github_file(
"https://github.com/r-lib/actions/blob/v2/examples/check-standard.yaml"
)
use_github_file(
"r-lib/actions",
path = "examples/check-standard.yaml",
ref = "v2",
save_as = ".github/workflows/R-CMD-check.yaml"
)
}
}
usethis/man/use_namespace.Rd 0000644 0001762 0000144 00000001402 14442324752 015614 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/namespace.R
\name{use_namespace}
\alias{use_namespace}
\title{Use a basic \code{NAMESPACE}}
\usage{
use_namespace(roxygen = TRUE)
}
\arguments{
\item{roxygen}{Do you plan to manage \code{NAMESPACE} with roxygen2?}
}
\description{
If \code{roxygen} is \code{TRUE} generates an empty \code{NAMESPACE} that exports nothing;
you'll need to explicitly export functions with \verb{@export}. If \code{roxygen}
is \code{FALSE}, generates a default \code{NAMESPACE} that exports all functions
except those that start with \code{.}.
}
\seealso{
The \href{https://r-pkgs.org/dependencies-mindset-background.html#sec-dependencies-namespace}{namespace chapter}
of \href{https://r-pkgs.org}{R Packages}.
}
usethis/man/git_vaccinate.Rd 0000644 0001762 0000144 00000001177 14447377413 015624 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/git.R
\name{git_vaccinate}
\alias{git_vaccinate}
\title{Vaccinate your global gitignore file}
\usage{
git_vaccinate()
}
\description{
Adds \code{.Rproj.user}, \code{.Rhistory}, \code{.Rdata}, \code{.httr-oauth}, \code{.DS_Store}, and \code{.quarto} to
your global (a.k.a. user-level) \code{.gitignore}. This is good practice as it
decreases the chance that you will accidentally leak credentials to GitHub.
\code{git_vaccinate()} also tries to detect and fix the situation where you have a
global gitignore file, but it's missing from your global Git config.
}
usethis/man/roxygen/ 0000755 0001762 0000144 00000000000 14420343677 014216 5 ustar ligges users usethis/man/roxygen/templates/ 0000755 0001762 0000144 00000000000 14420343677 016214 5 ustar ligges users usethis/man/roxygen/templates/double-auth.R 0000644 0001762 0000144 00000002572 14420343677 020556 0 ustar ligges users #' @section Git/GitHub Authentication:
#' Many usethis functions, including those documented here, potentially interact
#' with GitHub in two different ways:
#' * Via the GitHub REST API. Examples: create a repo, a fork, or a pull
#' request.
#' * As a conventional Git remote. Examples: clone, fetch, or push.
#'
#' Therefore two types of auth can happen and your credentials must be
#' discoverable. Which credentials do we mean?
#'
#' * A GitHub personal access token (PAT) must be discoverable by the gh
#' package, which is used for GitHub operations via the REST API. See
#' [gh_token_help()] for more about getting and configuring a PAT.
#' * If you use the HTTPS protocol for Git remotes, your PAT is also used for
#' Git operations, such as `git push`. Usethis uses the gert package for this,
#' so the PAT must be discoverable by gert. Generally gert and gh will
#' discover and use the same PAT. This ability to "kill two birds with one
#' stone" is why HTTPS + PAT is our recommended auth strategy for those new
#' to Git and GitHub and PRs.
#' * If you use SSH remotes, your SSH keys must also be discoverable, in
#' addition to your PAT. The public key must be added to your GitHub account.
#'
#' Git/GitHub credential management is covered in a dedicated article:
#' [Managing Git(Hub) Credentials](https://usethis.r-lib.org/articles/articles/git-credentials.html)
usethis/man/use_description.Rd 0000644 0001762 0000144 00000005267 14442324752 016220 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/description.R
\name{use_description}
\alias{use_description}
\alias{use_description_defaults}
\title{Create or modify a DESCRIPTION file}
\usage{
use_description(fields = list(), check_name = TRUE, roxygen = TRUE)
use_description_defaults(package = NULL, roxygen = TRUE, fields = list())
}
\arguments{
\item{fields}{A named list of fields to add to \code{DESCRIPTION}, potentially
overriding default values. See \code{\link[=use_description]{use_description()}} for how you can set
personalized defaults using package options.}
\item{check_name}{Whether to check if the name is valid for CRAN and throw an
error if not.}
\item{roxygen}{If \code{TRUE}, sets \code{RoxygenNote} to current roxygen2 version}
\item{package}{Package name}
}
\description{
\code{use_description()} creates a \code{DESCRIPTION} file. Although mostly associated
with R packages, a \code{DESCRIPTION} file can also be used to declare
dependencies for a non-package project. Within such a project,
\code{devtools::install_deps()} can then be used to install all the required
packages. Note that, by default, \code{use_decription()} checks for a
CRAN-compliant package name. You can turn this off with \code{check_name = FALSE}.
usethis consults the following sources, in this order, to set \code{DESCRIPTION}
fields:
\itemize{
\item \code{fields} argument of \code{\link[=create_package]{create_package()}} or \code{\link[=use_description]{use_description()}}
\item \code{getOption("usethis.description")}
\item Defaults built into usethis
}
The fields discovered via options or the usethis package can be viewed with
\code{use_description_defaults()}.
If you create a lot of packages, consider storing personalized defaults as a
named list in an option named \code{"usethis.description"}. Here's an example of
code to include in \code{.Rprofile}, which can be opened via \code{\link[=edit_r_profile]{edit_r_profile()}}:
\if{html}{\out{
}}
Prior to usethis v2.0.0, \code{getOption("devtools.desc")} was consulted for
backwards compatibility, but now only the \code{"usethis.description"} option is
supported.
}
\examples{
\dontrun{
use_description()
use_description(fields = list(Language = "es"))
use_description_defaults()
}
}
\seealso{
The \href{https://r-pkgs.org/description.html}{description chapter}
of \href{https://r-pkgs.org}{R Packages}
}
usethis/man/use_tidy_labels.Rd 0000644 0001762 0000144 00000001755 14420343677 016171 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/usethis-defunct.R
\name{use_tidy_labels}
\alias{use_tidy_labels}
\alias{use_tidy_ci}
\alias{use_tidy_eval}
\title{Defunct tidyverse functions}
\usage{
use_tidy_labels()
use_tidy_ci(...)
use_tidy_eval()
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#defunct}{\figure{lifecycle-defunct.svg}{options: alt='[Defunct]'}}}{\strong{[Defunct]}}
\itemize{
\item \code{use_tidy_labels()} has been replaced by \code{\link[=use_tidy_github_labels]{use_tidy_github_labels()}}.
\item \code{use_tidy_ci()} has been replaced by \code{\link[=use_tidy_github_actions]{use_tidy_github_actions()}}.
\item \code{use_tidy_eval()} is defunct because there's no longer a need to
systematically import and re-export a large number of functions in order
to use tidy evaluation. Instead, use \code{\link[=use_import_from]{use_import_from()}} to tactically
import functions as you need them.
}
}
\keyword{internal}
usethis/man/write-this.Rd 0000644 0001762 0000144 00000003731 14420343677 015115 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/write.R
\name{write-this}
\alias{write-this}
\alias{write_union}
\alias{write_over}
\title{Write into or over a file}
\usage{
write_union(path, lines, quiet = FALSE)
write_over(path, lines, quiet = FALSE, overwrite = FALSE)
}
\arguments{
\item{path}{Path to target file. It is created if it does not exist, but the
parent directory must exist.}
\item{lines}{Character vector of lines. For \code{write_union()}, these are lines
to add to the target file, if not already present. For \code{write_over()},
these are the exact lines desired in the target file.}
\item{quiet}{Logical. Whether to message about what is happening.}
\item{overwrite}{Force overwrite of existing file?}
\item{contents}{Character vector of lines.}
}
\value{
Logical indicating whether a write occurred, invisibly.
}
\description{
Helpers to write into or over a new or pre-existing file. Designed mostly for
for internal use. File is written with UTF-8 encoding.
}
\section{Functions}{
\itemize{
\item \code{write_union()}: writes lines to a file, taking the union of what's
already there, if anything, and some new lines. Note, there is no explicit
promise about the line order. Designed to modify simple config files like
\code{.Rbuildignore} and \code{.gitignore}.
\item \code{write_over()}: writes a file with specific lines, creating it if
necessary or overwriting existing, if proposed contents are not identical
and user is available to give permission.
}}
\examples{
\dontshow{
.old_wd <- setwd(tempdir())
}
write_union("a_file", letters[1:3])
readLines("a_file")
write_union("a_file", letters[1:5])
readLines("a_file")
write_over("another_file", letters[1:3])
readLines("another_file")
write_over("another_file", letters[1:3])
\dontrun{
## will error if user isn't present to approve the overwrite
write_over("another_file", letters[3:1])
}
## clean up
file.remove("a_file", "another_file")
\dontshow{
setwd(.old_wd)
}
}
\keyword{internal}
usethis/man/use_logo.Rd 0000644 0001762 0000144 00000001541 13676400413 014621 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/logo.R
\name{use_logo}
\alias{use_logo}
\title{Use a package logo}
\usage{
use_logo(img, geometry = "240x278", retina = TRUE)
}
\arguments{
\item{img}{The path to an existing image file}
\item{geometry}{a \link[magick:geometry]{magick::geometry} string specifying size. The default
assumes that you have a hex logo using spec from
\url{http://hexb.in/sticker.html}.}
\item{retina}{\code{TRUE}, the default, scales the image on the README,
assuming that geometry is double the desired size.}
}
\description{
This function helps you use a logo in your package:
\itemize{
\item Enforces a specific size
\item Stores logo image file at \code{man/figures/logo.png}
\item Produces the markdown text you need in README to include the logo
}
}
\examples{
\dontrun{
use_logo("usethis.png")
}
}
usethis/man/use_gitlab_ci.Rd 0000644 0001762 0000144 00000004411 14420343677 015603 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ci.R
\name{use_gitlab_ci}
\alias{use_gitlab_ci}
\alias{use_circleci}
\alias{use_circleci_badge}
\title{Continuous integration setup and badges}
\usage{
use_gitlab_ci()
use_circleci(browse = rlang::is_interactive(), image = "rocker/verse:latest")
use_circleci_badge(repo_spec = NULL)
}
\arguments{
\item{browse}{Open a browser window to enable automatic builds for the
package.}
\item{image}{The Docker image to use for build. Must be available on
\href{https://hub.docker.com}{DockerHub}. The
\href{https://hub.docker.com/r/rocker/verse}{rocker/verse} image includes
TeXLive, pandoc, and the tidyverse packages. For a minimal image, try
\href{https://hub.docker.com/r/rocker/r-ver}{rocker/r-ver}. To specify a version
of R, change the tag from \code{latest} to the version you want, e.g.
\verb{rocker/r-ver:3.5.3}.}
\item{repo_spec}{Optional GitHub repo specification in this form: \code{owner/repo}. This can usually be inferred from the GitHub remotes of active project.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#questioning}{\figure{lifecycle-questioning.svg}{options: alt='[Questioning]'}}}{\strong{[Questioning]}}
These functions are not actively used by the tidyverse team, and may not
currently work. Use at your own risk.
Sets up third-party continuous integration (CI) services for an R package
on GitLab or CircleCI. These functions:
\itemize{
\item Add service-specific configuration files and add them to \code{.Rbuildignore}.
\item Activate a service or give the user a detailed prompt.
\item Provide the markdown to insert a badge into README.
}
}
\section{\code{use_gitlab_ci()}}{
Adds a basic \code{.gitlab-ci.yml} to the top-level directory of a package. This
is a configuration file for the \href{https://docs.gitlab.com/ee/ci/}{GitLab CI/CD} continuous integration service.
}
\section{\code{use_circleci()}}{
Adds a basic \code{.circleci/config.yml} to the top-level directory of a package.
This is a configuration file for the \href{https://circleci.com/}{CircleCI}
continuous integration service.
}
\section{\code{use_circleci_badge()}}{
Only adds the \href{https://circleci.com/}{Circle CI} badge. Use for a project
where Circle CI is already configured.
}
usethis/man/use_code_of_conduct.Rd 0000644 0001762 0000144 00000002647 14420343677 017014 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/code-of-conduct.R
\name{use_code_of_conduct}
\alias{use_code_of_conduct}
\title{Add a code of conduct}
\usage{
use_code_of_conduct(contact, path = NULL)
}
\arguments{
\item{contact}{Contact details for making a code of conduct report.
Usually an email address.}
\item{path}{Path of the directory to put \code{CODE_OF_CONDUCT.md} in, relative to
the active project. Passed along to \code{\link[=use_directory]{use_directory()}}. Default is to locate
at top-level, but \verb{.github/} is also common.}
}
\description{
Adds a \code{CODE_OF_CONDUCT.md} file to the active project and lists in
\code{.Rbuildignore}, in the case of a package. The goal of a code of conduct is
to foster an environment of inclusiveness, and to explicitly discourage
inappropriate behaviour. The template comes from
\url{https://www.contributor-covenant.org}, version 2.1:
\url{https://www.contributor-covenant.org/version/2/1/code_of_conduct/}.
}
\details{
If your package is going to CRAN, the link to the CoC in your README must
be an absolute link to a rendered website as \code{CODE_OF_CONDUCT.md} is not
included in the package sent to CRAN. \code{use_code_of_conduct()} will
automatically generate this link if (1) you use pkgdown and (2) have set the
\code{url} field in \verb{_pkgdown.yml}; otherwise it will link to a copy of the CoC
on \url{https://www.contributor-covenant.org}.
}
usethis/man/proj_activate.Rd 0000644 0001762 0000144 00000001035 13676400413 015635 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/proj.R
\name{proj_activate}
\alias{proj_activate}
\title{Activate a project}
\usage{
proj_activate(path)
}
\arguments{
\item{path}{Project directory}
}
\value{
Single logical value indicating if current session is modified.
}
\description{
Activates a project in usethis, R session, and (if relevant) RStudio senses.
If you are in RStudio, this will open a new RStudio session. If not, it will
change the working directory and \link[=proj_set]{active project}.
}
usethis/man/use_package_doc.Rd 0000644 0001762 0000144 00000002155 14420343677 016111 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/documentation.R
\name{use_package_doc}
\alias{use_package_doc}
\title{Package-level documentation}
\usage{
use_package_doc(open = rlang::is_interactive())
}
\arguments{
\item{open}{Open the newly created file for editing? Happens in RStudio, if
applicable, or via \code{\link[utils:file.edit]{utils::file.edit()}} otherwise.}
}
\description{
Adds a dummy \code{.R} file that will prompt roxygen to generate basic
package-level documentation. If your package is named "foo", this will make
help available to the user via \code{?foo} or \code{package?foo}. Once you call
\code{devtools::document()}, roxygen will flesh out the \code{.Rd} file using data from
the \code{DESCRIPTION}. That ensures you don't need to repeat the same information
in multiple places. This \code{.R} file is also a good place for roxygen
directives that apply to the whole package (vs. a specific function), such as
global namespace tags like \verb{@importFrom}.
}
\seealso{
The \href{https://r-pkgs.org/man.html}{documentation chapter} of \href{https://r-pkgs.org}{R Packages}
}
usethis/man/use_data.Rd 0000644 0001762 0000144 00000005015 14420343677 014600 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data.R
\name{use_data}
\alias{use_data}
\alias{use_data_raw}
\title{Create package data}
\usage{
use_data(
...,
internal = FALSE,
overwrite = FALSE,
compress = "bzip2",
version = 2,
ascii = FALSE
)
use_data_raw(name = "DATASET", open = rlang::is_interactive())
}
\arguments{
\item{...}{Unquoted names of existing objects to save.}
\item{internal}{If \code{FALSE}, saves each object in its own \code{.rda}
file in the \verb{data/} directory. These data files bypass the usual
export mechanism and are available whenever the package is loaded
(or via \code{\link[=data]{data()}} if \code{LazyData} is not true).
If \code{TRUE}, stores all objects in a single \code{R/sysdata.rda} file.
Objects in this file follow the usual export rules. Note that this means
they will be exported if you are using the common \code{exportPattern()}
rule which exports all objects except for those that start with \code{.}.}
\item{overwrite}{By default, \code{use_data()} will not overwrite existing
files. If you really want to do so, set this to \code{TRUE}.}
\item{compress}{Choose the type of compression used by \code{\link[=save]{save()}}.
Should be one of "gzip", "bzip2", or "xz".}
\item{version}{The serialization format version to use. The default, 2, was
the default format from R 1.4.0 to 3.5.3. Version 3 became the default from
R 3.6.0 and can only be read by R versions 3.5.0 and higher.}
\item{ascii}{if \code{TRUE}, an ASCII representation of the data is
written. The default value of \code{ascii} is \code{FALSE} which
leads to a binary file being written. If \code{NA} and
\code{version >= 2}, a different ASCII representation is used which
writes double/complex numbers as binary fractions.}
\item{name}{Name of the dataset to be prepared for inclusion in the package.}
\item{open}{Open the newly created file for editing? Happens in RStudio, if
applicable, or via \code{\link[utils:file.edit]{utils::file.edit()}} otherwise.}
}
\description{
\code{use_data()} makes it easy to save package data in the correct format. I
recommend you save scripts that generate package data in \code{data-raw}: use
\code{use_data_raw()} to set it up. You also need to document exported datasets.
}
\examples{
\dontrun{
x <- 1:10
y <- 1:100
use_data(x, y) # For external use
use_data(x, y, internal = TRUE) # For internal use
}
\dontrun{
use_data_raw("daisy")
}
}
\seealso{
The \href{https://r-pkgs.org/data.html}{data chapter} of \href{https://r-pkgs.org}{R Packages}.
}
usethis/man/ui-questions.Rd 0000644 0001762 0000144 00000004370 14420343677 015463 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ui.R
\name{ui-questions}
\alias{ui-questions}
\alias{ui_yeah}
\alias{ui_nope}
\title{User interface - Questions}
\usage{
ui_yeah(
x,
yes = c("Yes", "Definitely", "For sure", "Yup", "Yeah", "I agree", "Absolutely"),
no = c("No way", "Not now", "Negative", "No", "Nope", "Absolutely not"),
n_yes = 1,
n_no = 2,
shuffle = TRUE,
.envir = parent.frame()
)
ui_nope(
x,
yes = c("Yes", "Definitely", "For sure", "Yup", "Yeah", "I agree", "Absolutely"),
no = c("No way", "Not now", "Negative", "No", "Nope", "Absolutely not"),
n_yes = 1,
n_no = 2,
shuffle = TRUE,
.envir = parent.frame()
)
}
\arguments{
\item{x}{A character vector.
For block styles, conditions, and questions, each element of the
vector becomes a line, and the result is processed by \code{\link[glue:glue]{glue::glue()}}.
For inline styles, each element of the vector becomes an entry in a
comma separated list.}
\item{yes}{A character vector of "yes" strings, which are randomly sampled to
populate the menu.}
\item{no}{A character vector of "no" strings, which are randomly sampled to
populate the menu.}
\item{n_yes}{An integer. The number of "yes" strings to include.}
\item{n_no}{An integer. The number of "no" strings to include.}
\item{shuffle}{A logical. Should the order of the menu options be randomly
shuffled?}
\item{.envir}{Used to ensure that \code{\link[glue:glue]{glue::glue()}} gets the correct
environment. For expert use only.}
}
\value{
A logical. \code{ui_yeah()} returns \code{TRUE} when the user selects a "yes"
option and \code{FALSE} otherwise, i.e. when user selects a "no" option or
refuses to make a selection (cancels). \code{ui_nope()} is the logical opposite
of \code{ui_yeah()}.
}
\description{
These functions are used to interact with the user by posing a simple yes or
no question. For details on the other \verb{ui_*()} functions, see the \link{ui} help
page.
}
\examples{
\dontrun{
ui_yeah("Do you like R?")
ui_nope("Have you tried turning it off and on again?", n_yes = 1, n_no = 1)
ui_yeah("Are you sure its plugged in?", yes = "Yes", no = "No", shuffle = FALSE)
}
}
\seealso{
Other user interface functions:
\code{\link{ui}}
}
\concept{user interface functions}
\keyword{internal}
usethis/man/use_travis.Rd 0000644 0001762 0000144 00000002004 14420343677 015172 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/usethis-defunct.R
\name{use_travis}
\alias{use_travis}
\alias{use_travis_badge}
\alias{use_pkgdown_travis}
\alias{use_appveyor}
\alias{use_appveyor_badge}
\alias{browse_travis}
\title{Defunct Travis and Appveyor functions}
\usage{
use_travis(browse = rlang::is_interactive(), ext = c("com", "org"))
use_travis_badge(ext = c("com", "org"), repo_spec = NULL)
use_pkgdown_travis()
use_appveyor(browse = rlang::is_interactive())
use_appveyor_badge(repo_spec = NULL)
browse_travis(package = NULL, ext = c("com", "org"))
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#defunct}{\figure{lifecycle-defunct.svg}{options: alt='[Defunct]'}}}{\strong{[Defunct]}}
These functions which formally supported CI on Appveyor and Travis are
now defunct as we no longer recommend using these services. We now
recommend using GitHub actions, e.g. with \code{\link[=use_github_action]{use_github_action()}}.
}
\keyword{internal}
usethis/man/use_github_pages.Rd 0000644 0001762 0000144 00000004770 14420343677 016337 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/github-pages.R
\name{use_github_pages}
\alias{use_github_pages}
\title{Configure a GitHub Pages site}
\usage{
use_github_pages(branch = "gh-pages", path = "/", cname = NA)
}
\arguments{
\item{branch, path}{Branch and path for the site source. The default of
\code{branch = "gh-pages"} and \code{path = "/"} reflects strong GitHub support for
this configuration: when a \code{gh-pages} branch is first created, it is
\emph{automatically} published to Pages, using the source found in \code{"/"}. If a
\code{gh-pages} branch does not yet exist on the host, \code{use_github_pages()}
creates an empty, orphan remote branch.
The most common alternative is to use the repo's default branch, coupled
with \code{path = "/docs"}. It is the user's responsibility to ensure that this
\code{branch} pre-exists on the host.
Note that GitHub does not support an arbitrary \code{path} and, at the time of
writing, only \code{"/"} or \code{"/docs"} are accepted.}
\item{cname}{Optional, custom domain name. The \code{NA} default means "don't set
or change this", whereas a value of \code{NULL} removes any previously
configured custom domain.
Note that this \emph{can} add or modify a CNAME file in your repository. If you
are using Pages to host a pkgdown site, it is better to specify its URL in
the pkgdown config file and let pkgdown manage CNAME.}
}
\value{
Site metadata returned by the GitHub API, invisibly
}
\description{
Activates or reconfigures a GitHub Pages site for a project hosted on GitHub.
This function anticipates two specific usage modes:
\itemize{
\item Publish from the root directory of a \code{gh-pages} branch, which is assumed to
be only (or at least primarily) a remote branch. Typically the \code{gh-pages}
branch is managed by an automatic "build and deploy" job, such as the one
configured by \code{\link[=use_github_action]{use_github_action("pkgdown")}}.
\item Publish from the \code{"/docs"} directory of a "regular" branch, probably the
repo's default branch. The user is assumed to have a plan for how they will
manage the content below \code{"/docs"}.
}
}
\examples{
\dontrun{
use_github_pages()
use_github_pages(branch = git_default_branch(), path = "/docs")
}
}
\seealso{
\itemize{
\item \code{\link[=use_pkgdown_github_pages]{use_pkgdown_github_pages()}} combines \code{use_github_pages()} with other
functions to fully configure a pkgdown site
\item \url{https://docs.github.com/en/pages}
\item \url{https://docs.github.com/en/rest/pages}
}
}
usethis/man/git_protocol.Rd 0000644 0001762 0000144 00000003125 14420343677 015517 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/git.R
\name{git_protocol}
\alias{git_protocol}
\alias{use_git_protocol}
\title{See or set the default Git protocol}
\usage{
git_protocol()
use_git_protocol(protocol)
}
\arguments{
\item{protocol}{One of "https" or "ssh"}
}
\value{
The protocol, either "https" or "ssh"
}
\description{
Git operations that address a remote use a so-called "transport protocol".
usethis supports HTTPS and SSH. The protocol dictates the Git URL format used
when usethis needs to configure the first GitHub remote for a repo:
\itemize{
\item \code{protocol = "https"} implies \verb{https://github.com//.git}
\item \code{protocol = "ssh"} implies \verb{git@github.com:/.git}
}
Two helper functions are available:
\itemize{
\item \code{git_protocol()} reveals the protocol "in force". As of usethis v2.0.0,
this defaults to "https". You can change this for the duration of the
R session with \code{use_git_protocol()}. Change the default for all R
sessions with code like this in your \code{.Rprofile} (easily editable via
\code{\link[=edit_r_profile]{edit_r_profile()}}):
\if{html}{\out{
}}
\item \code{use_git_protocol()} sets the Git protocol for the current R session
}
This protocol only affects the Git URL for newly configured remotes. All
existing Git remote URLs are always respected, whether HTTPS or SSH.
}
\examples{
\dontrun{
git_protocol()
use_git_protocol("ssh")
git_protocol()
use_git_protocol("https")
git_protocol()
}
}
usethis/man/use_git_remote.Rd 0000644 0001762 0000144 00000004104 14420343677 016023 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/git.R
\name{use_git_remote}
\alias{use_git_remote}
\alias{git_remotes}
\title{Configure and report Git remotes}
\usage{
use_git_remote(name = "origin", url, overwrite = FALSE)
git_remotes()
}
\arguments{
\item{name}{A string giving the short name of a remote.}
\item{url}{A string giving the url of a remote.}
\item{overwrite}{Logical. Controls whether an existing remote can be
modified.}
}
\value{
Named list of Git remotes.
}
\description{
Two helpers are available:
\itemize{
\item \code{use_git_remote()} sets the remote associated with \code{name} to \code{url}.
\item \code{git_remotes()} reports the configured remotes, similar to
\verb{git remote -v}.
}
}
\examples{
\dontrun{
# see current remotes
git_remotes()
# add new remote named 'foo', a la `git remote add `
use_git_remote(name = "foo", url = "https://github.com//.git")
# remove existing 'foo' remote, a la `git remote remove `
use_git_remote(name = "foo", url = NULL, overwrite = TRUE)
# change URL of remote 'foo', a la `git remote set-url `
use_git_remote(
name = "foo",
url = "https://github.com//.git",
overwrite = TRUE
)
# Scenario: Fix remotes when you cloned someone's repo, but you should
# have fork-and-cloned (in order to make a pull request).
# Store origin = main repo's URL, e.g., "git@github.com:/.git"
upstream_url <- git_remotes()[["origin"]]
# IN THE BROWSER: fork the main GitHub repo and get your fork's remote URL
my_url <- "git@github.com:/.git"
# Rotate the remotes
use_git_remote(name = "origin", url = my_url)
use_git_remote(name = "upstream", url = upstream_url)
git_remotes()
# Scenario: Add upstream remote to a repo that you fork-and-cloned, so you
# can pull upstream changes.
# Note: If you fork-and-clone via `usethis::create_from_github()`, this is
# done automatically!
# Get URL of main GitHub repo, probably in the browser
upstream_url <- "git@github.com:/.git"
use_git_remote(name = "upstream", url = upstream_url)
}
}
usethis/man/use_git.Rd 0000644 0001762 0000144 00000001132 14420343677 014446 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/git.R
\name{use_git}
\alias{use_git}
\title{Initialise a git repository}
\usage{
use_git(message = "Initial commit")
}
\arguments{
\item{message}{Message to use for first commit.}
}
\description{
\code{use_git()} initialises a Git repository and adds important files to
\code{.gitignore}. If user consents, it also makes an initial commit.
}
\examples{
\dontrun{
use_git()
}
}
\seealso{
Other git helpers:
\code{\link{use_git_config}()},
\code{\link{use_git_hook}()},
\code{\link{use_git_ignore}()}
}
\concept{git helpers}
usethis/man/use_tutorial.Rd 0000644 0001762 0000144 00000002514 14420343677 015533 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tutorial.R
\name{use_tutorial}
\alias{use_tutorial}
\title{Create a learnr tutorial}
\usage{
use_tutorial(name, title, open = rlang::is_interactive())
}
\arguments{
\item{name}{Base for file name to use for new \code{.Rmd} tutorial. Should consist
only of numbers, letters, \verb{_} and \code{-}. We recommend using lower case.}
\item{title}{The human-facing title of the tutorial.}
\item{open}{Open the newly created file for editing? Happens in RStudio, if
applicable, or via \code{\link[utils:file.edit]{utils::file.edit()}} otherwise.}
}
\description{
Creates a new tutorial below \verb{inst/tutorials/}. Tutorials are interactive R
Markdown documents built with the \href{https://rstudio.github.io/learnr/index.html}{\code{learnr} package}. \code{use_tutorial()} does
this setup:
\itemize{
\item Adds learnr to Suggests in \code{DESCRIPTION}.
\item Gitignores \verb{inst/tutorials/*.html} so you don't accidentally track
rendered tutorials.
\item Creates a new \code{.Rmd} tutorial from a template and, optionally, opens it
for editing.
\item Adds new \code{.Rmd} to \code{.Rbuildignore}.
}
}
\examples{
\dontrun{
use_tutorial("learn-to-do-stuff", "Learn to do stuff")
}
}
\seealso{
The \href{https://rstudio.github.io/learnr/index.html}{learnr package documentation}.
}
usethis/man/use_rstudio_preferences.Rd 0000644 0001762 0000144 00000001247 14420343677 017744 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rstudio.R
\name{use_rstudio_preferences}
\alias{use_rstudio_preferences}
\title{Set global RStudio preferences}
\usage{
use_rstudio_preferences(...)
}
\arguments{
\item{...}{<\code{\link[rlang:dyn-dots]{dynamic-dots}}> Property-value pairs.}
}
\value{
A named list of the previous values, invisibly.
}
\description{
This function allows you to set global RStudio preferences, achieving the
same effect programmatically as clicking buttons in RStudio's Global Options.
You can find a list of configurable properties at
\url{https://docs.posit.co/ide/server-pro/reference/session_user_settings.html}.
}
usethis/man/figures/ 0000755 0001762 0000144 00000000000 14420343677 014167 5 ustar ligges users usethis/man/figures/lifecycle-defunct.svg 0000644 0001762 0000144 00000002424 14445364647 020306 0 ustar ligges users
usethis/man/figures/lifecycle-maturing.svg 0000644 0001762 0000144 00000002430 14445364647 020501 0 ustar ligges users
usethis/man/figures/logo.png 0000644 0001762 0000144 00000070545 14420343677 015650 0 ustar ligges users PNG
IHDR ޫh gAMA a cHRM z&