From 6fa4cbc28a381a8ce0c98460254bf1e7b1da96d1 Mon Sep 17 00:00:00 2001 From: jennybc Date: Tue, 22 Oct 2024 20:19:57 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20@=20r-lib/us?= =?UTF-8?q?ethis@a9afa2cb7578de6d6efaa5835cb83d570115de6f=20=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- dev/news/index.html | 4 +++- dev/pkgdown.yml | 2 +- dev/reference/tidyverse.html | 14 +++++++++----- dev/reference/use_upkeep_issue.html | 2 +- dev/search.json | 2 +- 5 files changed, 15 insertions(+), 9 deletions(-) diff --git a/dev/news/index.html b/dev/news/index.html index 450470b76..f96b450e9 100644 --- a/dev/news/index.html +++ b/dev/news/index.html @@ -55,7 +55,9 @@

usethis (development version)

-
+
  • +use_tidy_upkeep_issue() now records the year it is being run in the Config/usethis/upkeep field in DESCRIPTION. If this value exists it is furthermore used to filter the checklist when making the issue.
    • +

Bug fixes and minor improvements

  • use_package() now decreases a package minimum version required when min_version is lower than what is currently specified in the DESCRIPTION file (@jplecavalier, #1957).

  • use_data() now uses serialization version 3 by default. (@laurabrianna, #2044)

    • diff --git a/dev/pkgdown.yml b/dev/pkgdown.yml index f62281631..337f5e8fe 100644 --- a/dev/pkgdown.yml +++ b/dev/pkgdown.yml @@ -7,7 +7,7 @@ articles: articles/pr-functions: pr-functions.html articles/ui-cli-conversion: ui-cli-conversion.html articles/usethis-setup: usethis-setup.html -last_built: 2024-10-21T15:59Z +last_built: 2024-10-22T20:19Z urls: reference: https://usethis.r-lib.org/reference article: https://usethis.r-lib.org/articles diff --git a/dev/reference/tidyverse.html b/dev/reference/tidyverse.html index 21c004eef..cd44b8675 100644 --- a/dev/reference/tidyverse.html +++ b/dev/reference/tidyverse.html @@ -88,7 +88,7 @@

    Usage use_tidy_logo(geometry = "240x278", retina = TRUE) -use_tidy_upkeep_issue(year = NULL)

+use_tidy_upkeep_issue(last_upkeep = last_upkeep_year())
@@ -130,9 +130,11 @@

Argumentsyear -

Approximate year when you last touched this package. If NULL, -the default, will give you a full set of actions to perform.

+
last_upkeep
+

Year of last upkeep. By default, the +Config/usethis/last-upkeep field in DESCRIPTION is consulted for this, if +it's defined. If there's no information on the last upkeep, the issue will +contain the full checklist.

@@ -177,7 +179,9 @@

Details

use_tidy_github_labels() calls use_github_labels() to implement tidyverse conventions around GitHub issue label names and colours.

  • use_tidy_upkeep_issue() creates an issue containing a checklist of -actions to bring your package up to current tidyverse standards.

    • +actions to bring your package up to current tidyverse standards. Also +records the current date in the Config/usethis/last-upkeep field in +DESCRIPTION.

  • use_tidy_logo() calls use_logo() on the appropriate hex sticker PNG file at https://github.com/rstudio/hex-stickers.

    • diff --git a/dev/reference/use_upkeep_issue.html b/dev/reference/use_upkeep_issue.html index 394da23ef..9331281f4 100644 --- a/dev/reference/use_upkeep_issue.html +++ b/dev/reference/use_upkeep_issue.html @@ -97,7 +97,7 @@

    Arguments

    Examples

    if (FALSE) { # \dontrun{
-use_upkeep_issue(2023)
+use_upkeep_issue()
 } # }
    diff --git a/dev/search.json b/dev/search.json index 0d7e73364..bb27d13a9 100644 --- a/dev/search.json +++ b/dev/search.json @@ -1 +1 @@ -[{"path":[]},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"our-pledge","dir":"","previous_headings":"","what":"Our Pledge","title":"Contributor Covenant Code of Conduct","text":"members, contributors, leaders pledge make participation community harassment-free experience everyone, regardless age, body size, visible invisible disability, ethnicity, sex characteristics, gender identity expression, level experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, sexual identity orientation. pledge act interact ways contribute open, welcoming, diverse, inclusive, healthy community.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"our-standards","dir":"","previous_headings":"","what":"Our Standards","title":"Contributor Covenant Code of Conduct","text":"Examples behavior contributes positive environment community include: Demonstrating empathy kindness toward people respectful differing opinions, viewpoints, experiences Giving gracefully accepting constructive feedback Accepting responsibility apologizing affected mistakes, learning experience Focusing best just us individuals, overall community Examples unacceptable behavior include: use sexualized language imagery, sexual attention advances kind Trolling, insulting derogatory comments, personal political attacks Public private harassment Publishing others’ private information, physical email address, without explicit permission conduct reasonably considered inappropriate professional setting","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"enforcement-responsibilities","dir":"","previous_headings":"","what":"Enforcement Responsibilities","title":"Contributor Covenant Code of Conduct","text":"Community leaders responsible clarifying enforcing standards acceptable behavior take appropriate fair corrective action response behavior deem inappropriate, threatening, offensive, harmful. Community leaders right responsibility remove, edit, reject comments, commits, code, wiki edits, issues, contributions aligned Code Conduct, communicate reasons moderation decisions appropriate.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"scope","dir":"","previous_headings":"","what":"Scope","title":"Contributor Covenant Code of Conduct","text":"Code Conduct applies within community spaces, also applies individual officially representing community public spaces. Examples representing community include using official e-mail address, posting via official social media account, acting appointed representative online offline event.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"enforcement","dir":"","previous_headings":"","what":"Enforcement","title":"Contributor Covenant Code of Conduct","text":"Instances abusive, harassing, otherwise unacceptable behavior may reported community leaders responsible enforcement codeofconduct@posit.co. complaints reviewed investigated promptly fairly. community leaders obligated respect privacy security reporter incident.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"enforcement-guidelines","dir":"","previous_headings":"","what":"Enforcement Guidelines","title":"Contributor Covenant Code of Conduct","text":"Community leaders follow Community Impact Guidelines determining consequences action deem violation Code Conduct:","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_1-correction","dir":"","previous_headings":"Enforcement Guidelines","what":"1. Correction","title":"Contributor Covenant Code of Conduct","text":"Community Impact: Use inappropriate language behavior deemed unprofessional unwelcome community. Consequence: private, written warning community leaders, providing clarity around nature violation explanation behavior inappropriate. public apology may requested.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_2-warning","dir":"","previous_headings":"Enforcement Guidelines","what":"2. Warning","title":"Contributor Covenant Code of Conduct","text":"Community Impact: violation single incident series actions. Consequence: warning consequences continued behavior. interaction people involved, including unsolicited interaction enforcing Code Conduct, specified period time. includes avoiding interactions community spaces well external channels like social media. Violating terms may lead temporary permanent ban.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_3-temporary-ban","dir":"","previous_headings":"Enforcement Guidelines","what":"3. Temporary Ban","title":"Contributor Covenant Code of Conduct","text":"Community Impact: serious violation community standards, including sustained inappropriate behavior. Consequence: temporary ban sort interaction public communication community specified period time. public private interaction people involved, including unsolicited interaction enforcing Code Conduct, allowed period. Violating terms may lead permanent ban.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_4-permanent-ban","dir":"","previous_headings":"Enforcement Guidelines","what":"4. Permanent Ban","title":"Contributor Covenant Code of Conduct","text":"Community Impact: Demonstrating pattern violation community standards, including sustained inappropriate behavior, harassment individual, aggression toward disparagement classes individuals. Consequence: permanent ban sort public interaction within community.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"attribution","dir":"","previous_headings":"","what":"Attribution","title":"Contributor Covenant Code of Conduct","text":"Code Conduct adapted Contributor Covenant, version 2.1, available https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. Community Impact Guidelines inspired [Mozilla’s code conduct enforcement ladder][https://github.com/mozilla/inclusion]. answers common questions code conduct, see FAQ https://www.contributor-covenant.org/faq. Translations available https://www.contributor-covenant.org/translations.","code":""},{"path":"https://usethis.r-lib.org/dev/CONTRIBUTING.html","id":null,"dir":"","previous_headings":"","what":"Contributing to usethis","title":"Contributing to usethis","text":"outlines propose change usethis. detailed info contributing , tidyverse packages, please see development contributing guide.","code":""},{"path":"https://usethis.r-lib.org/dev/CONTRIBUTING.html","id":"fixing-typos","dir":"","previous_headings":"","what":"Fixing typos","title":"Contributing to usethis","text":"can fix typos, spelling mistakes, grammatical errors documentation directly using GitHub web interface, long changes made source file. generally means ’ll need edit roxygen2 comments .R, .Rd file. can find .R file generates .Rd reading comment first line.","code":""},{"path":"https://usethis.r-lib.org/dev/CONTRIBUTING.html","id":"bigger-changes","dir":"","previous_headings":"","what":"Bigger changes","title":"Contributing to usethis","text":"want make bigger change, ’s good idea first file issue make sure someone team agrees ’s needed. ’ve found bug, please file issue illustrates bug minimal reprex (also help write unit test, needed).","code":""},{"path":"https://usethis.r-lib.org/dev/CONTRIBUTING.html","id":"pull-request-process","dir":"","previous_headings":"Bigger changes","what":"Pull request process","title":"Contributing to usethis","text":"Fork package clone onto computer. haven’t done , recommend using usethis::create_from_github(\"r-lib/usethis\", fork = TRUE). Install development dependencies devtools::install_dev_deps(), make sure package passes R CMD check running devtools::check(). R CMD check doesn’t pass cleanly, ’s good idea ask help continuing. Create Git branch pull request (PR). recommend using usethis::pr_init(\"brief-description--change\"). Make changes, commit git, create PR running usethis::pr_push(), following prompts browser. title PR briefly describe change. body PR contain Fixes #issue-number. user-facing changes, add bullet top NEWS.md (.e. just first header). Follow style described https://style.tidyverse.org/news.html.","code":""},{"path":"https://usethis.r-lib.org/dev/CONTRIBUTING.html","id":"code-style","dir":"","previous_headings":"Bigger changes","what":"Code style","title":"Contributing to usethis","text":"New code follow tidyverse style guide. can use styler package apply styles, please don’t restyle code nothing PR. use roxygen2, Markdown syntax, documentation. use testthat unit tests. Contributions test cases included easier accept.","code":""},{"path":"https://usethis.r-lib.org/dev/CONTRIBUTING.html","id":"code-of-conduct","dir":"","previous_headings":"","what":"Code of Conduct","title":"Contributing to usethis","text":"Please note usethis project released Contributor Code Conduct. contributing project agree abide terms.","code":""},{"path":"https://usethis.r-lib.org/dev/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"MIT License","title":"MIT License","text":"Copyright (c) 2020 usethis authors Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://usethis.r-lib.org/dev/SUPPORT.html","id":null,"dir":"","previous_headings":"","what":"Getting help with usethis","title":"Getting help with usethis","text":"Thanks using usethis! filing issue, places explore pieces put together make process smooth possible.","code":""},{"path":"https://usethis.r-lib.org/dev/SUPPORT.html","id":"make-a-reprex","dir":"","previous_headings":"","what":"Make a reprex","title":"Getting help with usethis","text":"Start making minimal reproducible example using reprex package. haven’t heard used reprex , ’re treat! Seriously, reprex make R-question-asking endeavors easier (pretty incredible ROI five ten minutes ’ll take learn ’s ). additional reprex pointers, check Get help! section tidyverse site.","code":""},{"path":"https://usethis.r-lib.org/dev/SUPPORT.html","id":"where-to-ask","dir":"","previous_headings":"","what":"Where to ask?","title":"Getting help with usethis","text":"Armed reprex, next step figure ask. ’s question: start community.rstudio.com, /StackOverflow. people answer questions. ’s bug: ’re right place, file issue. ’re sure: let community help figure ! problem bug feature request, can easily return report . opening new issue, sure search issues pull requests make sure bug hasn’t reported /already fixed development version. default, search pre-populated :issue :open. can edit qualifiers (e.g. :pr, :closed) needed. example, ’d simply remove :open search issues repo, open closed.","code":""},{"path":"https://usethis.r-lib.org/dev/SUPPORT.html","id":"what-happens-next","dir":"","previous_headings":"","what":"What happens next?","title":"Getting help with usethis","text":"efficient possible, development tidyverse packages tends bursty, shouldn’t worry don’t get immediate response. Typically don’t look repo sufficient quantity issues accumulates, ’s burst intense activity focus efforts. makes development efficient avoids expensive context switching problems, cost taking longer get back . process makes good reprex particularly important might multiple months initial report start working . can’t reproduce bug, can’t fix !","code":""},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"markdown-image-link","dir":"Articles","previous_headings":"","what":"Markdown image link","title":"Exploring badge accessibility","text":"usethis currently inserts badges special “badge block” README, fenced HTML comment tags. Within badge block, badge hyperlinked image, alt text. basic form: Note alt_text static label explaining badge’s purpose, whereas dynamic information baked externally-served image. usethis definitely controls alt_text, something ’d like feedback .","code":"[![alt_text](http://path/to/the/badge/image)](http://path/to/more/details)"},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"badge-image","dir":"Articles","previous_headings":"","what":"Badge image","title":"Exploring badge accessibility","text":"badges days tend SVG files, fortunate, since SVGs can carry attributes support accessibility. demonstrate custom badge generated via shields.io web service. request badge URL: badge, hyperlink set https://shields.io/. badge inside HTML comment block, like usethis README badges. ’ve prefixed every field can influence “”; 3 fields: alt text. label. static text appears left side badge, grey background, describes badge. message. text appears right side badge, colored background. often dynamic part, color text convey dynamic fact, e.g. “passing” green background “failing” red background. Now inspect badge SVG. apologize advance amount data displayed , seems good show one badge full gory detail. Later, display badge information selectively. understanding two main pieces metadata title aria-label attribute. reveal just two items badge: badge carries information title aria-label, “my_label: my_message”. interested learn information included twice good bad thing screen reader experience.","code":"https://img.shields.io/badge/my__label-my__message-orange library(xml2) library(purrr) inspect_badge <- function(badge) { badge %>% read_xml() %>% as_list() %>% pluck(\"svg\") } inspect_badge(\"https://img.shields.io/badge/my__label-my__message-orange\") #> $title #> $title[[1]] #> [1] \"my_label: my_message\" #> #> #> $linearGradient #> $linearGradient$stop #> list() #> attr(,\"offset\") #> [1] \"0\" #> attr(,\"stop-color\") #> [1] \"#bbb\" #> attr(,\"stop-opacity\") #> [1] \".1\" #> #> $linearGradient$stop #> list() #> attr(,\"offset\") #> [1] \"1\" #> attr(,\"stop-opacity\") #> [1] \".1\" #> #> attr(,\"id\") #> [1] \"s\" #> attr(,\"x2\") #> [1] \"0\" #> attr(,\"y2\") #> [1] \"100%\" #> #> $clipPath #> $clipPath$rect #> list() #> attr(,\"width\") #> [1] \"144\" #> attr(,\"height\") #> [1] \"20\" #> attr(,\"rx\") #> [1] \"3\" #> attr(,\"fill\") #> [1] \"#fff\" #> #> attr(,\"id\") #> [1] \"r\" #> #> $g #> $g$rect #> list() #> attr(,\"width\") #> [1] \"61\" #> attr(,\"height\") #> [1] \"20\" #> attr(,\"fill\") #> [1] \"#555\" #> #> $g$rect #> list() #> attr(,\"x\") #> [1] \"61\" #> attr(,\"width\") #> [1] \"83\" #> attr(,\"height\") #> [1] \"20\" #> attr(,\"fill\") #> [1] \"#fe7d37\" #> #> $g$rect #> list() #> attr(,\"width\") #> [1] \"144\" #> attr(,\"height\") #> [1] \"20\" #> attr(,\"fill\") #> [1] \"url(#s)\" #> #> attr(,\"clip-path\") #> [1] \"url(#r)\" #> #> $g #> $g$text #> $g$text[[1]] #> [1] \"my_label\" #> #> attr(,\"aria-hidden\") #> [1] \"true\" #> attr(,\"x\") #> [1] \"315\" #> attr(,\"y\") #> [1] \"150\" #> attr(,\"fill\") #> [1] \"#010101\" #> attr(,\"fill-opacity\") #> [1] \".3\" #> attr(,\"transform\") #> [1] \"scale(.1)\" #> attr(,\"textLength\") #> [1] \"510\" #> #> $g$text #> $g$text[[1]] #> [1] \"my_label\" #> #> attr(,\"x\") #> [1] \"315\" #> attr(,\"y\") #> [1] \"140\" #> attr(,\"transform\") #> [1] \"scale(.1)\" #> attr(,\"fill\") #> [1] \"#fff\" #> attr(,\"textLength\") #> [1] \"510\" #> #> $g$text #> $g$text[[1]] #> [1] \"my_message\" #> #> attr(,\"aria-hidden\") #> [1] \"true\" #> attr(,\"x\") #> [1] \"1015\" #> attr(,\"y\") #> [1] \"150\" #> attr(,\"fill\") #> [1] \"#010101\" #> attr(,\"fill-opacity\") #> [1] \".3\" #> attr(,\"transform\") #> [1] \"scale(.1)\" #> attr(,\"textLength\") #> [1] \"730\" #> #> $g$text #> $g$text[[1]] #> [1] \"my_message\" #> #> attr(,\"x\") #> [1] \"1015\" #> attr(,\"y\") #> [1] \"140\" #> attr(,\"transform\") #> [1] \"scale(.1)\" #> attr(,\"fill\") #> [1] \"#fff\" #> attr(,\"textLength\") #> [1] \"730\" #> #> attr(,\"fill\") #> [1] \"#fff\" #> attr(,\"text-anchor\") #> [1] \"middle\" #> attr(,\"font-family\") #> [1] \"Verdana,Geneva,DejaVu Sans,sans-serif\" #> attr(,\"text-rendering\") #> [1] \"geometricPrecision\" #> attr(,\"font-size\") #> [1] \"110\" #> #> attr(,\"width\") #> [1] \"144\" #> attr(,\"height\") #> [1] \"20\" #> attr(,\"role\") #> [1] \"img\" #> attr(,\"aria-label\") #> [1] \"my_label: my_message\" #> attr(,\"xmlns\") #> [1] \"http://www.w3.org/2000/svg\" #> attr(,\"xmlns:xlink\") #> [1] \"http://www.w3.org/1999/xlink\" inspect_badge <- function(badge) { x <- badge %>% read_xml() %>% as_list() %>% pluck(\"svg\") list( title = pluck(x, \"title\", 1), `aria-label` = pluck(x, attr_getter(\"aria-label\")) ) } inspect_badge(\"https://img.shields.io/badge/my__label-my__message-orange\") #> $title #> [1] \"my_label: my_message\" #> #> $`aria-label` #> [1] \"my_label: my_message\""},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"shields-io-badges-are-accessible-today","dir":"Articles","previous_headings":"Badge image","what":"shields.io badges are accessible today","title":"Exploring badge accessibility","text":"One reasons inspected shields.io badge may provide usable alternative service whose official badge (yet?) screen-reader-friendly. custom badge completely static. shields.io also supports custom dynamic badges, necessary information (label, message, color) available suitable JSON endpoint. Finally, relevant usethis, shields.io offers pre-configured dynamic badges commonly “badged” services, including GitHub Actions Codecov. shields.io badge usethis’s R CMD check workflow GitHub Actions: , indicating fields control my_alt_text my_label, ’s easier get feedback usethis . title aria-label badge : Now take inventory main badges inserted usethis things stand re: accessibility.","code":"inspect_badge(\"https://img.shields.io/github/workflow/status/r-lib/usethis/R-CMD-check?label=my_label-R-CMD-check\") #> $title #> [1] \"my_label-R-CMD-check: https://github.com/badges/shields/issues/8671\" #> #> $`aria-label` #> [1] \"my_label-R-CMD-check: https://github.com/badges/shields/issues/8671\""},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"r-cmd-check-status","dir":"Articles","previous_headings":"","what":"R CMD check status","title":"Exploring badge accessibility","text":"generally obtain current R CMD check status GitHub Actions workflow. official badge provided GitHub: title aria-label badge : time writing (late December 2021), badge include information. requested GitHub’s Actions Packages Feedback forum response GitHub encouraging. Hopefully native badge gain improved accessibility early 2022. https://github.com/github/feedback/discussions/8974 meantime, one use shields.io badge report R CMD check status, demonstrated previous section. maintainer one-, GitHub badge upgrade slow coming, implement usethis::use_github_actions_badge().","code":"inspect_badge(\"https://github.com/r-lib/usethis/actions/workflows/R-CMD-check.yaml/badge.svg\") #> $title #> [1] \"R-CMD-check.yaml - failing\" #> #> $`aria-label` #> NULL"},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"package-lifecycle","dir":"Articles","previous_headings":"","what":"Package lifecycle","title":"Exploring badge accessibility","text":"usethis::use_lifecycle_badge() declares developmental stage package, using framework https://lifecycle.r-lib.org/articles/stages.html. function already inserts shields.io badge: title aria-label badge : ’s possible usethis using badge “owned” lifecycle package. think don’t now, declaring lifecycle stage whole package necessarily imply need take formal dependency lifecycle package, usually causes badges copied man/figures/ directory. Also, badges shipped lifecycle package currently accessible, another reason use . opened issue (https://github.com/r-lib/lifecycle/issues/117). relatively easy fix, since static badges. done, package maintainers need update SVGs stored man/figures/.","code":"inspect_badge(\"https://img.shields.io/badge/lifecycle-stable-brightgreen.svg\") #> $title #> [1] \"lifecycle: stable\" #> #> $`aria-label` #> [1] \"lifecycle: stable\""},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"cran-status","dir":"Articles","previous_headings":"","what":"CRAN status","title":"Exploring badge accessibility","text":"usethis::use_cran_badge() places badge indicates package version available CRAN. badge served METACRAN (https://www.r-pkg.org) maintainer Gábor Csárdi already incorporated aria-label badges (commit). available badges listed . ’s badge placed usethis::use_cran_badge(): title aria-label badge : time writing (late December 2021), aria-label present, title . interested know good situation using screen reader.","code":"inspect_badge(\"https://www.r-pkg.org/badges/version/usethis\") #> $title #> NULL #> #> $`aria-label` #> [1] \"CRAN 3.0.0\""},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"code-coverage","dir":"Articles","previous_headings":"","what":"Code coverage","title":"Exploring badge accessibility","text":"usethis::use_coverage(type = c(\"codecov\", \"coveralls\", ...) calls internal helper usethis:::use_codecov_badge() insert badge either Codecov Coveralls service. examples two badges (note usethis use Coveralls, ’m using different package demo): title aria-label badges:: time writing (late December 2021), neither badge offers title aria-label. badges shields.io Codecov Coveralls: title aria-label shields.io badges::","code":"inspect_badge(\"https://codecov.io/gh/r-lib/usethis/branch/main/graph/badge.svg\") #> $title #> NULL #> #> $`aria-label` #> NULL inspect_badge(\"https://coveralls.io/repos/github/trinker/sentimentr/badge.svg?branch=master\") #> $title #> NULL #> #> $`aria-label` #> NULL inspect_badge(\"https://img.shields.io/codecov/c/github/r-lib/usethis?label=test%20coverage&logo=codecov\") #> $title #> [1] \"test coverage: 59%\" #> #> $`aria-label` #> [1] \"test coverage: 59%\" inspect_badge(\"https://img.shields.io/coveralls/github/trinker/sentimentr?logo=coveralls\") #> $title #> [1] \"coverage: 19%\" #> #> $`aria-label` #> [1] \"coverage: 19%\""},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"bioconductor","dir":"Articles","previous_headings":"","what":"Bioconductor","title":"Exploring badge accessibility","text":"package Bioconductor, usethis::use_bioc_badge() can used insert badge Bioconductor build status. badge: title aria-label badge: time writing (late December 2021), badge title aria-label. ’s immediately clear resolve , suspect Bioconductor receptive request create accessible badges.","code":"inspect_badge(\"http://www.bioconductor.org/shields/build/release/bioc/biocthis.svg\") #> $title #> NULL #> #> $`aria-label` #> NULL"},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"tldr-use-https-2fa-and-a-github-personal-access-token","dir":"Articles","previous_headings":"","what":"TL;DR: Use HTTPS, 2FA, and a GitHub Personal Access Token","title":"Managing Git(Hub) Credentials","text":"main recommendations : Adopt HTTPS Git transport protocol. Turn two-factor authentication GitHub account. Use personal access token (PAT) Git remote operations command line R. Allow tools store retrieve credentials Git credential store. previously set GitHub PAT .Renviron, stop . Next provide context rationale recommendations. following section, explain actually implement .","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"https-vs-ssh","dir":"Articles","previous_headings":"TL;DR: Use HTTPS, 2FA, and a GitHub Personal Access Token","what":"HTTPS vs SSH","title":"Managing Git(Hub) Credentials","text":"Instead HTTPS, use SSH. Many people valid reasons preferring SSH carry . recommendation HTTPS ’s easier SSH newcomers set correctly, especially Windows. GitHub also long recommended HTTPS new users. Finally, using HTTPS PAT kills two birds one stone: single credential can used authenticate GitHub regular Git server REST API. authenticate via SSH “regular” Git work, still set PAT work uses REST API.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"two-factor-authentication","dir":"Articles","previous_headings":"TL;DR: Use HTTPS, 2FA, and a GitHub Personal Access Token","what":"Two-factor authentication","title":"Managing Git(Hub) Credentials","text":"Turning two-factor authentication important online accounts just good idea, general. example, make 2FA hard requirement members tidyverse r-lib GitHub organizations. past, activating 2FA also forced using HTTPS use PAT, instead “username + password”, operations like git push. Using PAT now absolute requirement, operations using HTTPS protocol, longer anything 2FA. background deprecation “username + password” can found GitHub’s blog post Token authentication requirements Git operations.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"git-credential-helpers-and-the-credential-store","dir":"Articles","previous_headings":"TL;DR: Use HTTPS, 2FA, and a GitHub Personal Access Token","what":"Git credential helpers and the credential store","title":"Managing Git(Hub) Credentials","text":"’s awkward provide credentials every single Git transaction, ’s customary let system remember credentials. Git uses -called credential helpers , happily, tend “just work” days (especially, macOS Windows) 1. Git credential helpers take advantage official OS-provided credential stores, possible, macOS Keychain Windows Credential Manager. Recent innovations gert gh mean Git/GitHub operations R can also store discover credentials using official Git credential helpers. means can stop storing GitHub PATs plain text startup file, like .Renviron 2. , turn, reduces risk accidentally leaking credentials.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"practical-instructions","dir":"Articles","previous_headings":"","what":"Practical instructions","title":"Managing Git(Hub) Credentials","text":"actually implement recommendations? diagnostic functions usethis::gh_token_help() usethis::git_sitrep() offer advice see , directly R session.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"adopt-https","dir":"Articles","previous_headings":"Practical instructions","what":"Adopt HTTPS","title":"Managing Git(Hub) Credentials","text":"Make sure use HTTPS URLs, SSH, cloning repos adding new remotes: HTTPS URLs look like : https://github.com//.git SSH URLs look like : git@github.com:/.git usethis defaults HTTPS functions like create_from_github() use_github(), v2.0.03. ’s fine adopt HTTPS new work, even pre-existing repos use SSH. ’s fine use HTTPS one remote repo SSH another. ’s fine use HTTPS remotes one repo SSH remotes another. ’s fine interact GitHub repo via HTTPS one computer via SSH another. --nothing irreversible decision. long relevant tools can obtain necessary credentials cache , good go.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"turn-on-two-factor-authentication","dir":"Articles","previous_headings":"Practical instructions","what":"Turn on two-factor authentication","title":"Managing Git(Hub) Credentials","text":"See GitHub’s current instructions : Securing account two-factor authentication (2FA) don’t already use password manager 1Password Bitwarden, great time start! Among benefits, apps can serve authenticator 2FA. Turning 2FA recommended, optional.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"get-a-personal-access-token-pat","dir":"Articles","previous_headings":"Practical instructions","what":"Get a personal access token (PAT)","title":"Managing Git(Hub) Credentials","text":"Assuming ’re signed GitHub, create_github_token() takes pre-filled form create new PAT. can get page browser clicking “Generate new token” https://github.com/settings/tokens. advantage create_github_token() pre-selected recommended scopes, can look adjust clicking “Generate token”. good idea describe token’s purpose Note field, one day might multiple PATs. recommend naming token use case, computer project using , e.g. “personal-macbook-air” “vm--project-xyz”. future, find staring list tokens, inevitably ’ll need re-generate delete one . Make easy figure token need fiddle . GitHub encourages use perishable tokens, default Expiration period 30 days. Unless specific reason fight , recommend accepting default. assume GitHub’s security folks good reasons recommendation. , course, can adjust Expiration behaviour see fit, including “expiration”. ’re happy token’s Note, Expiration, Scopes, click “Generate token”. won’t able see token , don’t close navigate away browser window store PAT locally. Copy PAT clipboard, anticipating ’ll next: trigger prompt lets us store PAT Git credential store. Sidebar storing PAT: use password management app, 1Password Bitwarden (highly recommended!), might want add PAT (Note) entry GitHub. Storing PAT Git credential store semi-persistent convenience, sort like browser cache “remember ” website, ’s quite possible need re-enter PAT future. decide embrace impermanence PAT , somehow removed store, ’ll just re-generate new PAT re-enter . accept default 30-day expiration period, workflow ’ll using often anyway. create long-lasting tokens want play around functions setting clearing Git credentials, can handy record PAT secure place, like 1Password Bitwarden.","code":"usethis::create_github_token()"},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"put-your-pat-into-the-local-git-credential-store","dir":"Articles","previous_headings":"Practical instructions","what":"Put your PAT into the local Git credential store","title":"Managing Git(Hub) Credentials","text":"assume ’ve created PAT available clipboard. insert PAT Git credential store? R: gitcreds package installed, usethis v2.0.0, usethis uses gh, gh uses gitcreds. don’t PAT stored already, prompt enter PAT. Paste! already stored credential, gitcreds::gitcreds_set() reveals even let inspect . helps decide whether keep existing credential replace . doubt, embrace new, known---good credential old one, uncertain origins. previously made GitHub PAT available setting GITHUB_PAT environment variable .Renviron, need actively stop ! doubt previous practices, open .Renviron, look line setting GITHUB_PAT GITHUB_TOKEN environment variable, delete line. usethis::edit_r_environ() can helpful getting .Renviron open editing. Don’t forget restart R change take effect! can check PAT successfully stored usethis::gh_token_help() executed fresh R session: general function usethis::git_sitrep() also report PAT, along aspects Git/GitHub setup.","code":"gitcreds::gitcreds_set() > gitcreds::gitcreds_set() ? Enter password or token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -> Adding new credentials... -> Removing credentials from cache... -> Done. > gitcreds::gitcreds_set() -> Your current credentials for 'https://github.com': protocol: https host : github.com username: PersonalAccessToken password: <-- hidden --> -> What would you like to do? 1: Keep these credentials 2: Replace these credentials 3: See the password / token Selection: 2 -> Removing current credentials... ? Enter new password or token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -> Adding new credentials... -> Removing credentials from cache... -> Done. gh_token_help() git_sitrep()"},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"ongoing-pat-maintenance","dir":"Articles","previous_headings":"Practical instructions","what":"Ongoing PAT maintenance","title":"Managing Git(Hub) Credentials","text":"going (re-)generating (re-)storing PAT schedule dictated expiration period. default, per month. PAT expires, return https://github.com/settings/tokens click Note. (label tokens nicely use case, right? Right?) point, can optionally adjust scopes click “Regenerate token”. can optionally modify Expiration click “Regenerate token” (). , copy PAT clipboard, call gitcreds::gitcreds_set(), paste! Hopefully ’s becoming clear token’s Note important. actual token may changing, e.g., month, use case (scopes) much persistent stable. Sidebar: gitcreds package plays role gh credentials package gert. gitcreds credentials provide R interface Git credential store, targeting slightly different use cases. gitcreds credentials packages evolving convergently may, fact, merge one. meantime, chance use different “key”, “key-value” sense, storing retrieving PAT. Therefore, conceivable gert+credentials may also prompt PAT, case just provide . explicitly check gert+credentials can discover PAT, call credentials::set_github_pat(). , lead prompt can enter .","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"additional-resources","dir":"Articles","previous_headings":"","what":"Additional resources","title":"Managing Git(Hub) Credentials","text":"users ready work Git GitHub R now, specifically gert, gh, usethis. section, cover specialized topics apply certain users.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"github-enterprise","dir":"Articles","previous_headings":"Additional resources","what":"GitHub Enterprise","title":"Managing Git(Hub) Credentials","text":"v2.0.0, usethis fully support GitHub Enterprise deployments. find true, please open issue. usethis functions support explicit host argument, general, usethis honors GitHub host implicit URLs, e.g., locally configured Git remotes, inherits default behaviour gh. gh package honors GITHUB_API_URL environment variable , unset, falls back https://api.github.com. general, usethis, gh, gitcreds work GitHub Enterprise, long intended GitHub host discoverable specified. example, can store PAT GitHub Enterprise deployment like : can also troubleshoot PATs GHE usual functions: time writing, credentials::set_github_pat() hard-wired “github.com”, may generalized future.","code":"gitcreds::gitcreds_set(\"https://github.acme.com\") usethis::gh_token_help(\"https://github.acme.com\") # or usethis::git_sitrep()"},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"what-about--renviron","dir":"Articles","previous_headings":"Additional resources","what":"What about .Renviron?","title":"Managing Git(Hub) Credentials","text":"past, common way make GitHub PAT available R define GITHUB_PAT environment variable .Renviron startup file. still works, since gitcreds+gh credentials+gert check environment variables consult Git credential store. However, also means presence legacy GITHUB_PAT .Renviron can get way adoption new approach! doubt previous practices, open .Renviron, look line setting GITHUB_PAT environment variable, delete . usethis::edit_r_environ() can helpful getting .Renviron open editing. Don’t forget restart R change take effect. gitcreds+gh credentials+gert even check environment variables? retrieve PAT store, temporarily cache environment variable, persists duration current R session. allows discovered PAT reused, potentially multiple packages, repeatedly course R session. Using .Renviron primary PAT store less secure , can, safer keep PAT Git credential store let packages need discover upon first need. Linux users may still need use .Renviron method, since don’t easy access OS-managed stores like macOS Keychain Windows Credential Manager. still need use .Renviron method, usethis::edit_r_environ() opens file editing. Add line like , substitute PAT: Make sure file ends newline! Lack newline can lead silent failure load startup files, can tricky debug. Take care file accidentally pushed cloud, e.g. Google Drive GitHub. Restart R changes .Renviron take effect.","code":"usethis::edit_r_environ() GITHUB_PAT=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"what-about-the-remotes-and-pak-packages","dir":"Articles","previous_headings":"Additional resources","what":"What about the remotes and pak packages?","title":"Managing Git(Hub) Credentials","text":"remotes pak packages help us install R packages GitHub: Lifecycle-wise, remotes replaced pak, still transition period, maintained. packages potentially need GitHub PAT. PAT necessary, example, install private GitHub repo. Even accessing public resources, PAT helpful implies much higher rate limit requests GitHub API. pak uses PAT-finding approach usethis/gh/gitcreds. ’ve done setup described , pak “just work”, PAT everything else. remotes use new PAT-finding approach , instead, consults GITHUB_PAT environment variable, falling back built-generic credential. re: installing packages GitHub? personal recommendation: Use pak::pkg_install(\"OWNER/REPO\") explicit “install GitHub” needs. Allow remotes use fallback credential, ever gets called implicitly. define GITHUB_PAT .Renviron. want keep using remotes, instead pak, just rely built-credential. suffice rate-limiting concern, obviously provide access private repositories. really want use remotes, PAT, can “tickle” gitcreds, via gitcreds::gitcreds_get(), get load PAT store GITHUB_PAT environment variable, remotes happily find . done interactively needed, written individual scripts, even executed startup file. still avoids defining GITHUB_PAT .Renviron. use remotes, make sure update latest version, guarantee built-credential valid.","code":"remotes::install_github(\"r-lib/usethis\") pak::pkg_install(\"r-lib/usethis\") Sys.setenv(GITHUB_PAT = gitcreds::gitcreds_get(use_cache = FALSE)$password)"},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"continuous-integration","dir":"Articles","previous_headings":"Additional resources","what":"Continuous integration","title":"Managing Git(Hub) Credentials","text":"headless system, CI/CD platform like GitHub Actions, won’t able interactively store PAT gitcreds::gitcreds_set() credentials::set_github_pat(). case GitHub Actions, access token automatically available workflow can exposed R GITHUB_PAT environment variable like : automatic token doesn’t sufficient permissions, ’ll need create suitable token store repository secret. also general approach CI/CD platforms GitHub Actions: Provide PAT secure GITHUB_PAT environment variable. Use regular environment variables store less sensitive settings, API host. Take care expose PAT , e.g., printing environment variables log file.","code":"env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}"},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"how-to-learn-more","dir":"Articles","previous_headings":"","what":"How to learn more","title":"Managing Git(Hub) Credentials","text":"gh gitcreds gh: gh.r-lib.org gh vignette: Managing Personal Access Tokens gitcreds: r-lib.github.io/gitcreds/ gert credentials gert: docs.ropensci.org/gert credentials: docs.ropensci.org/credentials rOpenSci tech note: better way manage GitHub personal access tokens","code":""},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"contributing-to-someone-elses-package","dir":"Articles","previous_headings":"","what":"Contributing to someone else’s package","title":"Pull request helpers","text":", want contribute R package? ’s fantastic! walk process making -called pull request praise package. package designed help package developers “build friendly R packages praise users done something good, just need feel better.” can use praise construct encouraging feedback sampling collection positive adjectives, adverbs, verbs, smileys, exclamations: going propose new adjective: “formidable”.","code":"library(praise) template <- \"${EXCLAMATION} - your pull request is ${adjective}!\" praise(template) #> [1] \"YEE-HAW - your pull request is groovy!\""},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"whats-a-pull-request","dir":"Articles","previous_headings":"","what":"What’s a pull request?","title":"Pull request helpers","text":"pull request propose change GitHub repository. Think request maintainer pull changes repo. pr_*() family functions designed make working GitHub pull requests painless possible, contributors package maintainers. designed support Git GitHub workflows recommended Happy Git GitHub useR. pull request (PR) involves two players, contributor reviewer. make clear runs code, code chunks article color coded: code executed contributor appears chunks light gray background code executed reviewer appears chunks beige background.","code":"# contributor code # reviewer code"},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"set-up-advice","dir":"Articles","previous_headings":"","what":"Set up advice","title":"Pull request helpers","text":"article assumes already done Git GitHub parts setup vignette configured GitHub personal access token, described Managing Git(Hub) Credentials. good way check ready use pr_* family functions run git_sitrep(), prints info current Git, gert, GitHub setup. Specifically, pr_*() functions make use : create_github_token() helps set one . usethis can’t figure , might ask . can set usethis.protocol option proactively address . use \"https\" protocol, GitHub PAT credential need. good reason choose \"https\"!","code":""},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"attach-usethis","dir":"Articles","previous_headings":"","what":"Attach usethis","title":"Pull request helpers","text":"code assumes ’ve attached usethis R session:","code":"library(usethis)"},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"fork-and-clone","dir":"Articles","previous_headings":"","what":"Fork and clone","title":"Pull request helpers","text":"first step fork source repository, get copy GitHub, clone , get local copy. many ways accomplish two steps, demonstrate usethis::create_from_github(): : Forks praise repo, owned rladies GitHub, GitHub account. origin remote set praise repo. upstream remote set praise repo owned rladies. master branch set track upstream/master, can pull upstream changes future. Opens new instance RStudio praise project, ’re working RStudio. Otherwise, switches current R session project. Arguments might like know : Specify fork = TRUE fork = FALSE don’t want defer default behaviour. Use destdir put praise specific location computer. can set usethis.destdir option always want usethis put new projects specific directory.","code":"create_from_github(\"rladies/praise\") #> ℹ Defaulting to 'https' Git protocol #> ✓ Setting `fork = TRUE` #> ✓ Creating '/Users/mine/Desktop/praise/' #> ✓ Forking 'rladies/praise' #> ✓ Cloning repo from 'https://github.com/mine-cetinkaya-rundel/praise.git' into '/Users/mine/Desktop/praise' #> ✓ Setting active project to '/Users/mine/Desktop/praise' #> ℹ Default branch is 'master' #> ✓ Adding 'upstream' remote: 'https://github.com/rladies/praise.git' #> ✓ Pulling in changes from default branch of the source repo 'upstream/master' #> ✓ Setting remote tracking branch for local 'master' branch to 'upstream/master' #> ✓ Opening '/Users/mine/Desktop/praise/' in new RStudio session #> ✓ Setting active project to ''"},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"branch-then-make-your-change","dir":"Articles","previous_headings":"","what":"Branch, then make your change","title":"Pull request helpers","text":"start process contributing package pr_init(), creates branch repository pull request. good idea make pull requests feature branch, repo’s default branch, master (another common choice main). ’ll call branch \"formidable\". creates local branch called formidable switch (“check ”). Now can work locally, making changes files committing Git. Let’s go ahead make change, adding word “formidable” R/adjective.R file package. diff commit associated change. might spot made two mistakes : intended add “formidable”, added “formidabel” instead. forgot comma end line. Let’s assume didn’t actually catch mistakes, didn’t build check package, revealed missing comma. make mistakes.","code":"pr_init(branch = \"formidable\") #> ✓ Setting active project to '/Users/mine/Desktop/praise' #> ℹ Pulling changes from 'upstream/master' #> ✓ Creating and switching to local branch 'formidable' #> ● Use `pr_push()` to create PR."},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"submit-pull-request","dir":"Articles","previous_headings":"","what":"Submit pull request","title":"Pull request helpers","text":"pr_push() pushes local change copy praise GitHub puts position make pull request. launches browser window URL specified last message, looks like following. Click “Create pull request” make PR. clicking able choose draft PR actual PR (opening draft PR, mark ready review ’re done, e.g. commits one new call pr_push()). GitHub ping package maintainer review pull request. can view pull request browser pr_view(). anyone can follow along PR rladies/praise#90.","code":"pr_push() #> ✓ Checking that local branch 'formidable' has the changes in 'origin/formidable' #> ✓ Pushing local 'formidable' branch to 'origin/formidable' #> ✓ Create PR at link given below #> ✓ Opening URL 'https://github.com/mine-cetinkaya-rundel/praise/compare/formidable' pr_view(90) #> ✔ Opening URL 'https://github.com/rladies/praise/pull/90'"},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"review-of-the-pull-request","dir":"Articles","previous_headings":"","what":"Review of the pull request","title":"Pull request helpers","text":"’re lucky, pull request perfect, maintainer accept , .k.. merge . However, case, PR still needs work. package maintainer leaves us comments requesting changes. somewhat new , try address one comments (fix spelling) neglect (forget add comma). make another change commit . Run pr_push() update branch fork, automatically reflected PR. Now reviewer gets another chance review changes. point might choose just make necessary changes push commits pull request finish things . , reviewer fetches PR local machine pr_fetch(). Fetching PR creates local branch called mine-cetinkaya-rundel-formidable, text string comprised GitHub username contributor name branch created PR. pr_fetch() also sets upstream tracking branch local branch got created switches branch reviewer can make changes correct branch. reviewer makes necessary changes, adding missing comma, run pr_push() push changes PR.","code":"pr_push() #> ✔ Pushing local 'formidable' branch to 'origin:formidable' #> ✔ Setting upstream tracking branch for 'formidable' to 'origin/formidable' #> ✔ Create PR at link given below #> ✔ Opening URL 'https://github.com/mine-cetinkaya-rundel/praise/compare/formidable' pr_fetch(90) #> ✔ Setting active project to '/Users/gaborcsardi/works/praise' #> ✔ Checking out PR 'rladies/praise/#90' (@mine-cetinkaya-rundel): 'Add \"formidable\" to adjectives' #> ✔ Adding remote 'mine-cetinkaya-rundel' as 'git@github.com:mine-cetinkaya-rundel/praise.git' #> ✔ Creating local branch 'mine-cetinkaya-rundel-formidable' #> ✔ Setting upstream tracking branch for 'mine-cetinkaya-rundel-formidable' to 'mine-cetinkaya-rundel/formidable' #> ✔ Switching to branch 'mine-cetinkaya-rundel-formidable' #> ✔ Pulling changes from GitHub PR pr_push() #> ✔ Checking that local branch 'mine-cetinkaya-rundel-formidable' has the changes in 'mine-cetinkaya-rundel/formidable' #> ✔ Pushing local 'mine-cetinkaya-rundel-formidable' branch to 'mine-cetinkaya-rundel:formidable' #> ✔ View PR at 'https://github.com/rladies/praise/pull/90' or call `pr_view()`"},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"merge-and-finish","dir":"Articles","previous_headings":"","what":"Merge and finish","title":"Pull request helpers","text":"Finally, reviewer merges pull request GitHub. Locally, can run pr_finish() switch back default branch (usually named main master), pull, delete local branch created process interacting PR, remove associated remote. Since reviewer contributed code pull request, can get code back computer pr_pull(). optional , since full PR already incorporated default branch source repo (usually named main master). pr_pull() can useful PRs rounds alternating contributions maintainer. Finally, can also conclude PR process end pr_finish(). Remember can see whole PR unfolded rladies/praise#90.","code":"pr_finish() #> ✔ Checking that remote branch 'mine-cetinkaya-rundel/formidable' has the changes in 'local/mine-cetinkaya-rundel-formidable' #> ✔ Switching back to 'master' branch #> ✔ Pulling changes from GitHub source repo 'origin/master' #> ✔ Deleting local 'mine-cetinkaya-rundel-formidable' branch #> ✔ Removing remote 'mine-cetinkaya-rundel' pr_pull() #> ✓ Pulling from 'origin/formidable' #> Performing fast-forward merge, no commit needed pr_finish() #> ✓ Checking that remote branch 'origin/formidable' has the changes in 'formidable' #> ✓ Switching back to default branch ('master') #> ℹ Pulling changes from 'origin/master' #> ✓ Deleting local 'formidable' branch"},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"other-helpful-functions","dir":"Articles","previous_headings":"","what":"Other helpful functions","title":"Pull request helpers","text":"functions pr_*() family didn’t encounter PR scenario: pr_merge_main() used getting changes occurred main line development working PR. ’re working fork, git pull upstream master. ’re making PR internal branch, git pull origin master. can useful execute PR branch, big changes project PR become un-mergeable. also useful execute whenever return default branch (usually named main master) , indeed, pr_pause() includes . makes sure copy package --date source repo. pr_pause() makes sure ’re synced PR, switches back default branch, calls pr_merge_main() keep --date source repo. likely something package maintainer reviewing numerous PRs need use, switch back forth reviewing/extending PRs main line development default branch. pr_resume() helps resume work PR ’ve spent time another branch checked . give arguments, present interactive choice local branches indicates , , associated PR.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"block-styles","dir":"Articles","previous_headings":"","what":"Block styles","title":"Converting usethis's UI to use cli","text":"block styles exist produce bulleted output specific symbol, using specific color. Another important feature output can turned package-wide via usethis.quiet option. styles close can done cli::cli_bullets() way responds names input text. direct translation look something like : overall conversion plan switch new function, ui_bullets(), wrapper around cli::cli_bullets(), adds features: Early exit, without emitting messages, usethis.quiet option TRUE. usethis theme, changes color certain bullet styles adds new style todo’s. Summary ’ve done todo’s: Introduce new bullet shortcode todo. Proposal: _ (instead *), seems best single ascii character evokes place check something . Use cli::symbol$checkbox_off symbol (instead generic bullet). guess continue red. terms block styles, just leaves ui_code_block(), pretty different. ui_code_block() used put code screen optionally place clipboard. created new function, ui_code_snippet() built around cli::code_block(). Main observations: cli::code_block(language = \"R\") applies syntax highlighting hyperlinks (e.g. function help topics) R code, cool. Therefore language argument also exposed ui_code_snippet(), defaulting \"R\". Use \"\" anything ’s R code: > ui_code_snippet(\"x <- 1 + 2\") x <- 1 + 2 > ui_code_snippet(\"#include \", language = \"\") #include ui_code_snippet() takes scalar glue-type template string vector lines. Note two calls produce output. > ui_code_snippet(\" + options( + warnPartialMatchArgs = TRUE, + warnPartialMatchDollar = TRUE, + warnPartialMatchAttr = TRUE + )\") options( warnPartialMatchArgs = TRUE, warnPartialMatchDollar = TRUE, warnPartialMatchAttr = TRUE ) > # produces result > ui_code_snippet(c( + \"options(\", + \" warnPartialMatchArgs = TRUE,\", + \" warnPartialMatchDollar = TRUE,\", + \" warnPartialMatchAttr = TRUE\", + \")\")) options( warnPartialMatchArgs = TRUE, warnPartialMatchDollar = TRUE, warnPartialMatchAttr = TRUE ) Use interpolate = FALSE, don’t need interpolation. usual glue thing double , .e. {{ }}. becomes real pain, open issue/PR adding .open .close arguments ui_code_snippet().","code":"> f <- function() { + ui_todo(\"ui_todo(): red bullet\") + ui_done(\"ui_done(): green check\") + ui_oops(\"ui_oops(): red x\") + ui_info(\"ui_info(): yellow i\") + ui_line(\"ui_line(): (no symbol)\") + } > f() • ui_todo(): red bullet ✔ ui_done(): green check ✖ ui_oops(): red x ℹ ui_info(): yellow i ui_line(): (no symbol) > withr::with_options( + list(usethis.quiet = TRUE), + ui_info(\"You won't see this message.\") + ) > withr::with_options( + list(usethis.quiet = FALSE), # this is the default + ui_info(\"But you will see this one.\") + ) ℹ But you will see this one. > cli::cli_bullets(c( + \"noindent\", + \" \" = \"indent\", + \"*\" = \"bullet\", + \">\" = \"arrow\", + \"v\" = \"success\", + \"x\" = \"danger\", + \"!\" = \"warning\", + \"i\" = \"info\" + )) noindent indent • bullet → arrow ✔ success ✖ danger ! warning ℹ info > ui_bullets(c( + \"v\" = \"A great success!\", + \"_\" = \"Something you need to do.\", + \"x\" = \"Bad news.\", + \"i\" = \"The more you know.\", + \" \" = \"I'm just here for the indentation.\", + \"No indentation at all. Not used much in usethis.\" + )) ✔ A great success! ☐ Something you need to do. ✖ Bad news. ℹ The more you know. I'm just here for the indentation. No indentation at all. Not used much in usethis. > ui_code_snippet(\"x <- 1 + 2\") x <- 1 + 2 > ui_code_snippet(\"#include \", language = \"\") #include > ui_code_snippet(\" + options( + warnPartialMatchArgs = TRUE, + warnPartialMatchDollar = TRUE, + warnPartialMatchAttr = TRUE + )\") options( warnPartialMatchArgs = TRUE, warnPartialMatchDollar = TRUE, warnPartialMatchAttr = TRUE ) > # produces same result as > ui_code_snippet(c( + \"options(\", + \" warnPartialMatchArgs = TRUE,\", + \" warnPartialMatchDollar = TRUE,\", + \" warnPartialMatchAttr = TRUE\", + \")\")) options( warnPartialMatchArgs = TRUE, warnPartialMatchDollar = TRUE, warnPartialMatchAttr = TRUE )"},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"utility-functions","dir":"Articles","previous_headings":"","what":"Utility functions","title":"Converting usethis's UI to use cli","text":"block style functions route unexported utility functions. is_quiet() just consults usethis.quiet option implements default FALSE. ui_bullet() intermediate helper used ui_todo(), ui_done(), ui_oops() ui_info(). hygiene related indentation (using indent() utility function), calls ui_inform(). ui_line() ui_code() call ui_inform() directly. ui_inform() just wrapper around rlang::inform() guarded call is_quiet() is_quiet(), continue play role, anticipate longer need utilities (indent(), ui_bullet(), ui_inform()). Updates future: indent() turns still useful ui_code_snippet(), ’ve inlined , avoid reliance definitions ui-legacy.R. ui_bullet() renamed ui_legacy_bullet() auto-completion happiness new ui_bullets(). Let’s cover ui_silence() ’re , exported. ’s just withr::with_*() function executing code usethis.quiet = TRUE.","code":"is_quiet <- function() { isTRUE(getOption(\"usethis.quiet\", default = FALSE)) } ui_inform <- function(...) { if (!is_quiet()) { inform(paste0(...)) } invisible() } ui_silence <- function(code) { withr::with_options(list(usethis.quiet = TRUE), code) }"},{"path":[]},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"legacy-functions","dir":"Articles","previous_headings":"Inline styles","what":"Legacy functions","title":"Converting usethis's UI to use cli","text":"usethis inline styles (mostly) use inside functions like ui_todo(): ui_field() ui_value() ui_path() ui_code() ui_unset() inline styles enact combination : Color, e.g. crayon::green(x) Collapsing collection things one thing, e.g. c(\"\", \"b\", \"c\") “, b, c” Quoting, e.g. encodeString(x, quote = \"'\") ui_path() special potentially modifies input styling . ui_path() first makes path relative specific base (default, active project root) , path directory, also ensures trailing /. ui_unset() special purpose helper used need report something unknown, configured, nonexistent, etc.","code":"> new_val <- \"oxnard\" > x <- glue(\"{ui_field('name')} set to {ui_value(new_val)}\") > dput(x) structure(\"\\033[32mname\\033[39m set to \\033[34m'oxnard'\\033[39m\", class = c(\"glue\", \"character\")) > ui_done(x) ✔ name set to 'oxnard' > x <- glue(\"Your super secret password is {ui_unset()}.\") > dput(x) structure(\"Your super secret password is \\033[90m\\033[39m.\", clas s = c(\"glue\", \"character\")) > ui_info(x) ℹ Your super secret password is ."},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"cli-replacements","dir":"Articles","previous_headings":"Inline styles","what":"cli replacements","title":"Converting usethis's UI to use cli","text":"general, can move towards cli’s native inline-markup: https://cli.r-lib.org/reference/inline-markup.html ’s general conversion plan: ui_field() becomes {.field blah}. usethis_theme(), tweak .field style apply single quotes color available, ui_field() always done. ui_value() becomes {.val value}. ui_path() connected {.path path//thing}, , explained , ui_path() also . Therefore, abstracted “path math” internal helper, ui_path_impl(), aliased pth() compactness. ’s typical conversion: nice create custom inline class, e.g. {.ui_path {some_path}}, done , e.g., googledrive. ’s easy still inheriting cli’s file: hyperlink behaviour, desirable. leads somewhat clunky, verbose pattern , gives nice result. ui_code() gets replaced various inline styles, depending actual goal , : {.code some_text} {.arg some_argument} {.cls some_class} {.fun devtools::build_readme} {.help some_function} {.run usethis::usethis_function()} {.topic some_topic} {.var some_variable} ui_unset() replaced ui_special(), ’ll see . Currently intended grey color doesn’t show render document using solarized-dark far can’t get bottom :( isn’t grey “[Copied clipboard]” ui_code_snippet(), work?","code":"# using legacy functions ui_done(\"Setting {ui_field('LazyData')} to \\\\ {ui_value('true')} in {ui_path('DESCRIPTION')}\") # using new cli-based ui ui_bullets(c( \"v\" = \"Setting {.field LazyData} to {.val true} in {.path {pth('DESCRIPTION')}}.\" ))"},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"conditions","dir":"Articles","previous_headings":"","what":"Conditions","title":"Converting usethis's UI to use cli","text":"’m moving ui_stop(): ui_abort(): main point ui_abort() use cli_abort() (continue applying \"usethis_error\" class). also use ui_abort() apply different default bullet naming/styling. Starting \"x\" defaulting \"\" seems fit best usethis’s existing errors. bullets explicitly given honored. rlang::abort() cli::cli_abort() start \"!\" default, use \"*\" \" \", respectively. legacy functions also include ui_warn(). little usage , instead converting , ’ve eliminated use altogether favor \"!\" bullet: Sidebar: Now ’m looking lot new errors ui_abort() realize usethis also needs passing call argument along. ’m going leave future, separate effort.","code":"ui_stop <- function(x, .envir = parent.frame()) { x <- glue_collapse(x, \"\\n\") x <- glue(x, .envir = .envir) cnd <- structure( class = c(\"usethis_error\", \"error\", \"condition\"), list(message = x) ) stop(cnd) } ui_abort <- function(message, ..., class = NULL, .envir = parent.frame()) { cli::cli_div(theme = usethis_theme()) # bullet naming gymnastics, see below cli::cli_abort( message, class = c(class, \"usethis_error\"), .envir = .envir, ... ) } > block_start = \"# <<<\" > block_end = \"# >>>\" > ui_abort(c( + \"Invalid block specification.\", + \"Must start with {.code {block_start}} and end with {.code {block_en d}}.\" + )) Error: ✖ Invalid block specification. ℹ Must start with `# <<<` and end with `# >>>`. Run `rlang::last_trace()` to see where the error occurred. atever.\")) Error: ✔ It's weird to give a green check in an error, but whatever. Run `rlang::last_trace()` to see where the error occurred. > ui_abort(c( + \"!\" = \"Things are not ideal.\", + \">\" = \"Look at me!\" + )) Error: ! Things are not ideal. → Look at me! Run `rlang::last_trace()` to see where the error occurred. > ui_bullets(c(\"!\" = \"The guy she told you not to worry about.\")) ! The guy she told you not to worry about."},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"sitrep-and-format-helpers","dir":"Articles","previous_headings":"","what":"Sitrep and format helpers","title":"Converting usethis's UI to use cli","text":"small clump functions support sitrep-type output. hd_line() unexported , apparently, unused! now removed kv_line() unexported, new cli implementation ui_unset() exported succeeded ui_special() kv_line() stands “key-value line”. ’s used : Key features: Interpolates data applies inline style result. Works differently key value, ’re much likely use interpolation styling key value. special handling value NULL. Applies \"*\" bullet name/style result. won’t show updated source kv_line() usage show ’s capable : ui_special() successor ui_unset().","code":"> kv_line_legacy <- function(key, value, .envir = parent.frame()) { + value <- if (is.null(value)) ui_unset() else ui_value(value) + key <- glue(key, .envir = .envir) + ui_inform(glue(\"{cli::symbol$bullet} {key}: {value}\")) + } > > url <- \"https://github.com/r-lib/usethis.git\" > remote <- \"origin\" > kv_line_legacy(\"URL for the {ui_value(remote)} remote\", url) • URL for the 'origin' remote: 'https://github.com/r-lib/usethis.git' > > host <- \"github.com\" > kv_line_legacy(\"Personal access token for {ui_value(host)}\", NULL) • Personal access token for 'github.com': > noun <- \"thingy\" > value <- \"VALUE\" > kv_line(\"Let's reveal {.field {noun}}\", \"whatever\") • Let's reveal thingy: \"whatever\" > > kv_line(\"URL for the {.val {remote}} remote\", I(\"{.url {url}}\")) • URL for the \"origin\" remote: > > kv_line(\"Personal access token for {.val {host}}\", NULL) • Personal access token for \"github.com\": > > kv_line(\"Personal access token for {.val {host}}\", ui_special(\"discove red\")) • Personal access token for \"github.com\": "},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"questions","dir":"Articles","previous_headings":"","what":"Questions","title":"Converting usethis's UI to use cli","text":"’s currently drop-substitute ui_yeah() ui_nope() cli. Related issues: https://github.com/r-lib/cli/issues/228, https://github.com/r-lib/cli/issues/488. Therefore, meantime, ui_yeah() ui_nope() -quite-superseded external users. However, internally, ’ve switched unexported functions ui_yep() ui_nah() lightly modified versions ui_yeah() ui_nope() use cli styling.","code":"if (ui_nope(\" Current branch ({ui_value(actual)}) is not repo's default \\\\ branch ({ui_value(default_branch)}).{details}\")) { ui_abort(\"Cancelling. Not on desired branch.\") }"},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"miscellaneous-notes","dir":"Articles","previous_headings":"","what":"Miscellaneous notes","title":"Converting usethis's UI to use cli","text":"’ve adding period end messages, general rule. terms whitespace indentation, ’ve settled conventions. overall goal get right user-facing output (obviously), making easy possible predict ’s going look like ’re writing code. Key points: Put ui_bullets(c( line, bullet items, followed )) line. Sometimes make exception bullet list exactly one, short bullet item. Use hard line breaks inside bullet text comply surrounding line length. subsequent lines, use indentation get just past opening \". extraneous white space later rationalized cli, handles wrapping. Surround bullet names like x quotes, even though don’t , ’s required names, ! _ ’s better consistent. ’s another style like applies ui_abort(), ’s just one, unnamed bullet, call doesn’t fit one line.","code":"ui_bullets(c( \"i\" = \"Downloading into {.path {pth(destdir)}}.\", \"_\" = \"Prefer a different location? Cancel, try again, and specify {.arg destdir}.\" )) ... ui_bullets(c(\"x\" = \"Things are very wrong.\")) pr <- list(pr_number = 13) ui_abort(\" The repo or branch where PR #{pr$pr_number} originates seems to have been deleted.\")"},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"use-usethis-or-devtools-in-interactive-work","dir":"Articles","previous_headings":"","what":"Use usethis or devtools in interactive work","title":"usethis setup","text":"usethis package carved devtools package part “conscious uncoupling” v2.0.0 release. note devtools makes usethis’s functions available feel like part devtools . addition, devtools offers functions exposes selected functionality packages. might enjoy making devtools (therefore usethis) available interactive R work. Call usethis::use_devtools() prompts : : Open .Rprofile startup file editing. Show necessary code snippet console put clipboard. Prompt paste, save, close, restart R. Done! suggested snippet looks like : resources .Rprofile: official Startup documentation Startup chapter Forgot Teach R workshop materials Kevin Ushey’s blog post RProfile Essentials","code":"library(devtools) ## or library(usethis) use_devtools() if (interactive()) { suppressMessages(require(devtools)) }"},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"store-default-values-for-description-fields-and-other-preferences","dir":"Articles","previous_headings":"","what":"Store default values for DESCRIPTION fields and other preferences","title":"usethis setup","text":"Certain options consulted usethis allow set personal defaults: usethis.full_name: consulted making, e.g., supplemental license files. usethis.protocol: specifies preferred transport protocol Git. Either “https” (usethis default) “ssh”. See help git_protocol() . usethis.description: named list default DESCRIPTION fields new packages made usethis::create_package(). usethis.quiet: TRUE, prevents usethis printing messages console. usethis.destdir: default directory use create_from_github() use_course(). usethis.overwrite: TRUE, usethis overwrites existing file without asking user confirmation file inside Git repo. rationale normal Git workflow makes easy see selectively accept/discard proposed changes. Define options .Rprofile, can opened editing via usethis::edit_r_profile(). example code: Save similar code .Rprofile restart R take effect.","code":"options( usethis.description = list( \"Authors@R\" = utils::person( \"Jane\", \"Doe\", email = \"jane@example.com\", role = c(\"aut\", \"cre\"), comment = c(ORCID = \"JANE'S-ORCID-ID\") ) ), usethis.destdir = \"~/the/place/where/I/keep/my/R/projects\", usethis.overwrite = TRUE )"},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"the-sitrep-functions","dir":"Articles","previous_headings":"","what":"The “sitrep” functions","title":"usethis setup","text":"functions gather information help others troubleshoot things: proj_sitrep(): prints info active usethis project, working directory, active RStudio Project. Points things peculiar fix. git_sitrep(): prints info current Git, gert, GitHub setup. “Sitrep” short “situation report”.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"get-a-github-com-account","dir":"Articles","previous_headings":"","what":"Get a GitHub.com account","title":"usethis setup","text":"Sign free account GitHub.com. Happy Git GitHub useR provides advice picking username.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"install-git","dir":"Articles","previous_headings":"","what":"Install Git","title":"usethis setup","text":"Please see Happy Git GitHub useR instructions install Git. beyond scope article. usethis actually need Git install, uses gert package wraps libgit2. , chances , want normal Git things, like diff commit push, RStudio shell must install Git. Gert’s credential management also works best official Git tooling available.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"configure-user-name-and-user-email","dir":"Articles","previous_headings":"","what":"Configure user.name and user.email","title":"usethis setup","text":"Git installed, introduce Git. usethis::use_git_config() helps configure user.name user.email. Substitute name email address. user name give Git? GitHub username, although can . Another good option actual first name last name. commits labelled name, informative potential collaborators. email give Git? must email associated GitHub account. usethis::git_sitrep() generates git situation-report. can help confirm things work expected; can also help diagnose problems.","code":"library(usethis) ## or library(devtools) use_git_config(user.name = \"Jane Doe\", user.email = \"jane@example.com\") # check by running a git situation-report: # - your user.name and user.email should appear in global Git config git_sitrep()"},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"equivalent-git-commands","dir":"Articles","previous_headings":"Configure user.name and user.email","what":"Equivalent Git commands","title":"usethis setup","text":"code chunk equivalent :","code":"git config --global user.name 'Jane Doe' git config --global user.email 'jane@example.com' git config --global --list"},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"optional-configure-gits-editor","dir":"Articles","previous_headings":"Configure user.name and user.email","what":"Optional: configure Git’s editor","title":"usethis setup","text":"Another Git option many people eventually configure editor. come use Git shell. point, fail give Git wants terms commit message kick editor. can distressing, ’s editor choice don’t even know save quit. can enforce executing R: thing command line Git, execute shell: Substitute preferred editor emacs . popular choice nano. default, don’t configure core.editor, usually vim.","code":"library(usethis) use_git_config(core.editor = \"nano\") git config --global core.editor emacs"},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"connections-git-github-rstudio","dir":"Articles","previous_headings":"","what":"Connections: Git, GitHub, RStudio","title":"usethis setup","text":"stated , usethis doesn’t actually use Git install absolute requirement use GitHub use RStudio. use usethis highly correlated desire things, pleasant way. plan use GitHub, need make sure local Git can pull push GitHub.com. beyond scope article, see Connect GitHub section Happy Git. probably don’t want enter username password time, either cache credentials HTTPS set SSH keys. SSH person, set usethis.protocol option “ssh” (v2.0.0, “https” usethis default). want use RStudio work Git (therefore GitHub, see previous paragraph), need make sure RStudio can find Git executable. usually “just works”. Connect RStudio Git GitHub section Happy Git helps confirm well. well, also troubleshooting tips.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"get-and-store-a-github-personal-access-token","dir":"Articles","previous_headings":"","what":"Get and store a GitHub personal access token","title":"usethis setup","text":"GitHub personal access token (PAT) required want use use_github(), create_from_github(..., fork = TRUE), many usethis functions create something GitHub, repo, issue, pull request. Unlike pulling pushing, regular Git operations usual GitHub credentials necessarily work (although can, play cards right; see linked article). Git/GitHub credential management detailed separate article: Managing Git(Hub) Credentials","code":""},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"prepare-your-system-to-build-packages-from-source","dir":"Articles","previous_headings":"","what":"Prepare your system to build packages from source","title":"usethis setup","text":"participate R development, inevitably want run development versions people’s packages, .e. version available CRAN. typical way install package GitHub pak::pak(\"OWNER/REPO\"). , unlike using install.packages() CRAN, downloading installing source package, binary package. means system needs set building R packages. , long, need build R package compiled code . full description setting R development environment beyond scope article, give pointers diagnostics get started. Update R packages. expect keep frequently. work RStudio, often assist setting dev environment upon first need. Call devtools::has_devel() get initial sense whether R package build tools installed available. pkgbuild::check_build_tools() another function report system , interactive RStudio session, trigger automatic installation build tools. also possible install build tools . macOS: convenient way get tools needed compilation install Xcode Command Line Tools. Note much smaller full Xcode. shell, enter xcode-select --install. installing almost anything else, consider using Homebrew. Windows: Install Rtools. R package! “collection resources building packages R Microsoft Windows, building R ”. Go https://cran.r-project.org/bin/windows/Rtools/ install instructed.","code":""},{"path":"https://usethis.r-lib.org/dev/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Hadley Wickham. Author. Jennifer Bryan. Author, maintainer. Malcolm Barrett. Author. Andy Teucher. Author. . Copyright holder, funder.","code":""},{"path":"https://usethis.r-lib.org/dev/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Wickham H, Bryan J, Barrett M, Teucher (2024). usethis: Automate Package Project Setup. R package version 3.0.0.9000, https://github.com/r-lib/usethis, https://usethis.r-lib.org.","code":"@Manual{, title = {usethis: Automate Package and Project Setup}, author = {Hadley Wickham and Jennifer Bryan and Malcolm Barrett and Andy Teucher}, year = {2024}, note = {R package version 3.0.0.9000, https://github.com/r-lib/usethis}, url = {https://usethis.r-lib.org}, }"},{"path":"https://usethis.r-lib.org/dev/index.html","id":"usethis-","dir":"","previous_headings":"","what":"Automate Package and Project Setup","title":"Automate Package and Project Setup","text":"usethis workflow package: automates repetitive tasks arise project setup development, R packages non-package projects.","code":""},{"path":"https://usethis.r-lib.org/dev/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"Automate Package and Project Setup","text":"Install released version usethis CRAN: install development version GitHub :","code":"install.packages(\"usethis\") # install.packages(\"pak\") pak::pak(\"r-lib/usethis\")"},{"path":"https://usethis.r-lib.org/dev/index.html","id":"usage","dir":"","previous_headings":"","what":"Usage","title":"Automate Package and Project Setup","text":"use_*() functions operate active project: literally, directory computer. ’ve just used usethis create new package project, active project. Otherwise, usethis verifies current working directory valid project directory becomes active project. Use proj_get() proj_sitrep() manually query project read docs. usethis functions strong connections projects expect provide path. usethis quite chatty, explaining ’s assigning tasks. ✔ indicates something usethis done . ☐ indicates ’ll need work . quick look usethis can help set package. remember, many usethis functions also applicable analytical projects packages.","code":"library(usethis) # Create a new package ------------------------------------------------- path <- file.path(tempdir(), \"mypkg\") create_package(path) #> ✔ Creating '/tmp/RtmpCJHMlj/mypkg/'. #> ✔ Setting active project to \"/private/tmp/RtmpCJHMlj/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.3.2 #> ✔ Writing 'NAMESPACE'. #> ✔ Setting active project to \"\". # only needed since this session isn't interactive proj_activate(path) #> ✔ Setting active project to \"/private/tmp/RtmpCJHMlj/mypkg\". #> ✔ Changing working directory to '/tmp/RtmpCJHMlj/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 ggplot2 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\" and \"y\" to \"data/x.rda\" and \"data/y.rda\". #> ☐ Document your data (see ). # Use git ------------------------------------------------------------ use_git() #> ✔ Initialising Git repo. #> ✔ Adding \".Rproj.user\", \".Rhistory\", \".Rdata\", \".httr-oauth\", \".DS_Store\", and #> \".quarto\" to '.gitignore'."},{"path":"https://usethis.r-lib.org/dev/index.html","id":"code-of-conduct","dir":"","previous_headings":"","what":"Code of Conduct","title":"Automate Package and Project Setup","text":"Please note usethis project released Contributor Code Conduct. contributing project, agree abide terms.","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":null,"dir":"","previous_headings":"","what":"usethis design principles","title":"usethis design principles","text":"experiment making key package design principles explicit, versus implicit code. goal make maintenance easier, spread time across people.","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"active-project","dir":"","previous_headings":"","what":"Active project","title":"usethis design principles","text":"Many usethis functions act active project, path stored internal environment proj, specifically proj$cur. instead constantly passing around base path relying working directory. implied functions create modify files inside active project. mostly true use_*() functions, though exceptions. example, use_course() makes reference active project. project activated upon first need, .e. eventually function calls proj_get() , proj$cur NULL, attempt activate project () current working directory. Direct read/write proj$cur never happen, even internally. Instead, use proj_get() proj_set(). possible (.e. don’t want trigger project activation), use proj_get_() proj_set_(). one must use proj_set_() directly, remember stored project path processed proj_path_prep(). Form paths files within project proj_path(). Get paths relative project proj_rel_path().","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"activation-upon-load-or-attach-no","dir":"","previous_headings":"Active project","what":"Activation upon load or attach? No.","title":"usethis design principles","text":"’ve contemplated project activation .onLoad() .onAttach(), ’s clear appropriate. suggests neither appropriate. ever , zzz.R include something like : .onAttach()? package imported usethis also need set project attach. Currently user can open R, attach (load) usethis, change working directory target project. long project first time proj_get() called, correct project made active. preferred workflow, common.","code":".onLoad <- function(libname, pkgname) { try(proj_set(\".\", quiet = TRUE), silent = TRUE) }"},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"helper-functions","dir":"","previous_headings":"","what":"Helper functions","title":"usethis design principles","text":"ambivalence, internally-oriented helpers like write_union() exported. helps developers extending usethis create package standardize project setup within organization. downside aren’t exactly sure yet ’re willing guarantee helpers.","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"permission-to-overwrite","dir":"","previous_headings":"Helper functions","what":"Permission to overwrite","title":"usethis design principles","text":"write_over() returns FALSE nothing need overwrite (proposed file contents existing) user says “” returns TRUE overwrites. downstream logic depends whether something new written, consult return value. write_over() rarely called directly, usually called via use_template(), case handling apply return value.","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"helpers-and-the-active-project","dir":"","previous_headings":"Helper functions","what":"Helpers and the active project","title":"usethis design principles","text":"Two opposing mindsets: Helpers low-level general make direct use active project, change active project (activate first place). .e. project-based paths formed caller. Everything refer active project, unless ’s specific reason . Ideally, exported file writing helpers make direct reference active project. However, violate , due care, benefits us: write_utf8() potentially consults project path lives re: line ending. implementation takes care respect , also change active project. write_over() (can_overwrite(), really) , except case ’re determining whether path within Git repo. write_union() uses active project, exists, create humane path message. also actively avoids activating changing project. Git/GitHub helpers generally assume ’re working Git repo also active project. unexported. Prefer git_repo() proj_get(), choice, get benefit check_uses_git() ’s git_repo().","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"home-directory","dir":"","previous_headings":"","what":"Home directory","title":"usethis design principles","text":"usethis relies fs file system operations. main thing users notice treatment home directory Windows. Windows user’s home directory interpreted C:\\Users\\username (typical Unix-oriented tools, like Git ssh; also matches Python), opposed C:\\Users\\username\\Documents (R’s default Windows). order consistent everywhere, paths supplied user processed user_path_prep().","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"communicating-with-the-user","dir":"","previous_headings":"","what":"Communicating with the user","title":"usethis design principles","text":"User-facing messages ALWAYS emitted via helpers utils-ui.R. intentional preserved. can control verbosity package-wide usethis.quiet option, defaults FALSE. Exploited usethis tests: option set unset setup.R teardown.R, suppress output default. Individual tests need output, e.g. snapshot testing, include withr::local_options(usethis.quiet = FALSE). packages can muffle usethis call similar means. ui_silence() convenience helper executing small bits code silently. Note usethis exports many ui_*() functions historical reasons, defined ui-legacy.R, marked superseded now. See developer-facing article “Converting usethis’s UI use cli” .","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"gitgithub","dir":"","previous_headings":"","what":"Git/GitHub","title":"usethis design principles","text":"GitHub remote configs pr_*() functions accept, plus : pr_init() calls github_remote_config(github_get = NA) challenges configs “” “fork”. want work “maybe” configs, sometimes ’re offline don’t PAT credential store. come development. pr_resume() checks config (indirectly) calls choose_branch(). want able use function offline absence PAT, since main job switch branches. seems inappropriate hard check GitHub remote config. pr_pause() calls target_repo(github_get = FALSE, ask = FALSE) therefore accept “maybe” configs. Similar reasoning pr_resume(): seems like work, e.g., offline, since ’s mostly switching branches. Eventually calls pr_pull_source_override(). pr_view() gets target repo github_get = NA, works “maybe” configs. Seems low stakes enough picky. pr_fetch(), pr_pull(), pr_merge_main(), pr_finish(), require “” “fork”, via early call target_repo(github_get = TRUE) check_for_config(). probably work configs, e.g., “”, ’s worth added complexity. pr_push() requires “” “fork” , fact, gets actual config, ’s potentially used select remote push (origin upstream) user can push . need create new Git URL decide HTTPS SSH: Consult existing remotes repo, probably origin, possible Call git_protocol(), something sensible default summoning Git credentials GitHub PAT doesn’t work user, help diagnose . credential management business aren’t going offer fine control , say, level individual functions. Functions might make commit use challenge_uncommitted_changes() initial sanity-checking block encourage starting clean state, .e. uncommitted files , untracked = TRUE specified, also untracked files. allow people proceed risk. Always make commits git_commit_ask(). git_commit(), wraps gert::git_add() gert::git_commit(), defined inside git_commit_ask(). Whenever possible, specify paths git_commit_ask(). almost always possible know exactly files might touched created. need make commit noninteractive context, like test, use gert::git_commit(). Use git_uncommitted(untracked = TRUE) git_ask_commit(untracked = TRUE) ’s possible work ’ve done created new file tracked. Use untracked = FALSE work modify pre-existing file.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/badges.html","id":null,"dir":"Reference","previous_headings":"","what":"README badges — badges","title":"README badges — badges","text":"helpers produce markdown text need README include badges report information, CRAN version test coverage, link relevant external resources. add badges automatically ensure badge block starts line containing ends line containing .","code":""},{"path":"https://usethis.r-lib.org/dev/reference/badges.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"README badges — badges","text":"","code":"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)"},{"path":"https://usethis.r-lib.org/dev/reference/badges.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"README badges — badges","text":"badge_name Badge name. Used error message alt text href, src Badge link image src stage Stage package lifecycle. One \"experimental\", \"stable\", \"superseded\", \"deprecated\". ref Git branch, tag, SHA urlpath optional urlpath component add link, e.g. \"rstudio\" open RStudio IDE instead Jupyter notebook. See binder documentation additional examples. url link existing Posit Cloud project. See Posit Cloud documentation details set project access obtain project link.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/badges.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"README badges — badges","text":"use_badge(): general helper used badge functions use_bioc_badge(): badge indicates BioConductor build status use_cran_badge(): badge indicates version package available CRAN, powered https://www.r-pkg.org use_lifecycle_badge(): badge declares developmental stage package according https://lifecycle.r-lib.org/articles/stages.html. use_binder_badge(): badge indicates repository can launched executable environment https://mybinder.org/ use_posit_cloud_badge(): badge indicates repository can launched Posit Cloud project use_rscloud_badge(): : Use use_posit_cloud_badge() instead.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/badges.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"README badges — badges","text":"","code":"if (FALSE) { # \\dontrun{ use_cran_badge() use_lifecycle_badge(\"stable\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/browse-this.html","id":null,"dir":"Reference","previous_headings":"","what":"Visit important project-related web pages — browse-this","title":"Visit important project-related web pages — browse-this","text":"functions take various web pages associated project (often, R package) return target URL(s) invisibly. form URLs consult: Git remotes configured active project appear hosted GitHub deployment DESCRIPTION file active project specified package. DESCRIPTION file sought first local package library CRAN. Fixed templates: Circle CI: https://circleci.com/gh/{OWNER}/{PACKAGE} CRAN landing page: https://cran.r-project.org/package={PACKAGE} GitHub mirror CRAN package: https://github.com/cran/{PACKAGE} Templated URLs checked existence, guarantee content destination.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/browse-this.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Visit important project-related web pages — browse-this","text":"","code":"browse_package(package = NULL) browse_project() browse_github(package = NULL) browse_github_issues(package = NULL, number = NULL) browse_github_pulls(package = NULL, number = NULL) browse_github_actions(package = NULL) browse_circleci(package = NULL) browse_cran(package = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/browse-this.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Visit important project-related web pages — browse-this","text":"package Name package. NULL, active project targeted, regardless whether R package . number Optional, specify individual GitHub issue pull request. Can number \"new\".","code":""},{"path":"https://usethis.r-lib.org/dev/reference/browse-this.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Visit important project-related web pages — browse-this","text":"browse_package(): Assembles list URLs lets user choose one visit web browser. non-interactive session, returns discovered URLs. browse_project(): Thin wrapper around browse_package() always targets active usethis project. browse_github(): Visits GitHub repository associated project. case fork, might asked specify interested source repo fork. browse_github_issues(): Visits GitHub Issues index one specific issue. browse_github_pulls(): Visits GitHub Pull Request index one specific pull request. browse_circleci(): Visits project's page Circle CI. browse_cran(): Visits package CRAN, via canonical URL.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/browse-this.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Visit important project-related web pages — browse-this","text":"","code":"# works on the active project # browse_project() browse_package(\"httr\") browse_github(\"gh\") #> ☐ Open URL . browse_github_issues(\"fs\") #> ☐ Open URL . browse_github_issues(\"fs\", 1) #> ☐ Open URL . browse_github_pulls(\"curl\") #> ☐ Open URL . browse_github_pulls(\"curl\", 183) #> ☐ Open URL . browse_cran(\"MASS\") #> ☐ Open URL ."},{"path":"https://usethis.r-lib.org/dev/reference/create_from_github.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a project from a GitHub repo — create_from_github","title":"Create a project from a GitHub repo — create_from_github","text":"Creates new local project Git repository repo GitHub, either cloning fork--cloning. fork--clone case, create_from_github() also additional remote branch setup, leaving perfect position make pull request pr_init(), one several functions working pull requests. create_from_github() works best GitHub credentials discoverable. See authentication.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/create_from_github.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a project from a GitHub repo — create_from_github","text":"","code":"create_from_github( repo_spec, destdir = NULL, fork = NA, rstudio = NULL, open = rlang::is_interactive(), protocol = git_protocol(), host = NULL )"},{"path":"https://usethis.r-lib.org/dev/reference/create_from_github.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a project from a GitHub repo — create_from_github","text":"repo_spec string identifying GitHub repo one forms: Plain OWNER/REPO spec Browser URL, \"https://github.com/OWNER/REPO\" HTTPS Git URL, \"https://github.com/OWNER/REPO.git\" SSH Git URL, \"git@github.com:OWNER/REPO.git\" destdir Destination new folder, named according REPO extracted repo_spec. Defaults location stored global option usethis.destdir, defined, user's Desktop similarly conspicuous place otherwise. fork FALSE, clone repo_spec. TRUE, fork repo_spec, clone fork, additional setup favorable future pull requests: source repo, repo_spec, configured upstream remote, using indicated protocol. local DEFAULT branch set track upstream/DEFAULT, DEFAULT typically main master. also immediately pulled, cover case pre-existing, --date fork. fork = NA (default), check permissions repo_spec. can push, set fork = FALSE, , set fork = TRUE. rstudio Initiate RStudio Project? Defaults TRUE RStudio session project pre-existing .Rproj file. Defaults FALSE otherwise (note cloned repo may already RStudio Project, .e. may already .Rproj file). open TRUE, activates new project: using RStudio desktop, package opened new session. RStudio server, current RStudio project activated. Otherwise, working directory active project changed. protocol One \"https\" \"ssh\" host GitHub host target, passed .api_url argument gh::gh(). repo_spec URL, host extracted . unspecified, gh defaults \"https://api.github.com\", although gh's default can customised setting GITHUB_API_URL environment variable. hypothetical GitHub Enterprise instance, either \"https://github.acme.com/api/v3\" \"https://github.acme.com\" acceptable.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/create_from_github.html","id":"git-github-authentication","dir":"Reference","previous_headings":"","what":"Git/GitHub Authentication","title":"Create a project from a GitHub repo — create_from_github","text":"Many usethis functions, including documented , potentially interact GitHub two different ways: Via GitHub REST API. Examples: create repo, fork, pull request. conventional Git remote. Examples: clone, fetch, push. Therefore two types auth can happen credentials must discoverable. credentials mean? GitHub personal access token (PAT) must discoverable gh package, used GitHub operations via REST API. See gh_token_help() getting configuring PAT. use HTTPS protocol Git remotes, PAT also used Git operations, git push. Usethis uses gert package , PAT must discoverable gert. Generally gert gh discover use PAT. ability \"kill two birds one stone\" HTTPS + PAT recommended auth strategy new Git GitHub PRs. use SSH remotes, SSH keys must also discoverable, addition PAT. public key must added GitHub account. Git/GitHub credential management covered dedicated article: Managing Git(Hub) Credentials","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/create_from_github.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create a project from a GitHub repo — create_from_github","text":"","code":"if (FALSE) { # \\dontrun{ create_from_github(\"r-lib/usethis\") # repo_spec can be a URL create_from_github(\"https://github.com/r-lib/usethis\") # a URL repo_spec also specifies the host (e.g. GitHub Enterprise instance) create_from_github(\"https://github.acme.com/OWNER/REPO\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/create_package.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a package or project — create_package","title":"Create a package or project — create_package","text":"functions create R project: create_package() creates R package create_project() creates non-package project, .e. data analysis project functions can called existing project; asked existing files changed.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/create_package.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a package or project — create_package","text":"","code":"create_package( path, fields = list(), rstudio = rstudioapi::isAvailable(), roxygen = TRUE, check_name = TRUE, open = rlang::is_interactive() ) create_project( path, rstudio = rstudioapi::isAvailable(), open = rlang::is_interactive() )"},{"path":"https://usethis.r-lib.org/dev/reference/create_package.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a package or project — create_package","text":"path path. exists, used. exist, created, provided parent path exists. fields named list fields add DESCRIPTION, potentially overriding default values. See use_description() can set personalized defaults using package options. rstudio TRUE, calls use_rstudio() make new package project RStudio Project. FALSE non-package project, sentinel .file placed directory can recognized project rprojroot packages. roxygen plan use roxygen2 document package? check_name Whether check name valid CRAN throw error . open TRUE, activates new project: using RStudio desktop, package opened new session. RStudio server, current RStudio project activated. Otherwise, working directory active project changed.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/create_package.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create a package or project — create_package","text":"Path newly created project package, invisibly.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/edit.html","id":null,"dir":"Reference","previous_headings":"","what":"Open configuration files — edit","title":"Open configuration files — edit","text":"edit_r_profile() opens .Rprofile edit_r_environ() opens .Renviron edit_r_makevars() opens .R/Makevars edit_git_config() opens .gitconfig .git/config edit_git_ignore() opens global (user-level) gitignore file ensures path declared global Git config. edit_pkgdown_config opens pkgdown YAML configuration file current Project. edit_rstudio_snippets() opens RStudio's snippet config given type. edit_rstudio_prefs() opens RStudio's preference file.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/edit.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Open configuration files — edit","text":"","code":"edit_r_profile(scope = c(\"user\", \"project\")) edit_r_environ(scope = c(\"user\", \"project\")) edit_r_buildignore() edit_r_makevars(scope = c(\"user\", \"project\")) edit_rstudio_snippets( type = c(\"r\", \"markdown\", \"c_cpp\", \"css\", \"html\", \"java\", \"javascript\", \"python\", \"sql\", \"stan\", \"tex\", \"yaml\") ) edit_rstudio_prefs() edit_git_config(scope = c(\"user\", \"project\")) edit_git_ignore(scope = c(\"user\", \"project\")) edit_pkgdown_config()"},{"path":"https://usethis.r-lib.org/dev/reference/edit.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Open configuration files — edit","text":"scope Edit globally current user, locally current project type Snippet type (case insensitive text).","code":""},{"path":"https://usethis.r-lib.org/dev/reference/edit.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Open configuration files — edit","text":"Path file, invisibly.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/edit.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Open configuration files — edit","text":"edit_r_*() functions consult R's notion user's home directory. edit_git_*() functions (usethis general) inherit home directory behaviour fs package, differs R Windows. fs default conventional terms location user-level Git config files. See fs::path_home() details. Files created edit_rstudio_snippets() mask, supplement, built-default snippets. like built-snippets, copy include custom snippets.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/edit_file.html","id":null,"dir":"Reference","previous_headings":"","what":"Open file for editing — edit_file","title":"Open file for editing — edit_file","text":"Opens file editing RStudio, active environment, via utils::file.edit() otherwise. file exist, created. parent directory exist, also created. edit_template() specifically opens templates inst/templates use use_template().","code":""},{"path":"https://usethis.r-lib.org/dev/reference/edit_file.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Open file for editing — edit_file","text":"","code":"edit_file(path, open = rlang::is_interactive()) edit_template(template = NULL, open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/edit_file.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Open file for editing — edit_file","text":"path Path target file. open Whether open file interactive editing. template target template file. specified, existing template files offered interactive selection.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/edit_file.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Open file for editing — edit_file","text":"Target path, invisibly.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/edit_file.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Open file for editing — edit_file","text":"","code":"if (FALSE) { # \\dontrun{ edit_file(\"DESCRIPTION\") edit_file(\"~/.gitconfig\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":null,"dir":"Reference","previous_headings":"","what":"Get or set the default Git branch — git-default-branch","title":"Get or set the default Git branch — git-default-branch","text":"git_default_branch*() functions put structure around somewhat fuzzy (definitely real) concept default branch. particular, support new conventions around Git default branch name, globally specific project / Git repository.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Get or set the default Git branch — git-default-branch","text":"","code":"git_default_branch() git_default_branch_configure(name = \"main\") git_default_branch_rediscover(current_local_default = NULL) git_default_branch_rename(from = NULL, to = \"main\")"},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Get or set the default Git branch — git-default-branch","text":"name Default name initial branch new Git repositories. current_local_default Name local branch currently functioning default branch. unspecified, can often inferred. Name branch currently functioning default branch. New name default branch.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Get or set the default Git branch — git-default-branch","text":"Name default branch.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"background-on-the-default-branch","dir":"Reference","previous_headings":"","what":"Background on the default branch","title":"Get or set the default Git branch — git-default-branch","text":"Technically, Git official concept default branch. reality, almost Git repos effective default branch. one branch, ! branch bug fixes features get merged . branch see first visit repo site GitHub. Git remote, branch HEAD points . Historically, master common name default branch, main increasingly popular choice.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"git-default-branch-configure-","dir":"Reference","previous_headings":"","what":"git_default_branch_configure()","title":"Get or set the default Git branch — git-default-branch","text":"configures init.defaultBranch global (.k.user) level. setting determines name branch gets created make first commit new Git repo. init.defaultBranch affects local Git repos create future.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"git-default-branch-","dir":"Reference","previous_headings":"","what":"git_default_branch()","title":"Get or set the default Git branch — git-default-branch","text":"figures default branch current Git repo, integrating information local repo , applicable, upstream origin remote. local vs. remote mismatch, git_default_branch() throws error advice call git_default_branch_rediscover() repair situation. remote repo, default branch branch HEAD points . local repo, one branch, must default! Otherwise try identify relevant local branch looking specific branch names, order: whatever default branch upstream origin , applicable main master value Git option init.defaultBranch, usual deal local value, present, takes precedence global (.k.. user-level) value","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"git-default-branch-rediscover-","dir":"Reference","previous_headings":"","what":"git_default_branch_rediscover()","title":"Get or set the default Git branch — git-default-branch","text":"consults external authority – specifically, remote source repo GitHub – learn default branch current project / repo. match apparent local default branch (example, project switched master main), corresponding branch renaming local repo , relevant, fork. See https://happygitwithr.com/common-remote-setups.html GitHub remote configurations , e.g., mean source repo. function works configurations \"\", \"fork\", \"\".","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"git-default-branch-rename-","dir":"Reference","previous_headings":"","what":"git_default_branch_rename()","title":"Get or set the default Git branch — git-default-branch","text":"Note: works repo effectively . terms GitHub, must source repo personally , organization-owned, must admin permission source repo. renames default branch source repo GitHub calls git_default_branch_rediscover(), make necessary changes local repo , relevant, personal fork. See https://happygitwithr.com/common-remote-setups.html GitHub remote configurations , e.g., mean source repo. function works configurations \"\", \"fork\", \"no_github\". Regarding \"no_github\": course, function expect local repo GitHub remotes, primary use case.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Get or set the default Git branch — git-default-branch","text":"","code":"if (FALSE) { # \\dontrun{ git_default_branch() } # } if (FALSE) { # \\dontrun{ git_default_branch_configure() } # } if (FALSE) { # \\dontrun{ git_default_branch_rediscover() # you can always explicitly specify the local branch that's been playing the # role of the default git_default_branch_rediscover(\"unconventional_default_branch_name\") } # } if (FALSE) { # \\dontrun{ git_default_branch_rename() # you can always explicitly specify one or both branch names git_default_branch_rename(from = \"this\", to = \"that\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/git_branch_default.html","id":null,"dir":"Reference","previous_headings":"","what":"Deprecated Git functions — git_branch_default","title":"Deprecated Git functions — git_branch_default","text":"git_branch_default() replaced git_default_branch().","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git_branch_default.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Deprecated Git functions — git_branch_default","text":"","code":"git_branch_default()"},{"path":"https://usethis.r-lib.org/dev/reference/git_protocol.html","id":null,"dir":"Reference","previous_headings":"","what":"See or set the default Git protocol — git_protocol","title":"See or set the default Git protocol — git_protocol","text":"Git operations address remote use -called \"transport protocol\". usethis supports HTTPS SSH. protocol dictates Git URL format used usethis needs configure first GitHub remote repo: protocol = \"https\" implies https://github.com//.git protocol = \"ssh\" implies git@github.com:/.git Two helper functions available: git_protocol() reveals protocol \"force\". usethis v2.0.0, defaults \"https\". can change duration R session use_git_protocol(). Change default R sessions code like .Rprofile (easily editable via edit_r_profile()): use_git_protocol() sets Git protocol current R session protocol affects Git URL newly configured remotes. existing Git remote URLs always respected, whether HTTPS SSH.","code":"options(usethis.protocol = \"ssh\")"},{"path":"https://usethis.r-lib.org/dev/reference/git_protocol.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"See or set the default Git protocol — git_protocol","text":"","code":"git_protocol() use_git_protocol(protocol)"},{"path":"https://usethis.r-lib.org/dev/reference/git_protocol.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"See or set the default Git protocol — git_protocol","text":"protocol One \"https\" \"ssh\"","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git_protocol.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"See or set the default Git protocol — git_protocol","text":"protocol, either \"https\" \"ssh\"","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git_protocol.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"See or set the default Git protocol — git_protocol","text":"","code":"if (FALSE) { # \\dontrun{ git_protocol() use_git_protocol(\"ssh\") git_protocol() use_git_protocol(\"https\") git_protocol() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/git_sitrep.html","id":null,"dir":"Reference","previous_headings":"","what":"Git/GitHub sitrep — git_sitrep","title":"Git/GitHub sitrep — git_sitrep","text":"Get situation report current Git/GitHub status. Useful diagnosing problems. default report values; provide values tool scope specific.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git_sitrep.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Git/GitHub sitrep — git_sitrep","text":"","code":"git_sitrep(tool = c(\"git\", \"github\"), scope = c(\"user\", \"project\"))"},{"path":"https://usethis.r-lib.org/dev/reference/git_sitrep.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Git/GitHub sitrep — git_sitrep","text":"tool Report git, github scope Report globally current user, locally current project","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git_sitrep.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Git/GitHub sitrep — git_sitrep","text":"","code":"if (FALSE) { # \\dontrun{ # report all git_sitrep() # report git for current user git_sitrep(\"git\", \"user\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/git_vaccinate.html","id":null,"dir":"Reference","previous_headings":"","what":"Vaccinate your global gitignore file — git_vaccinate","title":"Vaccinate your global gitignore file — git_vaccinate","text":"Adds .Rproj.user, .Rhistory, .Rdata, .httr-oauth, .DS_Store, .quarto global (.k.. user-level) .gitignore. good practice decreases chance accidentally leak credentials GitHub. git_vaccinate() also tries detect fix situation global gitignore file, missing global Git config.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git_vaccinate.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Vaccinate your global gitignore file — git_vaccinate","text":"","code":"git_vaccinate()"},{"path":"https://usethis.r-lib.org/dev/reference/github-token.html","id":null,"dir":"Reference","previous_headings":"","what":"Get help with GitHub personal access tokens — github-token","title":"Get help with GitHub personal access tokens — github-token","text":"personal access token (PAT) needed certain tasks usethis via GitHub API, creating repository, fork, pull request. use HTTPS remotes, PAT also used interacting GitHub conventional Git remote. functions help get manage PAT: gh_token_help() guides token troubleshooting setup. create_github_token() opens browser window GitHub form generate PAT, suggested scopes pre-selected. also offers advice storing PAT. gitcreds::gitcreds_set() helps register PAT Git credential manager used operating system. Later, packages, usethis, gert, gh can automatically retrieve PAT use work GitHub behalf. Usually, first time PAT retrieved R session, cached environment variable, easier reuse duration R session. initial acquisition storage, happen automatically background. GitHub encouraging use PATs expire , e.g., 30 days, prepare re-generate re-store PAT periodically. Git/GitHub credential management covered dedicated article: Managing Git(Hub) Credentials","code":""},{"path":"https://usethis.r-lib.org/dev/reference/github-token.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Get help with GitHub personal access tokens — github-token","text":"","code":"create_github_token( scopes = c(\"repo\", \"user\", \"gist\", \"workflow\"), description = \"DESCRIBE THE TOKEN'S USE CASE\", host = NULL ) gh_token_help(host = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/github-token.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Get help with GitHub personal access tokens — github-token","text":"scopes Character vector token scopes, pre-selected web form. Final choices made GitHub form. Read GitHub API scopes https://docs.github.com/apps/building-oauth-apps/understanding-scopes--oauth-apps/. description Short description nickname token. might (eventually) multiple tokens GitHub account label can help keep track token . host GitHub host target, passed .api_url argument gh::gh(). unspecified, gh defaults \"https://api.github.com\", although gh's default can customised setting GITHUB_API_URL environment variable. hypothetical GitHub Enterprise instance, either \"https://github.acme.com/api/v3\" \"https://github.acme.com\" acceptable.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/github-token.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Get help with GitHub personal access tokens — github-token","text":"Nothing","code":""},{"path":"https://usethis.r-lib.org/dev/reference/github-token.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Get help with GitHub personal access tokens — github-token","text":"create_github_token() previously gone names: browse_github_token() browse_github_pat().","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/github-token.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Get help with GitHub personal access tokens — github-token","text":"","code":"if (FALSE) { # \\dontrun{ create_github_token() } # } if (FALSE) { # \\dontrun{ gh_token_help() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/issue-this.html","id":null,"dir":"Reference","previous_headings":"","what":"Helpers for GitHub issues — issue-this","title":"Helpers for GitHub issues — issue-this","text":"issue_* family functions allows perform common operations GitHub issues within R. designed help efficiently deal large numbers issues, particularly motivated challenges faced tidyverse team. issue_close_community() closes issue, bug report feature request, points author towards Posit Community better place discuss usage (https://forum.posit.co). issue_reprex_needed() labels issue \"reprex\" label gives author advice needed.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/issue-this.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Helpers for GitHub issues — issue-this","text":"","code":"issue_close_community(number, reprex = FALSE) issue_reprex_needed(number)"},{"path":"https://usethis.r-lib.org/dev/reference/issue-this.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Helpers for GitHub issues — issue-this","text":"number Issue number reprex issue also need reprex?","code":""},{"path":"https://usethis.r-lib.org/dev/reference/issue-this.html","id":"saved-replies","dir":"Reference","previous_headings":"","what":"Saved replies","title":"Helpers for GitHub issues — issue-this","text":"Unlike GitHub's \"saved replies\", functions can: shared people Perform actions, like labelling, closing additional arguments Include randomness (like friendly gifs)","code":""},{"path":"https://usethis.r-lib.org/dev/reference/issue-this.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Helpers for GitHub issues — issue-this","text":"","code":"if (FALSE) { # \\dontrun{ issue_close_community(12, reprex = TRUE) issue_reprex_needed(241) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/licenses.html","id":null,"dir":"Reference","previous_headings":"","what":"License a package — licenses","title":"License a package — licenses","text":"Adds necessary infrastructure declare package licensed one popular open source licenses: Permissive: MIT: simple permissive. Apache 2.0: MIT + provides patent protection. Copyleft: GPL v2: requires sharing improvements. GPL v3: requires sharing improvements. AGPL v3: requires sharing improvements. LGPL v2.1: requires sharing improvements. LGPL v3: requires sharing improvements. Creative commons licenses appropriate data packages: CC0: dedicated public domain. CC-: Free share adapt, must give appropriate credit. See https://choosealicense.com details options. Alternatively, code want share others, use_proprietary_license() makes clear rights reserved, code open source.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/licenses.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"License a package — licenses","text":"","code":"use_mit_license(copyright_holder = NULL) use_gpl_license(version = 3, include_future = TRUE) use_agpl_license(version = 3, include_future = TRUE) use_lgpl_license(version = 3, include_future = TRUE) use_apache_license(version = 2, include_future = TRUE) use_cc0_license() use_ccby_license() use_proprietary_license(copyright_holder)"},{"path":"https://usethis.r-lib.org/dev/reference/licenses.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"License a package — licenses","text":"copyright_holder Name copyright holder holders. defaults \"{package name} authors\"; change use CLA assign copyright single entity. version License version. defaults latest version licenses. include_future TRUE, license package current potential future versions license. generally considered good practice means package automatically include \"bug\" fixes licenses.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/licenses.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"License a package — licenses","text":"CRAN permit include copies standard licenses package, functions save license LICENSE.md add .Rbuildignore.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/proj_activate.html","id":null,"dir":"Reference","previous_headings":"","what":"Activate a project — proj_activate","title":"Activate a project — proj_activate","text":"Activates project usethis, R session, (relevant) RStudio senses. RStudio, open new RStudio session. , change working directory active project.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/proj_activate.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Activate a project — proj_activate","text":"","code":"proj_activate(path)"},{"path":"https://usethis.r-lib.org/dev/reference/proj_activate.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Activate a project — proj_activate","text":"path Project directory","code":""},{"path":"https://usethis.r-lib.org/dev/reference/proj_activate.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Activate a project — proj_activate","text":"Single logical value indicating current session modified.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/proj_sitrep.html","id":null,"dir":"Reference","previous_headings":"","what":"Report working directory and usethis/RStudio project — proj_sitrep","title":"Report working directory and usethis/RStudio project — proj_sitrep","text":"proj_sitrep() reports current working directory active usethis project active RStudio Project Call function things seem weird sure wrong fix . Usually, three coincide (unset) proj_sitrep() provides suggested commands getting back happy state.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/proj_sitrep.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Report working directory and usethis/RStudio project — proj_sitrep","text":"","code":"proj_sitrep()"},{"path":"https://usethis.r-lib.org/dev/reference/proj_sitrep.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Report working directory and usethis/RStudio project — proj_sitrep","text":"named list, S3 class sitrep (printing purposes), reporting current working directory, active usethis project, active RStudio Project","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/proj_sitrep.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Report working directory and usethis/RStudio project — proj_sitrep","text":"","code":"proj_sitrep() #> • working_directory: #> \"/home/runner/work/usethis/usethis/docs/dev/reference\" #> • active_usethis_proj: #> • active_rstudio_proj: #> ℹ There is currently no active usethis project. #> ℹ usethis attempts to activate a project upon first need. #> ☐ Call `usethis::proj_get()` to initiate project discovery. #> ☐ Call `proj_set(\"path/to/project\")` or #> `proj_activate(\"path/to/project\")` to provide an explicit path."},{"path":"https://usethis.r-lib.org/dev/reference/proj_utils.html","id":null,"dir":"Reference","previous_headings":"","what":"Utility functions for the active project — proj_utils","title":"Utility functions for the active project — proj_utils","text":"use_*() functions act active project. unset, usethis uses rprojroot find project root current working directory. establishes project root looking .file, RStudio Project, package DESCRIPTION, Git infrastructure, remake.yml file, .projectile file. stores active project use remainder session. general, end user scripts contain direct calls usethis::proj_*() utility functions. internal functions exported occasional interactive use use packages extend usethis. End user code call functions rprojroot simpler companion, , programmatically detect project build paths within . puzzled path (usually current working directory) appear inside project, can helpful call ::dr_here() get much verbose feedback.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/proj_utils.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Utility functions for the active project — proj_utils","text":"","code":"proj_get() proj_set(path = \".\", force = FALSE) proj_path(..., ext = \"\") with_project( path = \".\", code, force = FALSE, setwd = TRUE, quiet = getOption(\"usethis.quiet\", default = FALSE) ) local_project( path = \".\", force = FALSE, setwd = TRUE, quiet = getOption(\"usethis.quiet\", default = FALSE), .local_envir = parent.frame() )"},{"path":"https://usethis.r-lib.org/dev/reference/proj_utils.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Utility functions for the active project — proj_utils","text":"path Path set. path exist NULL. force TRUE, use path without checking usual criteria project. Use sparingly! main application solve temporary chicken-egg problem: need set active project order add project-signalling infrastructure, initialising Git repo adding DESCRIPTION file. ... character vectors, values NA, result also NA. paths follow recycling rules used tibble package, namely length 1 arguments recycled. ext optional extension append generated path. code Code run temporary active project setwd Whether also temporarily set working directory active project, NULL quiet Whether suppress user-facing messages, operating temporary active project .local_envir environment use scoping. Defaults current execution environment.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/proj_utils.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Utility functions for the active project — proj_utils","text":"proj_get(): Retrieves active project , necessary, attempts set first place. proj_set(): Sets active project. proj_path(): Builds paths within active project returned proj_get(). Thin wrapper around fs::path(). with_project(): Runs code temporary active project , optionally, working directory. example with_*() functions withr. local_project(): Sets active project , optionally, working directory current execution environment goes scope, e.g. end current function test. example local_*() functions withr.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/proj_utils.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Utility functions for the active project — proj_utils","text":"","code":"if (FALSE) { # \\dontrun{ ## see the active project proj_get() ## manually set the active project proj_set(\"path/to/target/project\") ## build a path within the active project (both produce same result) proj_path(\"R/foo.R\") proj_path(\"R\", \"foo\", ext = \"R\") ## build a path within SOME OTHER project with_project(\"path/to/some/other/project\", proj_path(\"blah.R\")) ## convince yourself that with_project() temporarily changes the project with_project(\"path/to/some/other/project\", print(proj_sitrep())) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":null,"dir":"Reference","previous_headings":"","what":"Helpers for GitHub pull requests — pull-requests","title":"Helpers for GitHub pull requests — pull-requests","text":"pr_* family functions designed make working GitHub pull requests (PRs) painless possible contributors package maintainers. use pr_* functions, project must Git repo one GitHub remote configurations: \"\": can push GitHub remote configured origin fork. \"fork\": can push GitHub remote configured origin, fork, parent configured upstream. origin points personal copy upstream points source repo. \"\" \"fork\" two several GitHub remote configurations examined Common remote setups Happy Git GitHub useR. Pull Request Helpers article walks process making pull request pr_* functions. pr_* functions also use Git/GitHub credentials carry various remote operations; see auth. pr_* functions also proactively check agreement re: default branch local repo source repo. See git_default_branch() .","code":""},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Helpers for GitHub pull requests — pull-requests","text":"","code":"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()"},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Helpers for GitHub pull requests — pull-requests","text":"branch Name new existing local branch. creating new branch, note usually consist lower case letters, numbers, -. number Number PR. target repo target? question case fork. fork, slim chance want consider pull requests fork (primary repo, .e. origin) instead source repo (.e. upstream, default).","code":""},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":"git-github-authentication","dir":"Reference","previous_headings":"","what":"Git/GitHub Authentication","title":"Helpers for GitHub pull requests — pull-requests","text":"Many usethis functions, including documented , potentially interact GitHub two different ways: Via GitHub REST API. Examples: create repo, fork, pull request. conventional Git remote. Examples: clone, fetch, push. Therefore two types auth can happen credentials must discoverable. credentials mean? GitHub personal access token (PAT) must discoverable gh package, used GitHub operations via REST API. See gh_token_help() getting configuring PAT. use HTTPS protocol Git remotes, PAT also used Git operations, git push. Usethis uses gert package , PAT must discoverable gert. Generally gert gh discover use PAT. ability \"kill two birds one stone\" HTTPS + PAT recommended auth strategy new Git GitHub PRs. use SSH remotes, SSH keys must also discoverable, addition PAT. public key must added GitHub account. Git/GitHub credential management covered dedicated article: Managing Git(Hub) Credentials","code":""},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":"for-contributors","dir":"Reference","previous_headings":"","what":"For contributors","title":"Helpers for GitHub pull requests — pull-requests","text":"contribute package, first use create_from_github(\"OWNER/REPO\"). forks source repository checks local copy. Next use pr_init() create branch PR. best practice never make commits default branch branch fork (usually named main master), . pull request always come feature branch. much easier pull upstream changes fork parent allow work feature branches. also much easier maintainer explore extend PR create feature branch. Work locally, branch, making changes files, committing work. ready create PR, run pr_push() push local branch GitHub, open webpage lets initiate PR (draft PR). learn process making pull request, read Pull Request Helpers vignette. lucky, PR perfect, maintainer accept . can run pr_finish() delete PR branch. cases, however, maintainer ask make changes. Make changes, run pr_push() update PR. also possible maintainer contribute code PR: get changes back onto computer, run pr_pull(). can also happen changes occurred package since first created PR. might need merge default branch (usually named main master) PR branch. running pr_merge_main(): makes sure PR compatible primary repo's main line development. pr_pull() pr_merge_main() can result merge conflicts, prepared resolve continuing.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":"for-maintainers","dir":"Reference","previous_headings":"","what":"For maintainers","title":"Helpers for GitHub pull requests — pull-requests","text":"download PR locally can experiment , run pr_fetch() select PR , already know number, call pr_fetch(). make changes, run pr_push() push back GitHub. merged PR, run pr_finish() delete local branch remove remote associated contributor's fork.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":"overview-of-all-the-functions","dir":"Reference","previous_headings":"","what":"Overview of all the functions","title":"Helpers for GitHub pull requests — pull-requests","text":"pr_init(): contributor, start work new PR ensuring local repo --date, creating checking new branch. Nothing pushed created GitHub call pr_push(). pr_fetch(): maintainer, review contribute changes existing PR creating local branch tracks remote PR. pr_fetch() little work possible, can also use resume work PR already local branch (also ensure local branch --date). called arguments, 9 open PRs offered interactive selection. pr_resume(): Resume work PR switching existing local branch pulling changes upstream tracking branch, one. called arguments, 9 local branches offered interactive selection, preference branches connected PRs branches recent activity. pr_push(): first time called, PR branch pushed GitHub taken webpage new PR (draft PR) can created. also sets local branch track remote counterpart. Subsequent calls pr_push() make sure local branch remote changes , , pushes local changes, thereby updating PR. pr_pull(): Pulls changes local branch's remote tracking branch. maintainer extended PR, bring changes back local work. pr_merge_main(): Pulls changes default branch source repo current local branch. can used local branch default branch PR branch. pr_pause(): Makes sure --date remote changes PR. switches back default branch pulls source repo. Use pr_resume() name branch use pr_fetch() resume using PR number. pr_view(): Visits PR associated current branch browser (default) specific PR identified number. (FYI browse_github_pulls() handy way visit list PRs current project.) pr_forget(): local clean current branch actual notional PR want abandon. Maybe initiated , via pr_init(), used pr_fetch() explore PR GitHub. local operations: update delete remote branches, close PRs. Alerts user uncommitted unpushed work risk lost. user chooses proceed, switches back default branch, pulls changes source repo, deletes local PR branch. associated Git remote deleted, \"forgotten\" PR branch using . pr_finish(): post-PR clean , actually merge close PR (maintainer browser). number given, infers PR upstream tracking branch current branch. number given, matter whether PR exists locally. PR exists locally, alerts user uncommitted unpushed changes, switches back default branch, pulls changes source repo, deletes local PR branch. PR came external fork, associated Git remote deleted, provided use local branches. PR merged user permission, deletes remote branch (remote operation pr_finish() potentially ).","code":""},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Helpers for GitHub pull requests — pull-requests","text":"","code":"if (FALSE) { # \\dontrun{ pr_fetch(123) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/rename_files.html","id":null,"dir":"Reference","previous_headings":"","what":"Automatically rename paired R/ and test/ files — rename_files","title":"Automatically rename paired R/ and test/ files — rename_files","text":"Moves R/{old}.R R/{new}.R Moves src/{old}.* src/{new}.* Moves tests/testthat/test-{old}.R tests/testthat/test-{new}.R Moves tests/testthat/test-{old}-*.* tests/testthat/test-{new}-*.* updates paths test file. Removes context() calls test file, unnecessary (discouraged) testthat v2.1.0. potentially dangerous operation, must using Git order use function.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/rename_files.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Automatically rename paired R/ and test/ files — rename_files","text":"","code":"rename_files(old, new)"},{"path":"https://usethis.r-lib.org/dev/reference/rename_files.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Automatically rename paired R/ and test/ files — rename_files","text":"old, new Old new file names (without .R extensions).","code":""},{"path":"https://usethis.r-lib.org/dev/reference/rprofile-helper.html","id":null,"dir":"Reference","previous_headings":"","what":"Helpers to make useful changes to .Rprofile — rprofile-helper","title":"Helpers to make useful changes to .Rprofile — rprofile-helper","text":"functions open .Rprofile give code need paste . use_devtools(): makes devtools available interactive sessions. use_usethis(): makes usethis available interactive sessions. use_reprex(): makes reprex available interactive sessions. use_conflicted(): makes conflicted available interactive sessions. use_partial_warnings(): warns partial matches.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/rprofile-helper.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Helpers to make useful changes to .Rprofile — rprofile-helper","text":"","code":"use_conflicted() use_reprex() use_usethis() use_devtools() use_partial_warnings()"},{"path":"https://usethis.r-lib.org/dev/reference/tidyverse.html","id":null,"dir":"Reference","previous_headings":"","what":"Helpers for tidyverse development — use_tidy_github_actions","title":"Helpers for tidyverse development — use_tidy_github_actions","text":"helpers follow tidyverse conventions generally little stricter defaults, reflecting need greater rigor commonly used packages.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/tidyverse.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Helpers for tidyverse development — use_tidy_github_actions","text":"","code":"use_tidy_github_actions(ref = NULL) create_tidy_package(path, copyright_holder = NULL) use_tidy_description() use_tidy_dependencies() use_tidy_contributing() use_tidy_support() use_tidy_issue_template() use_tidy_coc() use_tidy_github() use_tidy_style(strict = TRUE) use_tidy_logo(geometry = \"240x278\", retina = TRUE) use_tidy_upkeep_issue(year = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/tidyverse.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Helpers for tidyverse development — use_tidy_github_actions","text":"ref Desired Git reference, usually name tag (\"v2\") branch (\"main\"). possibilities include commit SHA (\"d1c516d\") \"HEAD\" (meaning \"tip remote's default branch\"). specified, defaults latest published release r-lib/actions (https://github.com/r-lib/actions/releases). path path. exists, used. exist, created, provided parent path exists. copyright_holder Name copyright holder holders. defaults \"{package name} authors\"; change use CLA assign copyright single entity. strict Boolean indicating whether strict version styling applied. See styler::tidyverse_style() details. geometry magick::geometry string specifying size. default assumes hex logo using spec http://hexb./sticker.html. retina TRUE, default, scales image README, assuming geometry double desired size. year Approximate year last touched package. NULL, default, give full set actions perform.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/tidyverse.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Helpers for tidyverse development — use_tidy_github_actions","text":"use_tidy_github_actions(): Sets following workflows using GitHub Actions: Run R CMD check current release, devel, four previous versions R. build matrix also ensures R CMD check run least three major operating systems (Linux, macOS, Windows). Report test coverage. Build deploy pkgdown site. Provide two commands used pull requests: /document run roxygen2::roxygenise() update PR, /style run styler::style_pkg() update PR. tidyverse team checks packages, overkill less widely used packages. Consider using streamlined workflows set use_github_actions() use_github_action_check_standard(). create_tidy_package(): creates new package, immediately applies many tidyverse conventions possible, issues reminders, activates new package. use_tidy_dependencies(): sets standard dependencies used tidyverse packages (except packages designed dependency free). use_tidy_description(): puts fields standard order alphabetises dependencies. use_tidy_eval(): imports standard set helpers facilitate programming tidy eval toolkit. use_tidy_style(): styles source code according tidyverse style guide. function overwrite files! See usage advice. use_tidy_contributing(): adds standard tidyverse contributing guidelines. use_tidy_issue_template(): adds standard tidyverse issue template. use_tidy_release_test_env(): updates test environment section cran-comments.md. use_tidy_support(): adds standard description support resources tidyverse. use_tidy_coc(): equivalent use_code_of_conduct(), puts document .github/ subdirectory. use_tidy_github(): convenience wrapper calls use_tidy_contributing(), use_tidy_issue_template(), use_tidy_support(), use_tidy_coc(). use_tidy_github_labels() calls use_github_labels() implement tidyverse conventions around GitHub issue label names colours. use_tidy_upkeep_issue() creates issue containing checklist actions bring package current tidyverse standards. use_tidy_logo() calls use_logo() appropriate hex sticker PNG file https://github.com/rstudio/hex-stickers.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/tidyverse.html","id":"use-tidy-style-","dir":"Reference","previous_headings":"","what":"use_tidy_style()","title":"Helpers for tidyverse development — use_tidy_github_actions","text":"Uses styler package package style code package, project, directory, according tidyverse style guide. Warning: function overwrite files! strongly suggested style files version control first create backup copy. Invisibly returns data frame one row per file, indicates whether styling caused change.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-legacy-functions.html","id":null,"dir":"Reference","previous_headings":"","what":"Legacy functions related to user interface — ui-legacy-functions","title":"Legacy functions related to user interface — ui-legacy-functions","text":"functions now superseded. External users usethis::ui_*() functions encouraged use cli package instead. cli package required functionality usethis::ui_*() functions created, now superior option. even cli vignette make transition: vignette(\"usethis-ui\", package = \"cli\"). usethis now uses cli internally UI, new functions exported presumably never . developer-focused article process transitioning usethis's UI use cli: Converting usethis's UI use cli.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-legacy-functions.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Legacy functions related to user interface — ui-legacy-functions","text":"","code":"ui_line(x = character(), .envir = parent.frame()) ui_todo(x, .envir = parent.frame()) ui_done(x, .envir = parent.frame()) ui_oops(x, .envir = parent.frame()) ui_info(x, .envir = parent.frame()) ui_code_block(x, copy = rlang::is_interactive(), .envir = parent.frame()) ui_stop(x, .envir = parent.frame()) ui_warn(x, .envir = parent.frame()) ui_field(x) ui_value(x) ui_path(x, base = NULL) ui_code(x) ui_unset(x = \"unset\")"},{"path":"https://usethis.r-lib.org/dev/reference/ui-legacy-functions.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Legacy functions related to user interface — ui-legacy-functions","text":"x character vector. block styles, conditions, questions, element vector becomes line, result processed glue::glue(). inline styles, element vector becomes entry comma separated list. .envir Used ensure glue::glue() gets correct environment. expert use . copy TRUE, session interactive, clipr package installed, copy code block clipboard. base specified, paths displayed relative path.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-legacy-functions.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Legacy functions related to user interface — ui-legacy-functions","text":"block styles, conditions, questions called side-effect. inline styles return string.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-legacy-functions.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Legacy functions related to user interface — ui-legacy-functions","text":"ui_ functions can broken four main categories: block styles: ui_line(), ui_done(), ui_todo(), ui_oops(), ui_info(). conditions: ui_stop(), ui_warn(). questions: ui_yeah(), ui_nope(). inline styles: ui_field(), ui_value(), ui_path(), ui_code(), ui_unset(). question functions ui_yeah() ui_nope() help page. UI output (apart ui_yeah()/ui_nope() prompts) can silenced setting options(usethis.quiet = TRUE). Use ui_silence() silence selected actions.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-legacy-functions.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Legacy functions related to user interface — ui-legacy-functions","text":"","code":"new_val <- \"oxnard\" ui_done(\"{ui_field('name')} set to {ui_value(new_val)}\") #> ✔ name set to 'oxnard' ui_todo(\"Redocument with {ui_code('devtools::document()')}\") #> • Redocument with `devtools::document()` ui_code_block(c( \"Line 1\", \"Line 2\", \"Line 3\" )) #> Line 1 #> Line 2 #> Line 3"},{"path":"https://usethis.r-lib.org/dev/reference/ui-questions.html","id":null,"dir":"Reference","previous_headings":"","what":"User interface - Questions — ui-questions","title":"User interface - Questions — ui-questions","text":"ui_yeah() ui_nope() technically superseded, , unlike rest legacy ui_*() functions, yet drop-replacement available cli package. ui_yeah() ui_nope() longer used internally usethis.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-questions.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"User interface - Questions — ui-questions","text":"","code":"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() )"},{"path":"https://usethis.r-lib.org/dev/reference/ui-questions.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"User interface - Questions — ui-questions","text":"x character vector. block styles, conditions, questions, element vector becomes line, result processed glue::glue(). inline styles, element vector becomes entry comma separated list. yes character vector \"yes\" strings, randomly sampled populate menu. character vector \"\" strings, randomly sampled populate menu. n_yes integer. number \"yes\" strings include. n_no integer. number \"\" strings include. shuffle logical. order menu options randomly shuffled? .envir Used ensure glue::glue() gets correct environment. expert use .","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-questions.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"User interface - Questions — ui-questions","text":"logical. ui_yeah() returns TRUE user selects \"yes\" option FALSE otherwise, .e. user selects \"\" option refuses make selection (cancels). ui_nope() logical opposite ui_yeah().","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-questions.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"User interface - Questions — ui-questions","text":"","code":"if (FALSE) { # \\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) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/ui_silence.html","id":null,"dir":"Reference","previous_headings":"","what":"Suppress usethis's messaging — ui_silence","title":"Suppress usethis's messaging — ui_silence","text":"Execute bit code without usethis's normal messaging.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui_silence.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Suppress usethis's messaging — ui_silence","text":"","code":"ui_silence(code)"},{"path":"https://usethis.r-lib.org/dev/reference/ui_silence.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Suppress usethis's messaging — ui_silence","text":"code Code execute usual UI output silenced.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui_silence.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Suppress usethis's messaging — ui_silence","text":"Whatever code returns.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui_silence.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Suppress usethis's messaging — ui_silence","text":"","code":"# compare the messaging you see from this: browse_github(\"usethis\") #> ☐ Open URL . # vs. this: ui_silence( browse_github(\"usethis\") )"},{"path":"https://usethis.r-lib.org/dev/reference/use_addin.html","id":null,"dir":"Reference","previous_headings":"","what":"Add minimal RStudio Addin binding — use_addin","title":"Add minimal RStudio Addin binding — use_addin","text":"function helps add minimal RStudio Addin binding inst/rstudio/addins.dcf.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_addin.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add minimal RStudio Addin binding — use_addin","text":"","code":"use_addin(addin = \"new_addin\", open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_addin.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add minimal RStudio Addin binding — use_addin","text":"addin Name addin function, defined R folder. open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_author.html","id":null,"dir":"Reference","previous_headings":"","what":"Add an author to the Authors@R field in DESCRIPTION — use_author","title":"Add an author to the Authors@R field in DESCRIPTION — use_author","text":"use_author() adds person Authors@R field DESCRIPTION file, creating field necessary. modify, e.g., role(s) email existing author (judged using \"Given Family\" name). recommend editing DESCRIPTION directly. , programmatic use, consider calling specialized functions available desc package directly. use_author() also surfaces two situations might want address: Explicit use fields Author Maintainer. recommend switching modern Authors@R field instead, offers richer metadata various downstream uses. (Note Authors@R eventually processed create Author Maintainer fields, tar.gz built package source.) Presence fake author placed create_package() use_description(). happens usethis create DESCRIPTION file user given author information via fields argument global option \"usethis.description\". placeholder looks something like First Last [aut, cre] (-ORCID-ID) use_author() offers remove interactive sessions.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_author.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add an author to the Authors@R field in DESCRIPTION — use_author","text":"","code":"use_author(given = NULL, family = NULL, ..., role = \"ctb\")"},{"path":"https://usethis.r-lib.org/dev/reference/use_author.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add an author to the Authors@R field in DESCRIPTION — use_author","text":"given character vector given names, list thereof. family character string family name, list thereof. ... Arguments passed utils::person middle character string collapsed middle name(s). Deprecated, see Details. email character string (vector) giving e-mail address (), list thereof. comment character string (vector) providing comments, list thereof. first character string giving first name. Deprecated, see Details. last character string giving last name. Deprecated, see Details. role character vector specifying role(s) person (see Details), list thereof.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_author.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add an author to the Authors@R field in DESCRIPTION — use_author","text":"","code":"if (FALSE) { # \\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\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_blank_slate.html","id":null,"dir":"Reference","previous_headings":"","what":"Don't save/load user workspace between sessions — use_blank_slate","title":"Don't save/load user workspace between sessions — use_blank_slate","text":"R can save reload user's workspace sessions via .RData file current directory. However, long-term reproducibility enhanced turn feature clear R's memory every restart. Starting blank slate provides timely feedback encourages development scripts complete self-contained. detail can found blog post Project-oriented workflow.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_blank_slate.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Don't save/load user workspace between sessions — use_blank_slate","text":"","code":"use_blank_slate(scope = c(\"user\", \"project\"))"},{"path":"https://usethis.r-lib.org/dev/reference/use_blank_slate.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Don't save/load user workspace between sessions — use_blank_slate","text":"scope Edit globally current user, locally current project","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_build_ignore.html","id":null,"dir":"Reference","previous_headings":"","what":"Add files to .Rbuildignore — use_build_ignore","title":"Add files to .Rbuildignore — use_build_ignore","text":".Rbuildignore regular expression line, usually easier work specific file names. default, use_build_ignore() (crudely) turn filename regular expression match path. Repeated entries silently removed. use_build_ignore() designed ignore individual files. want ignore files given extension, consider providing \"-\" regular expression, using escape = FALSE; see examples.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_build_ignore.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add files to .Rbuildignore — use_build_ignore","text":"","code":"use_build_ignore(files, escape = TRUE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_build_ignore.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add files to .Rbuildignore — use_build_ignore","text":"files Character vector path names. escape TRUE, default, escape . \\\\. surround ^ $.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_build_ignore.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add files to .Rbuildignore — use_build_ignore","text":"","code":"if (FALSE) { # \\dontrun{ # ignore all Excel files use_build_ignore(\"[.]xlsx$\", escape = FALSE) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_citation.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a CITATION template — use_citation","title":"Create a CITATION template — use_citation","text":"Use want encourage users package cite article book.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_citation.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a CITATION template — use_citation","text":"","code":"use_citation()"},{"path":"https://usethis.r-lib.org/dev/reference/use_code_of_conduct.html","id":null,"dir":"Reference","previous_headings":"","what":"Add a code of conduct — use_code_of_conduct","title":"Add a code of conduct — use_code_of_conduct","text":"Adds CODE_OF_CONDUCT.md file active project lists .Rbuildignore, case package. goal code conduct foster environment inclusiveness, explicitly discourage inappropriate behaviour. template comes https://www.contributor-covenant.org, version 2.1: https://www.contributor-covenant.org/version/2/1/code_of_conduct/.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_code_of_conduct.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add a code of conduct — use_code_of_conduct","text":"","code":"use_code_of_conduct(contact, path = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_code_of_conduct.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add a code of conduct — use_code_of_conduct","text":"contact Contact details making code conduct report. Usually email address. path Path directory put CODE_OF_CONDUCT.md , relative active project. Passed along use_directory(). Default locate top-level, .github/ also common.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_code_of_conduct.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Add a code of conduct — use_code_of_conduct","text":"package going CRAN, link CoC README must absolute link rendered website CODE_OF_CONDUCT.md included package sent CRAN. use_code_of_conduct() automatically generate link (1) use pkgdown (2) set url field _pkgdown.yml; otherwise link copy CoC https://www.contributor-covenant.org.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":null,"dir":"Reference","previous_headings":"","what":"Helpers to download and unpack a ZIP file — use_course_details","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"Details internal helper functions power use_course() use_zip(). create_download_url() exported.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"","code":"tidy_download(url, destdir = getwd()) tidy_unzip(zipfile, cleanup = FALSE) create_download_url(url)"},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"url GitHub, DropBox, Google Drive URL. create_download_url(): URL copied web browser. tidy_download(): download link ZIP file, possibly behind shortlink redirect. create_download_url() can helpful creating URL typical browser URLs. destdir Path existing local directory ZIP file stored. Defaults current working directory, note use_course() different default behavior. zipfile Path local ZIP file. cleanup Whether delete ZIP file unpacking. interactive session, cleanup = NA leads asking user want delete keep ZIP file.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"tidy-download-","dir":"Reference","previous_headings":"","what":"tidy_download()","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"Special-purpose function download ZIP file automatically determine file name, often determines folder name unpacking. Developed DropBox GitHub primary targets, possibly via shortlinks. platforms offer way download entire folder repo ZIP file, information original folder repo transmitted Content-Disposition header. absence header, filename generated input URL. either case, filename sanitized. Returns path downloaded ZIP file, invisibly. tidy_download() setup retry download failure. interactive session, asks user's consent. retries use longer connect timeout.","code":"# how it's used inside use_course() tidy_download( # url has been processed with internal helper normalize_url() url, # conspicuous_place() = `getOption('usethis.destdir')` or desktop or home # directory or working directory destdir = destdir %||% conspicuous_place() )"},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"dropbox","dir":"Reference","previous_headings":"","what":"DropBox","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"make folder available ZIP download, create shared link : https://help.dropbox.com/share/create--share-link shared link form: Replace dl=0 end dl=1 create download link: can use create_download_url() conversion. download link (shortlink points ) suitable input tidy_download(). one redirections, link eventually lead download URL. details, see https://help.dropbox.com/share/force-download https://help.dropbox.com/sync/download-entire-folders.","code":"https://www.dropbox.com/sh/12345abcde/6789wxyz?dl=0 https://www.dropbox.com/sh/12345abcde/6789wxyz?dl=1"},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"github","dir":"Reference","previous_headings":"","what":"GitHub","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"Click repo's \"Clone download\" button, reveal \"Download ZIP\" button. Capture URL, form: download link (shortlink points ) suitable input tidy_download(). one redirections, link eventually lead download URL. links also lead ZIP download, albeit different filenaming scheme (REF branch name, tag, SHA): can use create_download_url() create \"Download ZIP\" URL typical GitHub browser URL.","code":"https://github.com/r-lib/usethis/archive/main.zip https://github.com/github.com/r-lib/usethis/zipball/HEAD https://api.github.com/repos/r-lib/rematch2/zipball/REF https://api.github.com/repos/r-lib/rematch2/zipball/HEAD https://api.github.com/repos/r-lib/usethis/zipball/REF"},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"google-drive","dir":"Reference","previous_headings":"","what":"Google Drive","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"knowledge, possible download Google Drive folder ZIP archive. however possible share ZIP file stored Google Drive. get URL, click \"Get shareable link\" (within \"Share\" menu). URL allow direct download, designed processed web browser first. sharing link looks like: able get URL suitable direct download, need extract \"id\" element URL include URL format: Use create_download_url() perform transformation automatically.","code":"https://drive.google.com/open?id=123456789xxyyyzzz https://drive.google.com/uc?export=download&id=123456789xxyyyzzz"},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"tidy-unzip-","dir":"Reference","previous_headings":"","what":"tidy_unzip()","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"Special-purpose function unpack ZIP file (attempt ) create directory structure people want. unpacking archive, easy get one one less level nesting expected. especially important finesse directory structure : want local result unzipping content either GitHub DropBox ZIP files, pack things differently. intent: ZIP archive foo.zip contain single top-level directory, .e. packed \"loose parts\", unzip directory named foo. Typical DropBox ZIP files. ZIP archive foo.zip single top-level directory (, way, necessarily called \"foo\"), unpack said directory. Typical GitHub ZIP files. Returns path directory holding unpacked files, invisibly. DropBox: ZIP files produced DropBox special. file list tends contain spurious directory \"/\", ignore unzip. Also, directory Git repo /RStudio Project, unzip-ignore various hidden files, .RData, .Rhistory, .git/ .Rproj.user.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"","code":"if (FALSE) { # \\dontrun{ tidy_download(\"https://github.com/r-lib/rematch2/archive/main.zip\") tidy_unzip(\"rematch2-main.zip\") } # } # GitHub create_download_url(\"https://github.com/r-lib/usethis\") #> [1] \"https://github.com/r-lib/usethis/zipball/HEAD\" create_download_url(\"https://github.com/r-lib/usethis/issues\") #> [1] \"https://github.com/r-lib/usethis/zipball/HEAD\" # DropBox create_download_url(\"https://www.dropbox.com/sh/12345abcde/6789wxyz?dl=0\") #> [1] \"https://www.dropbox.com/sh/12345abcde/6789wxyz?dl=1\" # Google Drive create_download_url(\"https://drive.google.com/open?id=123456789xxyyyzzz\") #> [1] \"https://drive.google.com/uc?export=download&id=123456789xxyyyzzz\" create_download_url(\"https://drive.google.com/open?id=123456789xxyyyzzz/view\") #> [1] \"https://drive.google.com/uc?export=download&id=123456789xxyyyzzz\""},{"path":"https://usethis.r-lib.org/dev/reference/use_coverage.html","id":null,"dir":"Reference","previous_headings":"","what":"Test coverage — use_coverage","title":"Test coverage — use_coverage","text":"Adds test coverage reporting package, using either Codecov (https://codecov.io) Coveralls (https://coveralls.io).","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_coverage.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Test coverage — use_coverage","text":"","code":"use_coverage(type = c(\"codecov\", \"coveralls\"), repo_spec = NULL) use_covr_ignore(files)"},{"path":"https://usethis.r-lib.org/dev/reference/use_coverage.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Test coverage — use_coverage","text":"type web service use. repo_spec Optional GitHub repo specification form: owner/repo. can usually inferred GitHub remotes active project. files Character vector file globs.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_cpp11.html","id":null,"dir":"Reference","previous_headings":"","what":"Use C++ via the cpp11 package — use_cpp11","title":"Use C++ via the cpp11 package — use_cpp11","text":"Adds infrastructure needed use cpp11 package, header-R package helps R package developers handle R objects C++ code: Creates src/ Adds cpp11 DESCRIPTION Creates src/code.cpp, initial placeholder .cpp file","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_cpp11.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use C++ via the cpp11 package — use_cpp11","text":"","code":"use_cpp11()"},{"path":"https://usethis.r-lib.org/dev/reference/use_cran_comments.html","id":null,"dir":"Reference","previous_headings":"","what":"CRAN submission comments — use_cran_comments","title":"CRAN submission comments — use_cran_comments","text":"Creates cran-comments.md, template communications CRAN submitting package. goal clearly communicate steps taken check package wide range operating systems. submitting update package used packages, also need summarize results reverse dependency checks.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_cran_comments.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"CRAN submission comments — use_cran_comments","text":"","code":"use_cran_comments(open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_cran_comments.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"CRAN submission comments — use_cran_comments","text":"open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_data.html","id":null,"dir":"Reference","previous_headings":"","what":"Create package data — use_data","title":"Create package data — use_data","text":"use_data() makes easy save package data correct format. recommend save scripts generate package data data-raw: use use_data_raw() set . also need document exported datasets.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_data.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create package data — use_data","text":"","code":"use_data( ..., internal = FALSE, overwrite = FALSE, compress = \"bzip2\", version = 3, ascii = FALSE ) use_data_raw(name = \"DATASET\", open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_data.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create package data — use_data","text":"... Unquoted names existing objects save. internal FALSE, saves object .rda file data/ directory. data files bypass usual export mechanism available whenever package loaded (via data() LazyData true). TRUE, stores objects single R/sysdata.rda file. Objects file follow usual export rules. Note means exported using common exportPattern() rule exports objects except start .. overwrite default, use_data() overwrite existing files. really want , set TRUE. compress Choose type compression used save(). one \"gzip\", \"bzip2\", \"xz\". version serialization format version use. default, 3, can read R versions 3.5.0 higher. R 1.4.0 3.5.3, use version 2. ascii TRUE, ASCII representation data written. default value ascii FALSE leads binary file written. NA version >= 2, different ASCII representation used writes double/complex numbers binary fractions. name Name dataset prepared inclusion package. open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_data.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create package data — use_data","text":"","code":"if (FALSE) { # \\dontrun{ x <- 1:10 y <- 1:100 use_data(x, y) # For external use use_data(x, y, internal = TRUE) # For internal use } # } if (FALSE) { # \\dontrun{ use_data_raw(\"daisy\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_data_table.html","id":null,"dir":"Reference","previous_headings":"","what":"Prepare for importing data.table — use_data_table","title":"Prepare for importing data.table — use_data_table","text":"use_data_table() imports data.table() function data.table package, well several important symbols: :=, .SD, ., .N, ., .GRP, .NGRP, .EACHI. minimal setup can learn much \"Importing data.table\" vignette: https://rdatatable.gitlab.io/data.table/articles/datatable-importing.html. addition importing functions, use_data_table() also blocks usage data.table Depends field DESCRIPTION file; data.table used imported suggested package . See discussion.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_data_table.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Prepare for importing data.table — use_data_table","text":"","code":"use_data_table()"},{"path":"https://usethis.r-lib.org/dev/reference/use_description.html","id":null,"dir":"Reference","previous_headings":"","what":"Create or modify a DESCRIPTION file — use_description","title":"Create or modify a DESCRIPTION file — use_description","text":"use_description() creates DESCRIPTION file. Although mostly associated R packages, DESCRIPTION file can also used declare dependencies non-package project. Within project, devtools::install_deps() can used install required packages. Note , default, use_decription() checks CRAN-compliant package name. can turn check_name = FALSE. usethis consults following sources, order, set DESCRIPTION fields: fields argument create_package() use_description() getOption(\"usethis.description\") Defaults built usethis fields discovered via options usethis package can viewed use_description_defaults(). create lot packages, consider storing personalized defaults named list option named \"usethis.description\". example code include .Rprofile, can opened via edit_r_profile(): Prior usethis v2.0.0, getOption(\"devtools.desc\") consulted backwards compatibility, now \"usethis.description\" option supported.","code":"options( usethis.description = list( \"Authors@R\" = utils::person( \"Jane\", \"Doe\", email = \"jane@example.com\", role = c(\"aut\", \"cre\"), comment = c(ORCID = \"YOUR-ORCID-ID\") ), Language = \"es\", License = \"MIT + file LICENSE\" ) )"},{"path":"https://usethis.r-lib.org/dev/reference/use_description.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create or modify a DESCRIPTION file — use_description","text":"","code":"use_description(fields = list(), check_name = TRUE, roxygen = TRUE) use_description_defaults(package = NULL, roxygen = TRUE, fields = list())"},{"path":"https://usethis.r-lib.org/dev/reference/use_description.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create or modify a DESCRIPTION file — use_description","text":"fields named list fields add DESCRIPTION, potentially overriding default values. Default values taken \"usethis.description\" option usethis package (order), can viewed use_description_defaults(). check_name Whether check name valid CRAN throw error . roxygen TRUE, sets RoxygenNote current roxygen2 version package Package name","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_description.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create or modify a DESCRIPTION file — use_description","text":"","code":"if (FALSE) { # \\dontrun{ use_description() use_description(fields = list(Language = \"es\")) use_description_defaults() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_directory.html","id":null,"dir":"Reference","previous_headings":"","what":"Use a directory — use_directory","title":"Use a directory — use_directory","text":"use_directory() creates directory (already exist) project's top-level directory. function powers many use_ functions use_data() use_vignette().","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_directory.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use a directory — use_directory","text":"","code":"use_directory(path, ignore = FALSE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_directory.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use a directory — use_directory","text":"path Path directory create, relative project. ignore newly created file added .Rbuildignore?","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_directory.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Use a directory — use_directory","text":"","code":"if (FALSE) { # \\dontrun{ use_directory(\"inst\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_git.html","id":null,"dir":"Reference","previous_headings":"","what":"Initialise a git repository — use_git","title":"Initialise a git repository — use_git","text":"use_git() initialises Git repository adds important files .gitignore. user consents, also makes initial commit.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Initialise a git repository — use_git","text":"","code":"use_git(message = \"Initial commit\")"},{"path":"https://usethis.r-lib.org/dev/reference/use_git.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Initialise a git repository — use_git","text":"message Message use first commit.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_git.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Initialise a git repository — use_git","text":"","code":"if (FALSE) { # \\dontrun{ use_git() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_git_config.html","id":null,"dir":"Reference","previous_headings":"","what":"Configure Git — use_git_config","title":"Configure Git — use_git_config","text":"Sets Git options, either user project (\"global\" \"local\", Git terminology). Wraps gert::git_config_set() gert::git_config_global_set(). inspect Git config, see gert::git_config().","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git_config.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Configure Git — use_git_config","text":"","code":"use_git_config(scope = c(\"user\", \"project\"), ...)"},{"path":"https://usethis.r-lib.org/dev/reference/use_git_config.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Configure Git — use_git_config","text":"scope Edit globally current user, locally current project ... Name-value pairs, processed .","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git_config.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Configure Git — use_git_config","text":"Invisibly, previous values modified components, named list.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_git_config.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Configure Git — use_git_config","text":"","code":"if (FALSE) { # \\dontrun{ # set the user's global user.name and user.email use_git_config(user.name = \"Jane\", user.email = \"jane@example.org\") # set the user.name and user.email locally, i.e. for current repo/project use_git_config( scope = \"project\", user.name = \"Jane\", user.email = \"jane@example.org\" ) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_git_hook.html","id":null,"dir":"Reference","previous_headings":"","what":"Add a git hook — use_git_hook","title":"Add a git hook — use_git_hook","text":"Sets git hook using specified script. Creates hook directory needed, sets correct permissions hook.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git_hook.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add a git hook — use_git_hook","text":"","code":"use_git_hook(hook, script)"},{"path":"https://usethis.r-lib.org/dev/reference/use_git_hook.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add a git hook — use_git_hook","text":"hook Hook name. One \"pre-commit\", \"prepare-commit-msg\", \"commit-msg\", \"post-commit\", \"applypatch-msg\", \"pre-applypatch\", \"post-applypatch\", \"pre-rebase\", \"post-rewrite\", \"post-checkout\", \"post-merge\", \"pre-push\", \"pre-auto-gc\". script Text script run","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_git_ignore.html","id":null,"dir":"Reference","previous_headings":"","what":"Tell Git to ignore files — use_git_ignore","title":"Tell Git to ignore files — use_git_ignore","text":"Tell Git ignore files","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git_ignore.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tell Git to ignore files — use_git_ignore","text":"","code":"use_git_ignore(ignores, directory = \".\")"},{"path":"https://usethis.r-lib.org/dev/reference/use_git_ignore.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Tell Git to ignore files — use_git_ignore","text":"ignores Character vector ignores, specified file globs. directory Directory relative active project set ignores","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_git_remote.html","id":null,"dir":"Reference","previous_headings":"","what":"Configure and report Git remotes — use_git_remote","title":"Configure and report Git remotes — use_git_remote","text":"Two helpers available: use_git_remote() sets remote associated name url. git_remotes() reports configured remotes, similar git remote -v.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git_remote.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Configure and report Git remotes — use_git_remote","text":"","code":"use_git_remote(name = \"origin\", url, overwrite = FALSE) git_remotes()"},{"path":"https://usethis.r-lib.org/dev/reference/use_git_remote.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Configure and report Git remotes — use_git_remote","text":"name string giving short name remote. url string giving url remote. overwrite Logical. Controls whether existing remote can modified.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git_remote.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Configure and report Git remotes — use_git_remote","text":"Named list Git remotes.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git_remote.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Configure and report Git remotes — use_git_remote","text":"","code":"if (FALSE) { # \\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) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_github.html","id":null,"dir":"Reference","previous_headings":"","what":"Connect a local repo with GitHub — use_github","title":"Connect a local repo with GitHub — use_github","text":"use_github() takes local project : Checks initial state good go: Project already Git repo Current branch default branch, e.g. main master uncommitted changes pre-existing origin remote Creates associated repo GitHub Adds GitHub repo local repo origin remote Makes initial push GitHub Calls use_github_links(), project R package Configures origin/DEFAULT upstream branch local DEFAULT branch, e.g. main master See authentication setup necessary work.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Connect a local repo with GitHub — use_github","text":"","code":"use_github( organisation = NULL, private = FALSE, visibility = c(\"public\", \"private\", \"internal\"), protocol = git_protocol(), host = NULL )"},{"path":"https://usethis.r-lib.org/dev/reference/use_github.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Connect a local repo with GitHub — use_github","text":"organisation supplied, repo created organisation, instead login associated GitHub token discovered host. user's role token's scopes must permission create repositories organisation. private TRUE, creates private repository. visibility relevant organisation-owned repos associated certain GitHub Enterprise products. special \"internal\" visibility grants read permission organisation members, .e. intermediate \"private\" \"public\", within GHE. specified, visibility takes precedence private = TRUE/FALSE. protocol One \"https\" \"ssh\" host GitHub host target, passed .api_url argument gh::gh(). unspecified, gh defaults \"https://api.github.com\", although gh's default can customised setting GITHUB_API_URL environment variable. hypothetical GitHub Enterprise instance, either \"https://github.acme.com/api/v3\" \"https://github.acme.com\" acceptable.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github.html","id":"git-github-authentication","dir":"Reference","previous_headings":"","what":"Git/GitHub Authentication","title":"Connect a local repo with GitHub — use_github","text":"Many usethis functions, including documented , potentially interact GitHub two different ways: Via GitHub REST API. Examples: create repo, fork, pull request. conventional Git remote. Examples: clone, fetch, push. Therefore two types auth can happen credentials must discoverable. credentials mean? GitHub personal access token (PAT) must discoverable gh package, used GitHub operations via REST API. See gh_token_help() getting configuring PAT. use HTTPS protocol Git remotes, PAT also used Git operations, git push. Usethis uses gert package , PAT must discoverable gert. Generally gert gh discover use PAT. ability \"kill two birds one stone\" HTTPS + PAT recommended auth strategy new Git GitHub PRs. use SSH remotes, SSH keys must also discoverable, addition PAT. public key must added GitHub account. Git/GitHub credential management covered dedicated article: Managing Git(Hub) Credentials","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Connect a local repo with GitHub — use_github","text":"","code":"if (FALSE) { # \\dontrun{ pkgpath <- file.path(tempdir(), \"testpkg\") create_package(pkgpath) ## now, working inside \"testpkg\", initialize git repository use_git() ## create github repository and configure as git remote use_github() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_action.html","id":null,"dir":"Reference","previous_headings":"","what":"Set up a GitHub Actions workflow — use_github_action","title":"Set up a GitHub Actions workflow — use_github_action","text":"Sets continuous integration (CI) R package developed GitHub using GitHub Actions. CI can used trigger various operations push pull request, e.g. running R CMD check building deploying pkgdown site.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_action.html","id":"workflows","dir":"Reference","previous_headings":"","what":"Workflows","title":"Set up a GitHub Actions workflow — use_github_action","text":"four particularly important workflows used many packages: check-standard: Run R CMD check using R-latest Linux, Mac, Windows, using R-devel R-oldrel Linux. good baseline plan submitting package CRAN. test-coverage: Compute test coverage report https://.codecov.io calling covr::codecov(). pkgdown: Automatically build publish pkgdown website. recommend instead calling use_pkgdown_github_pages() performs important set . pr-commands: Enables use two R-specific commands pull request issue comments: /document run roxygen2::roxygenise() /style run styler::style_pkg(). update PR changes done. call use_github_action() without arguments, prompted pick one . Otherwise can see complete list possibilities provided r-lib https://github.com/r-lib/actions/tree/v2/examples, can supply url use workflow.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_action.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Set up a GitHub Actions workflow — use_github_action","text":"","code":"use_github_action( name = NULL, ref = NULL, url = NULL, save_as = NULL, readme = NULL, ignore = TRUE, open = FALSE, badge = NULL )"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_action.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Set up a GitHub Actions workflow — use_github_action","text":"name use_github_action(): Name one example workflow https://github.com/r-lib/actions/tree/v2/examples (without extension), e.g. \"pkgdown\", \"check-standard.yaml\". name starts check-, save_as default R-CMD-check.yaml badge default TRUE. ref Desired Git reference, usually name tag (\"v2\") branch (\"main\"). possibilities include commit SHA (\"d1c516d\") \"HEAD\" (meaning \"tip remote's default branch\"). specified, defaults latest published release r-lib/actions (https://github.com/r-lib/actions/releases). url full URL .yaml file GitHub. See details use_github_file(). save_as Name local workflow file. Defaults name fs::path_file(url) use_github_action(). specify part path; parent directory always .github/workflows, within active project. readme full URL README file provides details workflow. Ignored url NULL. ignore newly created file added .Rbuildignore? open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise. badge add badge README?","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_action.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Set up a GitHub Actions workflow — use_github_action","text":"","code":"if (FALSE) { # \\dontrun{ use_github_action() use_github_action_check_standard() use_github_action(\"pkgdown\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_actions.html","id":null,"dir":"Reference","previous_headings":"","what":"Deprecated GitHub Actions functions — use_github_actions","title":"Deprecated GitHub Actions functions — use_github_actions","text":"use_github_actions() deprecated just alias use_github_action_check_release(). use_github_action_check_full() overkill packages recommended. use_github_action_check_release(), use_github_action_check_standard(), use_github_action_pr_commands() deprecated favor use_github_action(), can now suggest specific workflows use.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_actions.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Deprecated GitHub Actions functions — use_github_actions","text":"","code":"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 )"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_actions_badge.html","id":null,"dir":"Reference","previous_headings":"","what":"Generates a GitHub Actions badge — use_github_actions_badge","title":"Generates a GitHub Actions badge — use_github_actions_badge","text":"Generates GitHub Actions badge . exists primarily internal use.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_actions_badge.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generates a GitHub Actions badge — use_github_actions_badge","text":"","code":"use_github_actions_badge(name = \"R-CMD-check.yaml\", repo_spec = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_actions_badge.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generates a GitHub Actions badge — use_github_actions_badge","text":"name Name workflow's YAML configuration file (without extension), e.g. \"R-CMD-check\", \"R-CMD-check.yaml\".","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_file.html","id":null,"dir":"Reference","previous_headings":"","what":"Copy a file from any GitHub repo into the current project — use_github_file","title":"Copy a file from any GitHub repo into the current project — use_github_file","text":"Gets content file GitHub, repo user can read, writes active project. function wraps endpoint GitHub API supports specifying target reference (.e. branch, tag, commit) follows symlinks.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_file.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Copy a file from any GitHub repo into the current project — use_github_file","text":"","code":"use_github_file( repo_spec, path = NULL, save_as = NULL, ref = NULL, ignore = FALSE, open = FALSE, overwrite = FALSE, host = NULL )"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_file.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Copy a file from any GitHub repo into the current project — use_github_file","text":"repo_spec string identifying GitHub repo , alternatively, GitHub file URL. Acceptable forms: Plain OWNER/REPO spec blob URL, \"https://github.com/OWNER/REPO/blob/REF/path///file\" raw URL, \"https://raw.githubusercontent.com/OWNER/REPO/REF/path///file\" case URL, path, ref, host extracted , addition repo_spec. path Path file copy, relative GitHub repo lives . extracted repo_spec user provides URL. save_as Path file create, relative root active project. Defaults last part path, sense basename(path) fs::path_file(path). ref name branch, tag, commit. default, file path copied current state repo's default branch. extracted repo_spec user provides URL. ignore newly created file added .Rbuildignore? open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise. overwrite Force overwrite existing file? host GitHub host target, passed .api_url argument gh::gh(). unspecified, gh defaults \"https://api.github.com\", although gh's default can customised setting GITHUB_API_URL environment variable. hypothetical GitHub Enterprise instance, either \"https://github.acme.com/api/v3\" \"https://github.acme.com\" acceptable.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_file.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Copy a file from any GitHub repo into the current project — use_github_file","text":"logical indicator whether file written, invisibly.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_file.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Copy a file from any GitHub repo into the current project — use_github_file","text":"","code":"if (FALSE) { # \\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\" ) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Manage GitHub issue labels — use_github_labels","title":"Manage GitHub issue labels — use_github_labels","text":"use_github_labels() can create new labels, update colours descriptions, optionally delete GitHub's default labels (delete_default = TRUE). never delete labels associated issues. use_tidy_github_labels() calls use_github_labels() tidyverse conventions powered tidy_labels(), tidy_labels_rename(), tidy_label_colours() tidy_label_descriptions().","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_labels.html","id":"tidyverse-label-usage","dir":"Reference","previous_headings":"","what":"tidyverse label usage","title":"Manage GitHub issue labels — use_github_labels","text":"Labels used part issue-triage process, designed minimise time spent re-reading issues. absence label indicates issue new, yet triaged. four mutually exclusive labels indicate overall \"type\" issue: bug: unexpected problem unintended behavior. documentation: requires changes docs. feature: feature requests enhancement. upkeep: general package maintenance work makes future development easier. five labels needed repositories: breaking change: issue/PR requires breaking change included patch releases. reprex indicates issue minimal reproducible example, reply sent requesting one user. good first issue indicates good issue first-time contributors. help wanted indicates maintainer wants help issue. wip indicates someone working promised . Finally larger repos accumulate labels specific areas functionality. example, usethis labels like \"description\", \"paths\", \"readme\", time shown common sources problems. labels helpful grouping issues can tackle related problems time. Repo-specific issues grey background (#eeeeee) emoji. keeps issue page visually harmonious still giving enough variation easily distinguish different types label.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Manage GitHub issue labels — use_github_labels","text":"","code":"use_github_labels( labels = character(), rename = character(), colours = character(), descriptions = character(), delete_default = FALSE ) use_tidy_github_labels() tidy_labels() tidy_labels_rename() tidy_label_colours() tidy_label_descriptions()"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Manage GitHub issue labels — use_github_labels","text":"labels character vector giving labels add. rename named vector names giving old names values giving new names. colours, descriptions Named character vectors giving hexadecimal colours (like e02a2a) longer descriptions. names match label names, anything unmatched left unchanged. create new label, supply colours, given random colour. delete_default TRUE, removes GitHub default labels appear labels vector associated issues.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_labels.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Manage GitHub issue labels — use_github_labels","text":"","code":"if (FALSE) { # \\dontrun{ # typical use in, e.g., a new tidyverse project use_github_labels(delete_default = TRUE) # create labels without changing colours/descriptions use_github_labels( labels = c(\"foofy\", \"foofier\", \"foofiest\"), colours = NULL, descriptions = NULL ) # change descriptions without changing names/colours use_github_labels( labels = NULL, colours = NULL, descriptions = c(\"foofiest\" = \"the foofiest issue you ever saw\") ) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_links.html","id":null,"dir":"Reference","previous_headings":"","what":"Use GitHub links in URL and BugReports — use_github_links","title":"Use GitHub links in URL and BugReports — use_github_links","text":"Populates URL BugReports fields GitHub-using R package appropriate links. GitHub repo link determined current project's GitHub remotes: working fork, function expects origin GitHub remote links target repo. working fork, function expects find two GitHub remotes: origin (fork) upstream (fork's parent) remote. interactive session, user can confirm repo use links. noninteractive session, links formed using upstream.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_links.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use GitHub links in URL and BugReports — use_github_links","text":"","code":"use_github_links(overwrite = FALSE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_links.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use GitHub links in URL and BugReports — use_github_links","text":"overwrite default, use_github_links() overwrite existing fields. Set TRUE overwrite existing links.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_links.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Use GitHub links in URL and BugReports — use_github_links","text":"","code":"if (FALSE) { # \\dontrun{ use_github_links() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_pages.html","id":null,"dir":"Reference","previous_headings":"","what":"Configure a GitHub Pages site — use_github_pages","title":"Configure a GitHub Pages site — use_github_pages","text":"Activates reconfigures GitHub Pages site project hosted GitHub. function anticipates two specific usage modes: Publish root directory gh-pages branch, assumed (least primarily) remote branch. Typically gh-pages branch managed automatic \"build deploy\" job, one configured use_github_action(\"pkgdown\"). Publish \"/docs\" directory \"regular\" branch, probably repo's default branch. user assumed plan manage content \"/docs\".","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_pages.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Configure a GitHub Pages site — use_github_pages","text":"","code":"use_github_pages(branch = \"gh-pages\", path = \"/\", cname = NA)"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_pages.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Configure a GitHub Pages site — use_github_pages","text":"branch, path Branch path site source. default branch = \"gh-pages\" path = \"/\" reflects strong GitHub support configuration: gh-pages branch first created, automatically published Pages, using source found \"/\". gh-pages branch yet exist host, use_github_pages() creates empty, orphan remote branch. common alternative use repo's default branch, coupled path = \"/docs\". user's responsibility ensure branch pre-exists host. Note GitHub support arbitrary path , time writing, \"/\" \"/docs\" accepted. cname Optional, custom domain name. NA default means \"set change \", whereas value NULL removes previously configured custom domain. Note can add modify CNAME file repository. using Pages host pkgdown site, better specify URL pkgdown config file let pkgdown manage CNAME.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_pages.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Configure a GitHub Pages site — use_github_pages","text":"Site metadata returned GitHub API, invisibly","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_github_pages.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Configure a GitHub Pages site — use_github_pages","text":"","code":"if (FALSE) { # \\dontrun{ use_github_pages() use_github_pages(branch = git_default_branch(), path = \"/docs\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_release.html","id":null,"dir":"Reference","previous_headings":"","what":"Publish a GitHub release — use_github_release","title":"Publish a GitHub release — use_github_release","text":"Pushes current branch (safe) publishes GitHub release latest CRAN submission. use devtools::submit_cran() submit CRAN, information submitted state captured CRAN-SUBMISSION file. use_github_release() uses info populate GitHub release notes , success, deletes file. absence file, assume current state (SHA HEAD, package version, NEWS) submitted state.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_release.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Publish a GitHub release — use_github_release","text":"","code":"use_github_release(publish = TRUE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_release.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Publish a GitHub release — use_github_release","text":"publish TRUE, publishes release. FALSE, creates draft release.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_gitlab_ci.html","id":null,"dir":"Reference","previous_headings":"","what":"Continuous integration setup and badges — use_gitlab_ci","title":"Continuous integration setup and badges — use_gitlab_ci","text":"functions actively used tidyverse team, may currently work. Use risk. Sets third-party continuous integration (CI) services R package GitLab CircleCI. functions: Add service-specific configuration files add .Rbuildignore. Activate service give user detailed prompt. Provide markdown insert badge README.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_gitlab_ci.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Continuous integration setup and badges — use_gitlab_ci","text":"","code":"use_gitlab_ci() use_circleci(browse = rlang::is_interactive(), image = \"rocker/verse:latest\") use_circleci_badge(repo_spec = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_gitlab_ci.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Continuous integration setup and badges — use_gitlab_ci","text":"browse Open browser window enable automatic builds package. image Docker image use build. Must available DockerHub. rocker/verse image includes TeXLive, pandoc, tidyverse packages. minimal image, try rocker/r-ver. specify version R, change tag latest version want, e.g. rocker/r-ver:3.5.3. repo_spec Optional GitHub repo specification form: owner/repo. can usually inferred GitHub remotes active project.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_gitlab_ci.html","id":"use-gitlab-ci-","dir":"Reference","previous_headings":"","what":"use_gitlab_ci()","title":"Continuous integration setup and badges — use_gitlab_ci","text":"Adds basic .gitlab-ci.yml top-level directory package. configuration file GitLab CI/CD continuous integration service.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_gitlab_ci.html","id":"use-circleci-","dir":"Reference","previous_headings":"","what":"use_circleci()","title":"Continuous integration setup and badges — use_gitlab_ci","text":"Adds basic .circleci/config.yml top-level directory package. configuration file CircleCI continuous integration service.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_gitlab_ci.html","id":"use-circleci-badge-","dir":"Reference","previous_headings":"","what":"use_circleci_badge()","title":"Continuous integration setup and badges — use_gitlab_ci","text":"adds Circle CI badge. Use project Circle CI already configured.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_import_from.html","id":null,"dir":"Reference","previous_headings":"","what":"Import a function from another package — use_import_from","title":"Import a function from another package — use_import_from","text":"use_import_from() imports function another package adding roxygen2 @importFrom tag package-level documentation (can created use_package_doc()). Importing function another package allows refer without namespace (e.g., fun() instead package::fun()). use_import_from() also re-documents NAMESPACE, re-load current package. ensures fun immediately available development session.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_import_from.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Import a function from another package — use_import_from","text":"","code":"use_import_from(package, fun, load = is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_import_from.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Import a function from another package — use_import_from","text":"package Package name fun vector function names load Logical. Re-load pkgload::load_all()?","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_import_from.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Import a function from another package — use_import_from","text":"Invisibly, TRUE package document changed, FALSE .","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_import_from.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Import a function from another package — use_import_from","text":"","code":"if (FALSE) { # \\dontrun{ use_import_from(\"glue\", \"glue\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_jenkins.html","id":null,"dir":"Reference","previous_headings":"","what":"Create Jenkinsfile for Jenkins CI Pipelines — use_jenkins","title":"Create Jenkinsfile for Jenkins CI Pipelines — use_jenkins","text":"use_jenkins() adds basic Jenkinsfile R packages project root directory. Jenkinsfile stages take advantage calls make, calling function also run use_make() Makefile already exist project root.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_jenkins.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create Jenkinsfile for Jenkins CI Pipelines — use_jenkins","text":"","code":"use_jenkins()"},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_latest_dependencies.html","id":null,"dir":"Reference","previous_headings":"","what":"Use ","title":"Use ","text":"Pins minimum versions Imports Depends dependencies latest ones (determined source). Useful tidyverse package, otherwise used extreme care.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_latest_dependencies.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use ","text":"","code":"use_latest_dependencies(overwrite = TRUE, source = c(\"CRAN\", \"local\"))"},{"path":"https://usethis.r-lib.org/dev/reference/use_latest_dependencies.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use ","text":"overwrite default (TRUE), dependencies modified. Set FALSE modify dependencies without version specifications. source Use \"CRAN\" \"local\" package versions.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_lifecycle.html","id":null,"dir":"Reference","previous_headings":"","what":"Use lifecycle badges — use_lifecycle","title":"Use lifecycle badges — use_lifecycle","text":"helper: Adds lifecycle dependency. Imports lifecycle::deprecated() use function arguments. Copies lifecycle badges man/figures. Reminds use badge syntax. Learn https://lifecycle.r-lib.org/articles/communicate.html","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_lifecycle.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use lifecycle badges — use_lifecycle","text":"","code":"use_lifecycle()"},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_logo.html","id":null,"dir":"Reference","previous_headings":"","what":"Use a package logo — use_logo","title":"Use a package logo — use_logo","text":"function helps use logo package: Enforces specific size Stores logo image file man/figures/logo.png Produces markdown text need README include logo","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_logo.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use a package logo — use_logo","text":"","code":"use_logo(img, geometry = \"240x278\", retina = TRUE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_logo.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use a package logo — use_logo","text":"img path existing image file geometry magick::geometry string specifying size. default assumes hex logo using spec http://hexb./sticker.html. retina TRUE, default, scales image README, assuming geometry double desired size.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_logo.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Use a package logo — use_logo","text":"","code":"if (FALSE) { # \\dontrun{ use_logo(\"usethis.png\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_make.html","id":null,"dir":"Reference","previous_headings":"","what":"Create Makefile — use_make","title":"Create Makefile — use_make","text":"use_make() adds basic Makefile project root directory.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_make.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create Makefile — use_make","text":"","code":"use_make()"},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_namespace.html","id":null,"dir":"Reference","previous_headings":"","what":"Use a basic NAMESPACE — use_namespace","title":"Use a basic NAMESPACE — use_namespace","text":"roxygen TRUE generates empty NAMESPACE exports nothing; need explicitly export functions @export. roxygen FALSE, generates default NAMESPACE exports functions except start ..","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_namespace.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use a basic NAMESPACE — use_namespace","text":"","code":"use_namespace(roxygen = TRUE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_namespace.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use a basic NAMESPACE — use_namespace","text":"roxygen plan manage NAMESPACE roxygen2?","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_news_md.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a simple NEWS.md — use_news_md","title":"Create a simple NEWS.md — use_news_md","text":"creates basic NEWS.md root directory.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_news_md.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a simple NEWS.md — use_news_md","text":"","code":"use_news_md(open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_news_md.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a simple NEWS.md — use_news_md","text":"open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_package.html","id":null,"dir":"Reference","previous_headings":"","what":"Depend on another package — use_package","title":"Depend on another package — use_package","text":"use_package() adds CRAN package dependency DESCRIPTION offers little advice best use . use_dev_package() adds dependency -development package, adding dev repo Remotes automatically installed correct location. helper remove dependency: , simply remove package DESCRIPTION file. use_package() exists support couple common maneuvers: Add dependency Imports Suggests LinkingTo. Add minimum version dependency. Specify minimum supported version R. use_package() probably works slightly exotic modifications, point, edit DESCRIPTION hand. intention account possible edge cases.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_package.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Depend on another package — use_package","text":"","code":"use_package(package, type = \"Imports\", min_version = NULL) use_dev_package(package, type = \"Imports\", remote = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_package.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Depend on another package — use_package","text":"package Name package depend . type Type dependency: must one \"Imports\", \"Depends\", \"Suggests\", \"Enhances\", \"LinkingTo\" (unique abbreviation). Matching case insensitive. min_version Optionally, supply minimum version package. Set TRUE use currently installed version use version string suitable numeric_version(), \"2.5.0\". remote default, OWNER/REPO GitHub remote inserted. Optionally, can supply character string specify remote, e.g. \"gitlab::jimhester/covr\", using syntax supported remotes package.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_package.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Depend on another package — use_package","text":"","code":"if (FALSE) { # \\dontrun{ use_package(\"ggplot2\") use_package(\"dplyr\", \"suggests\") use_dev_package(\"glue\") # Depend on R version 4.1 use_package(\"R\", type = \"Depends\", min_version = \"4.1\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_package_doc.html","id":null,"dir":"Reference","previous_headings":"","what":"Package-level documentation — use_package_doc","title":"Package-level documentation — use_package_doc","text":"Adds dummy .R file cause roxygen2 generate basic package-level documentation. package named \"foo\", make help available user via ?foo package?foo. call devtools::document(), roxygen2 flesh .Rd file using data DESCRIPTION. ensures need repeat (remember update!) information multiple places. .R file also good place roxygen directives apply whole package (vs. specific function), global namespace tags like @importFrom.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_package_doc.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Package-level documentation — use_package_doc","text":"","code":"use_package_doc(open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_package_doc.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Package-level documentation — use_package_doc","text":"open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_pipe.html","id":null,"dir":"Reference","previous_headings":"","what":"Use magrittr's pipe in your package — use_pipe","title":"Use magrittr's pipe in your package — use_pipe","text":"setup necessary use magrittr's pipe operator, %>% package. function requires use roxygen2. Adds magrittr \"Imports\" DESCRIPTION. Imports pipe operator specifically, necessary internal use. Exports pipe operator, export = TRUE, necessary make %>% available users package.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_pipe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use magrittr's pipe in your package — use_pipe","text":"","code":"use_pipe(export = TRUE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_pipe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use magrittr's pipe in your package — use_pipe","text":"export TRUE, file R/utils-pipe.R added, provides roxygen template import re-export %>%. FALSE, necessary roxygen directive added, possible, otherwise instructions given.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_pipe.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Use magrittr's pipe in your package — use_pipe","text":"","code":"if (FALSE) { # \\dontrun{ use_pipe() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_pkgdown.html","id":null,"dir":"Reference","previous_headings":"","what":"Use pkgdown — use_pkgdown","title":"Use pkgdown — use_pkgdown","text":"pkgdown makes easy turn package beautiful website. usethis provides two functions help use pkgdown: use_pkgdown(): creates pkgdown config file adds relevant files directories .Rbuildignore .gitignore. use_pkgdown_github_pages(): implements GitHub setup needed automatically publish pkgdown site GitHub pages: (first, calls use_pkgdown()) use_github_pages() prepares publish pkgdown site gh-pages branch use_github_action(\"pkgdown\") configures GitHub Action automatically build pkgdown site deploy via GitHub Pages pkgdown site's URL added pkgdown configuration file, URL field DESCRIPTION, GitHub repo. Packages owned certain GitHub organizations (tidyverse, r-lib, tidymodels) get special treatment, terms anticipating (eventual) site URL use pkgdown template.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_pkgdown.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use pkgdown — use_pkgdown","text":"","code":"use_pkgdown(config_file = \"_pkgdown.yml\", destdir = \"docs\") use_pkgdown_github_pages()"},{"path":"https://usethis.r-lib.org/dev/reference/use_pkgdown.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use pkgdown — use_pkgdown","text":"config_file Path pkgdown yaml config file, relative project. destdir Target directory pkgdown docs.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_r.html","id":null,"dir":"Reference","previous_headings":"","what":"Create or edit R or test files — use_r","title":"Create or edit R or test files — use_r","text":"pair functions makes easy create paired R test files, using convention tests R/foofy.R live tests/testthat/test-foofy.R. can use create new files scratch supplying name, use RStudio, can call create (navigate ) companion file based currently open file. also works test snapshot file active, .e. looking tests/testthat/_snaps/foofy.md, use_r() use_test() take R/foofy.R tests/testthat/test-foofy.R, respectively.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_r.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create or edit R or test files — use_r","text":"","code":"use_r(name = NULL, open = rlang::is_interactive()) use_test(name = NULL, open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_r.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create or edit R or test files — use_r","text":"name Either string giving file name (without directory) NULL take name currently open file RStudio. open Whether open file interactive editing.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_r.html","id":"renaming-files-in-an-existing-package","dir":"Reference","previous_headings":"","what":"Renaming files in an existing package","title":"Create or edit R or test files — use_r","text":"tips aligning file names across R/ tests/testthat/ existing package necessarily follow convention . script generates data frame R/ test files can help identify missed opportunities pairing: rename_files() function can also helpful.","code":"library(fs) library(tidyverse) bind_rows( tibble( type = \"R\", path = dir_ls(\"R/\", regexp = \"\\\\.[Rr]$\"), name = as.character(path_ext_remove(path_file(path))), ), tibble( type = \"test\", path = dir_ls(\"tests/testthat/\", regexp = \"/test[^/]+\\\\.[Rr]$\"), name = as.character(path_ext_remove(str_remove(path_file(path), \"^test[-_]\"))), ) ) %>% pivot_wider(names_from = type, values_from = path) %>% print(n = Inf)"},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_r.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create or edit R or test files — use_r","text":"","code":"if (FALSE) { # \\dontrun{ # create a new .R file below R/ use_r(\"coolstuff\") # if `R/coolstuff.R` is active in a supported IDE, you can now do: use_test() # if `tests/testthat/test-coolstuff.R` is active in a supported IDE, you can # return to `R/coolstuff.R` with: use_r() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_rcpp.html","id":null,"dir":"Reference","previous_headings":"","what":"Use C, C++, RcppArmadillo, or RcppEigen — use_rcpp","title":"Use C, C++, RcppArmadillo, or RcppEigen — use_rcpp","text":"Adds infrastructure commonly needed using compiled code: Creates src/ Adds required packages DESCRIPTION May create initial placeholder .c .cpp file Creates Makevars Makevars.win files (use_rcpp_armadillo() )","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rcpp.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use C, C++, RcppArmadillo, or RcppEigen — use_rcpp","text":"","code":"use_rcpp(name = NULL) use_rcpp_armadillo(name = NULL) use_rcpp_eigen(name = NULL) use_c(name = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_rcpp.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use C, C++, RcppArmadillo, or RcppEigen — use_rcpp","text":"name Either string giving file name (without directory) NULL take name currently open file RStudio.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_readme_rmd.html","id":null,"dir":"Reference","previous_headings":"","what":"Create README files — use_readme_rmd","title":"Create README files — use_readme_rmd","text":"Creates skeleton README files possible stubs high-level description project/package goals R code install GitHub, GitHub usage detected basic example Use Rmd want rich intermingling code output. Use md basic README. README.Rmd automatically added .Rbuildignore. resulting README populated default YAML frontmatter R fenced code blocks (md) chunks (Rmd). use Rmd, still need render regularly, keep README.md --date. devtools::build_readme() handy . also use GitHub Actions re-render README.Rmd every time push. example workflow can found examples/ directory : https://github.com/r-lib/actions/. current project Git repo, use_readme_rmd() automatically configures pre-commit hook helps keep README.Rmd README.md, synchronized. hook creates friction try commit README.Rmd edited recently README.md. hook causes problems solves , implemented .git/hooks/pre-commit, can modify even delete.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_readme_rmd.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create README files — use_readme_rmd","text":"","code":"use_readme_rmd(open = rlang::is_interactive()) use_readme_md(open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_readme_rmd.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create README files — use_readme_rmd","text":"open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_readme_rmd.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create README files — use_readme_rmd","text":"","code":"if (FALSE) { # \\dontrun{ use_readme_rmd() use_readme_md() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_release_issue.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a release checklist in a GitHub issue — use_release_issue","title":"Create a release checklist in a GitHub issue — use_release_issue","text":"preparing release package CRAN quite steps need performed, steps can take multiple hours. function creates checklist GitHub issue : Help keep track process Feel sense satisfaction progress towards final submission Help watchers package stay informed. checklist contains generic set steps found helpful, based type release (\"patch\", \"minor\", \"major\"). encouraged edit issue customize list meet needs.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_release_issue.html","id":"customization","dir":"Reference","previous_headings":"","what":"Customization","title":"Create a release checklist in a GitHub issue — use_release_issue","text":"want consistently add extra bullets every release, can include custom bullets providing (unexported) release_bullets() function returns character vector. (historical reasons, release_questions() also supported). want check additional packages revdep check process, provide (unexported) release_extra_revdeps() function returns character vector. currently supported Posit internal check tooling.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_release_issue.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a release checklist in a GitHub issue — use_release_issue","text":"","code":"use_release_issue(version = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_release_issue.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a release checklist in a GitHub issue — use_release_issue","text":"version Optional version number release. unspecified, can make interactive choice.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_release_issue.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create a release checklist in a GitHub issue — use_release_issue","text":"","code":"if (FALSE) { # \\dontrun{ use_release_issue(\"2.0.0\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_revdep.html","id":null,"dir":"Reference","previous_headings":"","what":"Reverse dependency checks — use_revdep","title":"Reverse dependency checks — use_revdep","text":"Performs set checking reverse dependencies R package, implemented revdepcheck package: Creates revdep/ directory adds .Rbuildignore Populates revdep/.gitignore prevent tracking various revdep artefacts Prompts user run checks revdepcheck::revdep_check()","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_revdep.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Reverse dependency checks — use_revdep","text":"","code":"use_revdep()"},{"path":"https://usethis.r-lib.org/dev/reference/use_rmarkdown_template.html","id":null,"dir":"Reference","previous_headings":"","what":"Add an RMarkdown Template — use_rmarkdown_template","title":"Add an RMarkdown Template — use_rmarkdown_template","text":"Adds files directories necessary add custom rmarkdown template RStudio. creates: inst/rmarkdown/templates/{{template_dir}}. Main directory. skeleton/skeleton.Rmd. template Rmd file. template.yml basic information filled .","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rmarkdown_template.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add an RMarkdown Template — use_rmarkdown_template","text":"","code":"use_rmarkdown_template( template_name = \"Template Name\", template_dir = NULL, template_description = \"A description of the template\", template_create_dir = FALSE )"},{"path":"https://usethis.r-lib.org/dev/reference/use_rmarkdown_template.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add an RMarkdown Template — use_rmarkdown_template","text":"template_name name printed template menu. template_dir Name directory template live within inst/rmarkdown/templates. none provided user, created template_name. template_description Sets value description template.yml. template_create_dir Sets value create_dir template.yml.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rmarkdown_template.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add an RMarkdown Template — use_rmarkdown_template","text":"","code":"if (FALSE) { # \\dontrun{ use_rmarkdown_template() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_roxygen_md.html","id":null,"dir":"Reference","previous_headings":"","what":"Use roxygen2 with markdown — use_roxygen_md","title":"Use roxygen2 with markdown — use_roxygen_md","text":"already using roxygen2, markdown, need use roxygen2md convert existing Rd expressions markdown. conversion perfect, make sure check results.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_roxygen_md.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use roxygen2 with markdown — use_roxygen_md","text":"","code":"use_roxygen_md(overwrite = FALSE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_roxygen_md.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use roxygen2 with markdown — use_roxygen_md","text":"overwrite Whether overwrite existing Roxygen field DESCRIPTION \"list(markdown = TRUE)\".","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rscloud_badge.html","id":null,"dir":"Reference","previous_headings":"","what":"Deprecated badge function — use_rscloud_badge","title":"Deprecated badge function — use_rscloud_badge","text":"use_rscloud_badge() replaced use_posit_cloud_badge().","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rscloud_badge.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Deprecated badge function — use_rscloud_badge","text":"","code":"use_rscloud_badge(url)"},{"path":"https://usethis.r-lib.org/dev/reference/use_rstudio.html","id":null,"dir":"Reference","previous_headings":"","what":"Add RStudio Project infrastructure — use_rstudio","title":"Add RStudio Project infrastructure — use_rstudio","text":"likely want use create_project() create_package() instead use_rstudio()! create_*() functions can add RStudio Project infrastructure pre-existing project package. use_rstudio() mostly internal use creating usethis-like package organization. following current project, often executing proj_set(..., force = TRUE): Creates .Rproj file Adds RStudio files .gitignore Adds RStudio files .Rbuildignore, project package","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rstudio.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add RStudio Project infrastructure — use_rstudio","text":"","code":"use_rstudio(line_ending = c(\"posix\", \"windows\"), reformat = TRUE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_rstudio.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add RStudio Project infrastructure — use_rstudio","text":"line_ending Line ending reformat TRUE, .Rproj setup common options reformat files save: adding trailing newline, trimming trailing whitespace, setting line-ending. best practice new projects. FALSE, options left unset, appropriate contributing someone else's project .Rproj file.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rstudio_preferences.html","id":null,"dir":"Reference","previous_headings":"","what":"Set global RStudio preferences — use_rstudio_preferences","title":"Set global RStudio preferences — use_rstudio_preferences","text":"function allows set global RStudio preferences, achieving effect programmatically clicking buttons RStudio's Global Options. can find list configurable properties https://docs.posit.co/ide/server-pro/reference/session_user_settings.html.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rstudio_preferences.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Set global RStudio preferences — use_rstudio_preferences","text":"","code":"use_rstudio_preferences(...)"},{"path":"https://usethis.r-lib.org/dev/reference/use_rstudio_preferences.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Set global RStudio preferences — use_rstudio_preferences","text":"... Property-value pairs.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rstudio_preferences.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Set global RStudio preferences — use_rstudio_preferences","text":"named list previous values, invisibly.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_spell_check.html","id":null,"dir":"Reference","previous_headings":"","what":"Use spell check — use_spell_check","title":"Use spell check — use_spell_check","text":"Adds unit test automatically run spell check documentation , optionally, vignettes R CMD check, using spelling package. Also adds WORDLIST file package, dictionary whitelisted words. See spelling::wordlist details.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_spell_check.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use spell check — use_spell_check","text":"","code":"use_spell_check(vignettes = TRUE, lang = \"en-US\", error = FALSE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_spell_check.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use spell check — use_spell_check","text":"vignettes Logical, TRUE spell check rmd rnw files vignettes/ folder. lang Preferred spelling language. Usually either \"en-US\" \"en-GB\". error Logical, indicating whether unit test fail spelling errors found. Defaults FALSE, error, prints potential spelling errors","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_standalone.html","id":null,"dir":"Reference","previous_headings":"","what":"Use a standalone file from another repo — use_standalone","title":"Use a standalone file from another repo — use_standalone","text":"\"standalone\" file implements minimum set functionality way can copied another package. use_standalone() makes easy get file repo. always overwrites existing standalone file name, making easy update previously imported code.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_standalone.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use a standalone file from another repo — use_standalone","text":"","code":"use_standalone(repo_spec, file = NULL, ref = NULL, host = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_standalone.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use a standalone file from another repo — use_standalone","text":"repo_spec string identifying GitHub repo one forms: Plain OWNER/REPO spec Browser URL, \"https://github.com/OWNER/REPO\" HTTPS Git URL, \"https://github.com/OWNER/REPO.git\" SSH Git URL, \"git@github.com:OWNER/REPO.git\" file Name standalone file. standalone- prefix file extension optional. omitted, allow choose standalone files offered repo. ref name branch, tag, commit. default, file path copied current state repo's default branch. extracted repo_spec user provides URL. host GitHub host target, passed .api_url argument gh::gh(). repo_spec URL, host extracted . unspecified, gh defaults \"https://api.github.com\", although gh's default can customised setting GITHUB_API_URL environment variable. hypothetical GitHub Enterprise instance, either \"https://github.acme.com/api/v3\" \"https://github.acme.com\" acceptable.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_standalone.html","id":"supported-fields","dir":"Reference","previous_headings":"","what":"Supported fields","title":"Use a standalone file from another repo — use_standalone","text":"standalone file YAML frontmatter provides additional information, file originates last updated. example: Two fields consulted use_standalone(): dependencies: file list files repo standalone file depends . files retrieved automatically use_standalone(). imports: package list packages standalone file depends . minimal version may specified parentheses, e.g. rlang (>= 1.0.0). dependencies passed use_package() ensure included Imports: field DESCRIPTION file. Note lists specified standard YAML syntax, using square brackets, example: imports: [rlang (>= 1.0.0), purrr].","code":"--- repo: r-lib/rlang file: standalone-types-check.R last-updated: 2023-03-07 license: https://unlicense.org dependencies: standalone-obj-type.R imports: rlang (>= 1.1.0) ---"},{"path":"https://usethis.r-lib.org/dev/reference/use_standalone.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Use a standalone file from another repo — use_standalone","text":"","code":"if (FALSE) { # \\dontrun{ use_standalone(\"r-lib/rlang\", file = \"types-check\") use_standalone(\"r-lib/rlang\", file = \"types-check\", ref = \"standalone-dep\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_template.html","id":null,"dir":"Reference","previous_headings":"","what":"Use a usethis-style template — use_template","title":"Use a usethis-style template — use_template","text":"Creates file data template found package. Provides control file name, addition .Rbuildignore, opening file inspection.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_template.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use a usethis-style template — use_template","text":"","code":"use_template( template, save_as = template, data = list(), ignore = FALSE, open = FALSE, package = \"usethis\" )"},{"path":"https://usethis.r-lib.org/dev/reference/use_template.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use a usethis-style template — use_template","text":"template Path template file relative templates/ directory within package; see details. save_as Path file create, relative root active project. Defaults template data list data passed template. ignore newly created file added .Rbuildignore? open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise. package Name package template found.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_template.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Use a usethis-style template — use_template","text":"logical vector indicating file modified.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_template.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Use a usethis-style template — use_template","text":"function can used engine templating function packages. template argument used along package argument derive path template file; expected fs::path_package(package = package, \"templates\", template). use fs::path_package() instead base::system.file() path construction works even development workflow, e.g., works devtools::load_all() pkgload::load_all(). Note describes behaviour fs::path_package() fs v1.2.7.9001 higher. interpolate data template, supply list using data argument. Internally, function uses whisker::whisker.render() combine template file data.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_template.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Use a usethis-style template — use_template","text":"","code":"if (FALSE) { # \\dontrun{ # Note: running this will write `NEWS.md` to your working directory use_template( template = \"NEWS.md\", data = list(Package = \"acme\", Version = \"1.2.3\"), package = \"usethis\" ) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_test_helper.html","id":null,"dir":"Reference","previous_headings":"","what":"Create or edit a test helper file — use_test_helper","title":"Create or edit a test helper file — use_test_helper","text":"function creates (opens) test helper file, typically tests/testthat/helper.R. Test helper files executed beginning every automated test run also executed load_all(). helper file great place define test helper functions use throughout test suite, custom expectation.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_test_helper.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create or edit a test helper file — use_test_helper","text":"","code":"use_test_helper(name = NULL, open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_test_helper.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create or edit a test helper file — use_test_helper","text":"name Can used specify optional \"SLUG\" tests/testthat/helper-SLUG.R. open Whether open file interactive editing.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_test_helper.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create or edit a test helper file — use_test_helper","text":"","code":"if (FALSE) { # \\dontrun{ use_test_helper() use_test_helper(\"mocks\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_testthat.html","id":null,"dir":"Reference","previous_headings":"","what":"Sets up overall testing infrastructure — use_testthat","title":"Sets up overall testing infrastructure — use_testthat","text":"Creates tests/testthat/, tests/testthat.R, adds testthat package Suggests field. Learn https://r-pkgs.org/testing-basics.html","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_testthat.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Sets up overall testing infrastructure — use_testthat","text":"","code":"use_testthat(edition = NULL, parallel = FALSE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_testthat.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Sets up overall testing infrastructure — use_testthat","text":"edition testthat edition use. Defaults latest edition, .e. major version number currently installed testthat. parallel tests run parallel? feature appeared testthat 3.0.0; see https://testthat.r-lib.org/articles/parallel.html details caveats.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_testthat.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Sets up overall testing infrastructure — use_testthat","text":"","code":"if (FALSE) { # \\dontrun{ use_testthat() use_test() use_test(\"something-management\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_tibble.html","id":null,"dir":"Reference","previous_headings":"","what":"Prepare to return a tibble — use_tibble","title":"Prepare to return a tibble — use_tibble","text":"minimum setup tibble returned package handled using tibble method generics like print() [. Presumably care chosen store expose object class tbl_df. Specifically: Check active package uses roxygen2 Add tibble package \"Imports\" DESCRIPTION Prepare roxygen directive necessary import least one function tibble: possible, directive inserted existing package-level documentation, .e. roxygen snippet created use_package_doc() Otherwise, issue advice user add directive necessary package returns stored data object class tbl_df, package code make direct use functions tibble package. nothing, tibble namespace necessarily loaded tibble may therefore printed subsetted like base data.frame.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_tibble.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Prepare to return a tibble — use_tibble","text":"","code":"use_tibble()"},{"path":"https://usethis.r-lib.org/dev/reference/use_tibble.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Prepare to return a tibble — use_tibble","text":"","code":"if (FALSE) { # \\dontrun{ use_tibble() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_tidy_eval.html","id":null,"dir":"Reference","previous_headings":"","what":"Deprecated tidyverse functions — use_tidy_eval","title":"Deprecated tidyverse functions — use_tidy_eval","text":"use_tidy_eval() deprecated longer need systematically import re-export large number functions order use tidy evaluation. Instead, use use_import_from() tactically import functions need .","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_tidy_eval.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Deprecated tidyverse functions — use_tidy_eval","text":"","code":"use_tidy_eval()"},{"path":"https://usethis.r-lib.org/dev/reference/use_tidy_thanks.html","id":null,"dir":"Reference","previous_headings":"","what":"Identify contributors via GitHub activity — use_tidy_thanks","title":"Identify contributors via GitHub activity — use_tidy_thanks","text":"Derives list GitHub usernames, based opened issues pull requests. Used populate acknowledgment section package release blog posts https://www.tidyverse.org/blog/. arguments given, retrieve contributors active project since last (GitHub) release. Unexported helper functions, releases() ref_df() can useful interactively get quick look release tag names data frame refs (defaulting releases), respectively.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_tidy_thanks.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Identify contributors via GitHub activity — use_tidy_thanks","text":"","code":"use_tidy_thanks(repo_spec = NULL, from = NULL, to = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_tidy_thanks.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Identify contributors via GitHub activity — use_tidy_thanks","text":"repo_spec Optional GitHub repo specification form accepted repo_spec argument create_from_github() (plain spec browser Git URL). URL specification way target GitHub host \"github.com\", default. , GitHub ref (.e., SHA, tag, release) timestamp ISO 8601 format, specifying start end interval interest, sense [, ]. Examples: \"08a560d\", \"v1.3.0\", \"2018-02-24T00:13:45Z\", \"2018-05-01\". = NULL, = NULL, set timestamp recent (GitHub) release. Otherwise, NULL means \"bound\".","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_tidy_thanks.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Identify contributors via GitHub activity — use_tidy_thanks","text":"character vector GitHub usernames, invisibly.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_tidy_thanks.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Identify contributors via GitHub activity — use_tidy_thanks","text":"","code":"if (FALSE) { # \\dontrun{ # active project, interval = since the last release use_tidy_thanks() # active project, interval = since a specific datetime use_tidy_thanks(from = \"2020-07-24T00:13:45Z\") # r-lib/usethis, interval = since a certain date use_tidy_thanks(\"r-lib/usethis\", from = \"2020-08-01\") # r-lib/usethis, up to a specific release use_tidy_thanks(\"r-lib/usethis\", from = NULL, to = \"v1.1.0\") # r-lib/usethis, since a specific commit, up to a specific date use_tidy_thanks(\"r-lib/usethis\", from = \"08a560d\", to = \"2018-05-14\") # r-lib/usethis, but with copy/paste of a browser URL use_tidy_thanks(\"https://github.com/r-lib/usethis\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_tutorial.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a learnr tutorial — use_tutorial","title":"Create a learnr tutorial — use_tutorial","text":"Creates new tutorial inst/tutorials/. Tutorials interactive R Markdown documents built learnr package. use_tutorial() setup: Adds learnr Suggests DESCRIPTION. Gitignores inst/tutorials/*.html accidentally track rendered tutorials. Creates new .Rmd tutorial template , optionally, opens editing. Adds new .Rmd .Rbuildignore.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_tutorial.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a learnr tutorial — use_tutorial","text":"","code":"use_tutorial(name, title, open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_tutorial.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a learnr tutorial — use_tutorial","text":"name Base file name use new .Rmd tutorial. consist numbers, letters, _ -. recommend using lower case. title human-facing title tutorial. open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_tutorial.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create a learnr tutorial — use_tutorial","text":"","code":"if (FALSE) { # \\dontrun{ use_tutorial(\"learn-to-do-stuff\", \"Learn to do stuff\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_upkeep_issue.html","id":null,"dir":"Reference","previous_headings":"","what":"Create an upkeep checklist in a GitHub issue — use_upkeep_issue","title":"Create an upkeep checklist in a GitHub issue — use_upkeep_issue","text":"opens issue package repository checklist tasks regular maintenance package. fairly opinionated list tasks believe taking care generally make package better, easier maintain, enjoyable users. tasks meant performed (completed show subsequent lists), reviewed periodically. tidyverse team uses similar function use_tidy_upkeep_issue() annual package Spring Cleaning.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_upkeep_issue.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create an upkeep checklist in a GitHub issue — use_upkeep_issue","text":"","code":"use_upkeep_issue(year = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_upkeep_issue.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create an upkeep checklist in a GitHub issue — use_upkeep_issue","text":"year Year performing upkeep, used issue title. Defaults current year","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_upkeep_issue.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create an upkeep checklist in a GitHub issue — use_upkeep_issue","text":"","code":"if (FALSE) { # \\dontrun{ use_upkeep_issue(2023) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_version.html","id":null,"dir":"Reference","previous_headings":"","what":"Increment package version — use_version","title":"Increment package version — use_version","text":"usethis supports semantic versioning, described detail version section R Packages. version number breaks like : use_version() increments \"Version\" field DESCRIPTION, adds new heading NEWS.md (exists), commits changes (package uses Git), optionally pushes (safe ). makes update line like PKG_version = \"x.y.z\"; src/version.c (exists). use_dev_version() increments development version, e.g. 1.0.0 1.0.0.9000. existing version already development version four components, nothing. Thin wrapper around use_version().","code":".. (released version) ... (dev version)"},{"path":"https://usethis.r-lib.org/dev/reference/use_version.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Increment package version — use_version","text":"","code":"use_version(which = NULL, push = FALSE) use_dev_version(push = FALSE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_version.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Increment package version — use_version","text":"string specifying level increment, one : \"major\", \"minor\", \"patch\", \"dev\". NULL, user can choose interactively. push TRUE, also attempts push commits remote branch.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_version.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Increment package version — use_version","text":"","code":"if (FALSE) { # \\dontrun{ ## for interactive selection, do this: use_version() ## request a specific type of increment use_version(\"minor\") use_dev_version() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_vignette.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a vignette or article — use_vignette","title":"Create a vignette or article — use_vignette","text":"Creates new vignette article vignettes/. Articles special type vignette appear pkgdown websites, included package (added .Rbuildignore automatically).","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_vignette.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a vignette or article — use_vignette","text":"","code":"use_vignette(name, title = name) use_article(name, title = name)"},{"path":"https://usethis.r-lib.org/dev/reference/use_vignette.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a vignette or article — use_vignette","text":"name Base file name use new vignette. consist numbers, letters, _ -. Lower case recommended. title title vignette.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_vignette.html","id":"general-setup","dir":"Reference","previous_headings":"","what":"General setup","title":"Create a vignette or article — use_vignette","text":"Adds needed packages DESCRIPTION. Adds inst/doc .gitignore built vignettes tracked. Adds vignettes/*.html vignettes/*.R .gitignore never accidentally track rendered vignettes.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_vignette.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create a vignette or article — use_vignette","text":"","code":"if (FALSE) { # \\dontrun{ use_vignette(\"how-to-do-stuff\", \"How to do stuff\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/usethis-package.html","id":null,"dir":"Reference","previous_headings":"","what":"usethis: Automate Package and Project Setup — usethis-package","title":"usethis: Automate Package and Project Setup — usethis-package","text":"Automate package project setup tasks otherwise performed manually. includes setting unit testing, test coverage, continuous integration, Git, 'GitHub', licenses, 'Rcpp', 'RStudio' projects, .","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/usethis-package.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"usethis: Automate Package and Project Setup — usethis-package","text":"Maintainer: Jennifer Bryan jenny@posit.co (ORCID) Authors: Hadley Wickham hadley@posit.co (ORCID) Malcolm Barrett malcolmbarrett@gmail.com (ORCID) Andy Teucher andy.teucher@posit.co (ORCID) contributors: Posit Software, PBC [copyright holder, funder]","code":""},{"path":"https://usethis.r-lib.org/dev/reference/usethis_options.html","id":null,"dir":"Reference","previous_headings":"","what":"Options consulted by usethis — usethis_options","title":"Options consulted by usethis — usethis_options","text":"User-configurable options consulted usethis, provide mechanism setting default behaviors various functions. built-defaults suit , set one options. Typically, done .Rprofile startup file, can open editing edit_r_profile() - set specified options future R sessions. code look something like:","code":"options( usethis.description = list( \"Authors@R\" = utils::person( \"Jane\", \"Doe\", email = \"jane@example.com\", role = c(\"aut\", \"cre\"), comment = c(ORCID = \"YOUR-ORCID-ID\") ), License = \"MIT + file LICENSE\" ), usethis.destdir = \"/path/to/folder/\", # for use_course(), create_from_github() usethis.protocol = \"ssh\", # Use ssh git protocol usethis.overwrite = TRUE # overwrite files in Git repos without confirmation )"},{"path":"https://usethis.r-lib.org/dev/reference/usethis_options.html","id":"options-for-the-usethis-package","dir":"Reference","previous_headings":"","what":"Options for the usethis package","title":"Options consulted by usethis — usethis_options","text":"usethis.description: customize default content new DESCRIPTION files setting option named list. frequent package developer, worthwhile pre-configure preferred name, email, license, etc. See example article usethis setup details. usethis.destdir: Default directory place new projects downloaded use_course() create_from_github(). option unset, user's Desktop similarly conspicuous place used. usethis.protocol: specifies preferred transport protocol Git. Either \"https\" (default) \"ssh\": usethis.protocol = \"https\" implies https://github.com//.git usethis.protocol = \"ssh\" implies git@github.com:/.git can also change duration R session use_git_protocol(). usethis.overwrite: TRUE, usethis overwrites existing file without asking user confirmation file inside Git repo. rationale normal Git workflow makes easy see selectively accept/discard proposed changes. usethis.quiet: Set TRUE suppress user-facing messages. Default FALSE. usethis.allow_nested_project: Whether allow create project inside another project. rarely good idea, option defaults FALSE.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/write-this.html","id":null,"dir":"Reference","previous_headings":"","what":"Write into or over a file — write-this","title":"Write into or over a file — write-this","text":"Helpers write new pre-existing file. Designed mostly internal use. File written UTF-8 encoding.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/write-this.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Write into or over a file — write-this","text":"","code":"write_union(path, lines, quiet = FALSE) write_over(path, lines, quiet = FALSE, overwrite = FALSE)"},{"path":"https://usethis.r-lib.org/dev/reference/write-this.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Write into or over a file — write-this","text":"path Path target file. created exist, parent directory must exist. lines Character vector lines. write_union(), lines add target file, already present. write_over(), exact lines desired target file. quiet Logical. Whether message happening. overwrite Force overwrite existing file?","code":""},{"path":"https://usethis.r-lib.org/dev/reference/write-this.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Write into or over a file — write-this","text":"Logical indicating whether write occurred, invisibly.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/write-this.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Write into or over a file — write-this","text":"write_union(): writes lines file, taking union already , anything, new lines. Note, explicit promise line order. Designed modify simple config files like .Rbuildignore .gitignore. write_over(): writes file specific lines, creating necessary overwriting existing, proposed contents identical user available give permission.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/write-this.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Write into or over a file — write-this","text":"","code":"write_union(\"a_file\", letters[1:3]) #> ✔ Adding \"a\", \"b\", and \"c\" to a_file. readLines(\"a_file\") #> [1] \"a\" \"b\" \"c\" write_union(\"a_file\", letters[1:5]) #> ✔ Adding \"d\" and \"e\" to a_file. readLines(\"a_file\") #> [1] \"a\" \"b\" \"c\" \"d\" \"e\" write_over(\"another_file\", letters[1:3]) #> ✔ Writing another_file. readLines(\"another_file\") #> [1] \"a\" \"b\" \"c\" write_over(\"another_file\", letters[1:3]) if (FALSE) { # \\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\") #> [1] TRUE TRUE"},{"path":"https://usethis.r-lib.org/dev/reference/zip-utils.html","id":null,"dir":"Reference","previous_headings":"","what":"Download and unpack a ZIP file — zip-utils","title":"Download and unpack a ZIP file — zip-utils","text":"Functions download unpack ZIP file local folder files, intentional default behaviour. Useful pedagogical settings anytime need large audience download set files quickly actually able find . underlying helpers documented use_course_details.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/zip-utils.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Download and unpack a ZIP file — zip-utils","text":"","code":"use_course(url, destdir = getOption(\"usethis.destdir\")) use_zip( url, destdir = getwd(), cleanup = if (rlang::is_interactive()) NA else FALSE )"},{"path":"https://usethis.r-lib.org/dev/reference/zip-utils.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Download and unpack a ZIP file — zip-utils","text":"url Link ZIP file containing materials. reduce chance typos live settings, shorter forms accepted: GitHub repo spec: \"OWNER/REPO\". Equivalent https://github.com/OWNER/REPO/DEFAULT_BRANCH.zip. bit.ly, pos., rstd.io shortlinks: \"bit.ly/xxx-yyy-zzz\", \"pos./foofy\" \"rstd.io/foofy\". instructor must arrange shortlink point valid download URL target ZIP file. helper create_download_url() helps create URLs GitHub, DropBox, Google Drive. destdir Destination new folder. Defaults location stored global option usethis.destdir, defined, user's Desktop similarly conspicuous place otherwise. cleanup Whether delete original ZIP file unpacking contents. interactive setting, NA leads menu user can approve deletion (decline).","code":""},{"path":"https://usethis.r-lib.org/dev/reference/zip-utils.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Download and unpack a ZIP file — zip-utils","text":"Path new directory holding unpacked ZIP file, invisibly.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/zip-utils.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Download and unpack a ZIP file — zip-utils","text":"use_course(): Designed live workshops mind. Includes intentional friction highlight download destination. Workflow: User executes, e.g., use_course(\"bit.ly/xxx-yyy-zzz\"). User asked notice confirm location new folder. Specify destdir configure \"usethis.destdir\" option prevent . User asked like delete ZIP file. new folder contains .Rproj file, new instance RStudio launched. Otherwise, folder opened file manager, e.g. Finder File Explorer. use_zip(): useful day--day work. Downloads current working directory, default, allows cleanup behaviour specified.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/zip-utils.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Download and unpack a ZIP file — zip-utils","text":"","code":"if (FALSE) { # \\dontrun{ # download the source of usethis from GitHub, behind a bit.ly shortlink use_course(\"bit.ly/usethis-shortlink-example\") use_course(\"http://bit.ly/usethis-shortlink-example\") # download the source of rematch2 package from CRAN use_course(\"https://cran.r-project.org/bin/windows/contrib/3.4/rematch2_2.0.1.zip\") # download the source of rematch2 package from GitHub, 4 ways use_course(\"r-lib/rematch2\") use_course(\"https://api.github.com/repos/r-lib/rematch2/zipball/HEAD\") use_course(\"https://api.github.com/repos/r-lib/rematch2/zipball/main\") use_course(\"https://github.com/r-lib/rematch2/archive/main.zip\") } # }"},{"path":[]},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"bug-fixes-and-minor-improvements-development-version","dir":"Changelog","previous_headings":"","what":"Bug fixes and minor improvements","title":"usethis (development version)","text":"use_package() now decreases package minimum version required min_version lower currently specified DESCRIPTION file (@jplecavalier, #1957). use_data() now uses serialization version 3 default. (@laurabrianna, #2044) Reverse dependency checks suggested exist (#1817, @seankross).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-300","dir":"Changelog","previous_headings":"","what":"usethis 3.0.0","title":"usethis 3.0.0","text":"CRAN release: 2024-07-29","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"transition-to-cli-package-for-ui-3-0-0","dir":"Changelog","previous_headings":"","what":"Transition to cli package for UI","title":"usethis 3.0.0","text":"ui_*() functions marked superseded. External users functions encouraged use cli package instead. cli package required functionality usethis::ui_*() functions first created, now ’s superior option. cli vignette make transition: vignette(\"usethis-ui\", package = \"cli\"). usethis longer uses ui_*() functions internally, favor new cli-based helpers exported.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"deprecated-function-and-argument-removal-3-0-0","dir":"Changelog","previous_headings":"","what":"Deprecated function and argument removal","title":"usethis 3.0.0","text":"removing functions arguments deprecated usethis v2.0.0, released December 2020. changes place long time now: Switch git2r gert (+ credentials). Use git config gh package infer, e.g., target repo spec. Pivot towards GitHub Actions away Travis AppVeyor. Functions removed , applicable, use instead: git_credentials() use_git_credentials() browse_github_token() (create_github_token()) browse_github_pat() (create_github_token()) github_token() (gh_token_help() gh::gh_token()) pr_pull_upstream() (pr_merge_main()) pr_sync() (pr_merge_main(); pr_push()) use_appveyor() use_appveyor_badge() use_travis() use_travis_badge() browse_travis() use_pkgdown_travis() use_tidy_ci() deprecated v2.1.0 (use_tidy_github_actions()) use_tidy_labels() deprecated v2.1.0 (use_tidy_github_labels()) Function arguments removed: create_from_github(auth_token =, credentials =) use_github(auth_token =, credentials =) use_github_labels(repo_spec =, host =, auth_token =) use_github_links(auth_token =, host =) use_github_release(host =, auth_token =)","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-changes-3-0-0","dir":"Changelog","previous_headings":"","what":"Other changes","title":"usethis 3.0.0","text":"use_zip() use_course() equipped handle ZIP parent folder implicit (@burnsal, #1961). use_test_helper() new function create test helper file (@olivroy, #1822). use_cpp11() makes easier update NAMESPACE (@pachadotdev, #1921). pr_merge_main() now offers choice open files merge conflicts (@olivroy, #1720). edit_rstudio_snippets() now accepts yaml snippets (@olivroy, #1941). use_standalone() inserts improved header includes code needed update standalone file (@krlmlr, #1903). use_release_issue() use_upkeep_issue() behave better user fork. user asked just choose origin upstream target repo (#2023). README templates now recommend pak instead devtools package installation (@olivroy, #1723). use_github() now knows can reuse name earlier repo since renamed (@ateucher, #1893). use_git() longer asks want restart RStudio using Positron. use_test() use_r() now work tests/testthat/_snaps/{foo}.md (@olivroy, #1988). URLs baked badge generated use_coverage(type = \"codecov\") updated longer specify branch(#2008). usethis::use_version() now tolerates empty lines preceding first section title package NEWS file. (#1976)","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-223","dir":"Changelog","previous_headings":"","what":"usethis 2.2.3","title":"usethis 2.2.3","text":"CRAN release: 2024-02-19 Patch release changes .Rd files requested CRAN.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-222","dir":"Changelog","previous_headings":"","what":"usethis 2.2.2","title":"usethis 2.2.2","text":"CRAN release: 2023-07-05 Implicit usage numeric_version() via comparison now always provides character input. response request CRAN anticipate future solutions https://bugs.r-project.org/show_bug.cgi?id=18548.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-221","dir":"Changelog","previous_headings":"","what":"usethis 2.2.1","title":"usethis 2.2.1","text":"CRAN release: 2023-06-23 Internal helper cran_version(), used functions use_release_checklist() use_news_md(), resilient situations CRAN mirror set (#1857). Internal usage numeric_version() now always provides character input, rather relying implicit .character() coercion. response request CRAN anticipate future solutions https://bugs.r-project.org/show_bug.cgi?id=18548 (#1869).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-220","dir":"Changelog","previous_headings":"","what":"usethis 2.2.0","title":"usethis 2.2.0","text":"CRAN release: 2023-06-06","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-functions-2-2-0","dir":"Changelog","previous_headings":"","what":"New functions","title":"usethis 2.2.0","text":"use_author() new function introduce new person Authors@R field DESCRIPTION (@avalcarcel9, #833). use_rstudio_preferences() lets set RStudio preferences programmatically (#1518) use_standalone() new function makes easier use standalone files provided various low-level tidyverse packages, like rlang (#1654). use_upkeep_issue() new function facilitate regular maintenance package. Similar use_release_issue(), opens issue repo checklist maintenance tasks. include additional bullets package includes upkeep_bullets() function returns character vector (#1794).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"package-development-2-2-0","dir":"Changelog","previous_headings":"","what":"Package development","title":"usethis 2.2.0","text":"Although nested projects discouraged, can useful development contexts. create_package() now sets correct package name returns correct package path package nested inside project (#1647). use_article() longer adds rmarkdown package Suggests. Instead, rmarkdown already dependency, ’s added Config/Needs/website. means package uses articles (vs. vignettes) won’t gain unnecessary dependency rmarkdown (#1700). use_data() now sets appropriate minimal R version DESCRIPTION, depending serialization format version choose (@dpprdan, #1672). use_github_links() default now appends GitHub url existing urls URL field DESCRIPTION, rather replacing existing urls (#1805). use_latest_dependencies() longer affects Suggests since dependencies enforced (#1749). use_news_md() now places “(development version)” header NEWS.md development version number DESCRIPTION. also sets first bullet “Initial CRAN submission” looks like “new” package (#1708). use_coverage() longer adds covr Suggests, since test-coverage GitHub Actions workflow takes care installing covr (@Bisaloo, #1851).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"package-release-2-2-0","dir":"Changelog","previous_headings":"","what":"Package release","title":"usethis 2.2.0","text":"use_release_issue() now remind run use_github_links() necessary (@Bisaloo, #1754) use_release_issue() now encourages creation NEWS.md prior submission, instead (#1755). use_github_release() now automatically pushes GitHub (safe) automatically publishes release, rather requiring edit publish draft (#1385). use_github_release() longer fails absence NEWS.md (#1755). use_release_issue() now remind check/close milestone corresponding release, exists (#1642). use_version() use_dev_version() gain push argument optionally push result committing. used eliminate manual step use_release_issue() checklist (#1385). use_revdep() longer places email template, days likely communicate maintainers breaking changes via GitHub issues pull requests (#1769).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"package-file-management-2-2-0","dir":"Changelog","previous_headings":"","what":"Package file management","title":"usethis 2.2.0","text":"rename_files() now also affects files src/ (#1585). use_r() use_test() now work active files R/, src/, tests/testthat/ (#1566). use_r() use_test() now work files containing . (#1690). use_rcpp(), use_c() friends now work way use_r() use_test(): ’ll take default file name file currently open RStudio (#1730).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"git-and-github-2-2-0","dir":"Changelog","previous_headings":"","what":"Git and GitHub","title":"usethis 2.2.0","text":"create_from_github() now use existing .Rproj file exists anywhere repo, just root directory. useful ’re working repos contain tools multiple languages (#1680). git_sitrep() gains two arguments: tool scope, enables limit report , example, tool = \"git\" scope = \"user\". default remains provide full report. Also, provides feedback git user’s information set, checks global git-email user-level GitHub PAT (@ijlyttle, #1732, #1714, #1706). git_vaccinated() now treats path configured core.excludesFile like user-supplied paths; particular, use ~/ home directory shortcut expanded via fs::path_expand() (@dpprdan, #1560). use_github_action() now suggests possible actions called without arguments (#1724). use_github_actions(), use_github_action_check_standard(), use_github_action_check_release(), use_github_action_pr_commands() deprecated favour new interactive powers use_github_action() (#1724).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"minor-improvements-and-fixes-2-2-0","dir":"Changelog","previous_headings":"","what":"Minor improvements and fixes","title":"usethis 2.2.0","text":"Links R Packages book updated second edition book (#1689). SVG badges placed use_lifecycle() improved accessibility features, .e. advertise lifecycle stage via aria-label attribute (#1554, https://github.com/r-lib/lifecycle/issues/117). use_rscloud_badge() deprecated favour use_posit_cloud_badge(), functions now accept updated url format Posit Cloud projects (#1670). use_rstudio() gains reformat argument omits .Rproj settings enforce file formatting conventions, e.g. around whitespace. create_from_github() uses option introduces .Rproj project lacks one, making easier follow project’s existing conventions (#1679). write_over() use_github_file() gain overwrite argument (#1748).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"tidyverse-related-2-2-0","dir":"Changelog","previous_headings":"","what":"Tidyverse-related","title":"usethis 2.2.0","text":"use_release_issue() now uses internal release_extra_revdeps() add extra revdep sources. Currently use internal Posit tooling, hope extend users future (#1610). use_tidy_logo() new function calls use_logo() appropriate hex sticker PNG file https://github.com/rstudio/hex-stickers (#1871).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"deprecated-functions-2-2-0","dir":"Changelog","previous_headings":"","what":"Deprecated functions","title":"usethis 2.2.0","text":"use_tidy_eval() now deprecated imports re-exports large number functions longer needed order tidy evaluation (#1656). use_travis(), use_pkgdown_travis(), browse_travis(), use_appveyor() now deprecated longer recommend Travis Appveyor. recommend GitHub actions instead (#1517).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-216","dir":"Changelog","previous_headings":"","what":"usethis 2.1.6","title":"usethis 2.1.6","text":"CRAN release: 2022-05-25","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"github-related-2-1-6","dir":"Changelog","previous_headings":"","what":"GitHub-related","title":"usethis 2.1.6","text":"use_github_action() friends gain ref argument, defaults tag latest release https://github.com/r-lib/actions (#1541). use_github_actions_badge() now uses URLs GitHub via “Create status badge” helper browser (#1525). changes significance name argument; now really must name workflow configuration file. functions error clearly requested operation supported “” remote configuration (#1588).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-changes-2-1-6","dir":"Changelog","previous_headings":"","what":"Other changes","title":"usethis 2.1.6","text":"use_roxygen_md() gains overwrite argument (#1599). use_rscloud_badge() new function creates README badge indicating repository can launched RStudio Cloud project (@gvelasq, #1584). use_data() gains ascii argument, passed along save() (@JosiahParry, #1625). use_code_of_conduct() updated version 2.1 Contributor Covenant (@batpigandme, #1591).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-215","dir":"Changelog","previous_headings":"","what":"usethis 2.1.5","title":"usethis 2.1.5","text":"CRAN release: 2021-12-09 pkgdown-related functions longer automatically strip trailing slash pkgdown site URL, order play nicely CRAN’s URL checks (#1526). edit_pkgdown_config() new function opens pkgdown YAML configuration file current Project, file exists. error thrown reporting unsupported GitHub configuration fixed forward compatibility future version rlang, .e. anticipated rlang v1.0.0. Version 2.1.4 never released. Version advanced 2.1.4 2.1.5 strictly CRAN (re-)submission purposes.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-213","dir":"Changelog","previous_headings":"","what":"usethis 2.1.3","title":"usethis 2.1.3","text":"CRAN release: 2021-10-27 Modified test ensure intermittent GitHub rate limiting lead ungraceful failure CRAN.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-212","dir":"Changelog","previous_headings":"","what":"usethis 2.1.2","title":"usethis 2.1.2","text":"CRAN release: 2021-10-25 git_default_branch_rename() longer errors repos README exists, badge block. git_default_branch_rediscover() prunes defunct remote ref old default branch, e.g. origin/master. Version 2.1.1 never released. Version advanced 2.1.1 2.1.2 strictly CRAN (re-)submission purposes.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-210","dir":"Changelog","previous_headings":"","what":"usethis 2.1.0","title":"usethis 2.1.0","text":"CRAN release: 2021-10-16","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"git-default-branch-support-2-1-0","dir":"Changelog","previous_headings":"","what":"Git default branch support","title":"usethis 2.1.0","text":"usethis sophisticated understanding default branch gains several functions support default branch renaming. git_branch_default() renamed git_default_branch(), place logically new family functions. old name still works, won’t true forever. intended surface case project renamed default branch local repo needs sync . git_default_branch_rediscover() new function helps contributors update local repo (personal fork, applicable) project/repo renames default branch. git_default_branch_rename() new function helps repo owner rename default branch (GitHub locally). git_default_branch_configure() new function set new Git configuration option init.defaultBranch, controls name initial branch new local repos. git_sitrep() exposes init.defaultBranch surfaces sophisticated analysis git_default_branch().","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-github-related-changes-2-1-0","dir":"Changelog","previous_headings":"","what":"Other GitHub-related changes","title":"usethis 2.1.0","text":"git_sitrep() gh_token_help() try even harder help people get happy path respect GitHub PAT (#1400, #1413, #1488, #1489, #1497). minimum version gh bumped help / force people upgrade gh version supports current GitHub PAT formats (@ijlyttle, #1454). use_github_file() new function related use_template(). Instead starting local file, use_github_file() grabs contents arbitrary file GitHub user permission read. supports targeting specific branch, tag, commit can follow symlink (#1407). use_github_file() now powers use_github_action() friends. use_github_release() much diligent using information left behind devtools::submit_cran() devtools::release(). Specifically, applies determining SHA tagged release. SHA, turn, determines consulted versions DESCRIPTION (package version) NEWS.md (release notes) (#1380). use_release_issue() also takes bullets release_questions(), compatibility devtools::release(). git_vaccinate(), edit_git_ignore(), git_sitrep() careful consult, reveal, set core.excludesFile setting user’s Git configuration (#1461). use_github_action_check_full() removed. ’s overkill majority R packages, better use_github_actions() use_github_action_check_standard() (#1490). use_github_pages() use_pkgdown_github_pages() use new method creating empty, orphan gh-pages branch. necessary due new GitHub behaviour, become essentially impossible refer empty tree (#1472). use_github() can create repositories \"internal\" visibility, feature exists within GitHub Enterprise products (#1505).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"package-development-2-1-0","dir":"Changelog","previous_headings":"","what":"Package development","title":"usethis 2.1.0","text":"use_readme_rmd() use_readme_md() longer include CRAN installation instructions initial template; instead, include GitHub-based install instructions otherwise prompt user update instructions (#1507). use_import_from() new function puts @importFrom pkg fun directives package consistent location (@malcolmbarrett, #1377). DESCRIPTION files generated usethis longer include LazyData default, per new CRAN checks; instead, LazyData now added first time use use_data() (@malcolmbarrett, #1404). use_tidy_eval() updated reflect current recommendations using (therefore exposing) tidy eval packages (@lionel-, #1445). use_pkgdown() automatically uses Bootstrap 5 pkgdown version supports (anticipated pkgdown 2.0.0). use_lifecycle() now imports lifecycle::deprecated() (#1419). use_code_of_conduct() now requires contact argument supply contact details reporting CoC violations (#1269). use_package() longer guides user use dependency change made (@malcolmbarrett, #1384).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"aimed-at-the-tidyverse-team-2-1-0","dir":"Changelog","previous_headings":"Package development","what":"Aimed at the tidyverse team","title":"usethis 2.1.0","text":"functions exported anyone use, aimed primarily maintainers tidyverse, r-lib, tidymodels packages. use_tidy_dependencies() new function sets standard dependencies used tidyverse packages, except designed dependency free (#1423). use_tidy_upkeep_issue() new function similar use_release_issue() creates checklist-style issue prompt various updates (#1416). use_tidy_release_test_env() deleted since longer recommend including test environments cran-comments.md. ’s evidence CRAN finds useful, ’s annoying keep --date (#1365). use_tidy_github_labels() new name use_tidy_labels() (#1430). use_tidy_github_actions() takes use_tidy_ci(), now deprecated.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"user-level-configuration-2-1-0","dir":"Changelog","previous_headings":"","what":"User-level configuration","title":"usethis 2.1.0","text":"\"usethis.overwrite\" new option. set TRUE, usethis overwrites existing file without asking user confirmation file inside Git repo. normal Git workflow makes easy see selectively accept/discard proposed changes. behaviour strictly opt-(#1424). Functions provide code load packages .Rprofile now use rlang::check_installed() make sure package installed locally (@malcolmbarrett, #1398). edit_rstudio_prefs() edit_rstudio_snippets() work now case-sensitive OSes, due path fix re: location RStudio’s config files (@charliejhadley, #1420).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-201","dir":"Changelog","previous_headings":"","what":"usethis 2.0.1","title":"usethis 2.0.1","text":"CRAN release: 2021-02-10 functions require package now ask ’d like install . Added edit_template() opening creating files inst/templates (use use_template()) (@malcolmbarrett, #1319). use_article() now creates file vignettes/articles/ (#548). use_lifecycle() updated changes lifecycle workflow (#1323). use_tidy_pkgdown() renamed use_pkgdown_github_pages() since function useful anyone wants automatically publish GitHub pages, just tidyverse team (#1308). use_release_issue() includes bunch minor improvements. importantly, initial CRAN release now include number common things CRAN checks aren’t R CMD check. use_readme_rmd(), use_readme_md(), use_tidy_contributing(), use_tidy_support() use updated logic determining OWNER/REPO spec target repo (#1312).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-200","dir":"Changelog","previous_headings":"","what":"usethis 2.0.0","title":"usethis 2.0.0","text":"CRAN release: 2020-12-10","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"adoption-of-gert-and-changes-to-gitgithub-credential-handling-2-0-0","dir":"Changelog","previous_headings":"","what":"Adoption of gert and changes to Git/GitHub credential handling","title":"usethis 2.0.0","text":"Usethis various functions help Git-related tasks, break two categories: Git tasks, clone, push, pull. things command line Git. GitHub tasks, fork, release, open issue pull request. things browser GitHub API. ’ve switched git2r gert package Git operations (https://docs.ropensci.org/gert/). continue use gh package GitHub API work (https://gh.r-lib.org). big news area lower-level dependencies getting better finding Git credentials, finding credentials command line Git (, therefore, RStudio), finding credentials . allows usethis shed workarounds needed past, serve remedial “credential valet”. hood, gert gh now consulting local Git credential store, need credentials. time writing, using two different even-lower-level packages : gert uses credentials package (https://docs.ropensci.org/credentials/) gh uses gitcreds package (https://gitcreds.r-lib.org/) Even now, gert gh discover credentials, least github.com. future, two packages may merge one. Git/GitHub credential management covered new article: Managing Git(Hub) Credentials main user-facing changes usethis : usethis discover use credentials command line Git. usethis able work GitHub deployment. github.com default, GitHub Enterprise deployments fully supported. target GitHub host determined current project’s configured GitHub remotes, whenever possible. result, several functions deprecated several functions deprecated arguments. use_git_credentials() git_credentials() github_token() create_from_github() (auth_token, credentials) use_github() (auth_token, credentials) use_github_links() (host, auth_token) use_github_labels() (repo_spec, host, auth_token) use_tidy_labels() (repo_spec, host, auth_token) use_github_release() (host, auth_token) switch gert + credentials eliminate credential-finding fiascos. Gert also takes different approach wrapping libgit2, underlying C library Git operations. result consistent support SSH TLS, across operating systems, without requiring special effort install time. users enjoy Git remote operations “just work”, SSH HTTPS remotes. fewer “unsupported protocol” errors.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"github-remote-configuration-2-0-0","dir":"Changelog","previous_headings":"","what":"GitHub remote configuration","title":"usethis 2.0.0","text":"Usethis gains formal framework characterizing GitHub remote configuration. look : GitHub repositories origin upstream point Whether can push relate , e.g. fork-parent relationship internal matter, users notice usethis clear configurations supported various functions . common configurations reviewed section Happy Git. working fork, sometimes question whether target fork parent repository. example, use_github_links() adds GitHub links URL BugReports fields DESCRIPTION. someone calls use_github_links() working fork, probably want links refer parent source repo, fork, user probably preparing pull request. Usethis now better default behaviour situations , cases, present interactive choice.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"default-branch-2-0-0","dir":"Changelog","previous_headings":"","what":"Default branch","title":"usethis 2.0.0","text":"increasing interest making name repo’s default branch configurable. Specifically, main emerging popular alternative master. Usethis now discovers current repo’s default branch uses everywhere , previously, hard-wired master. git_branch_default() newly exported function also ’s used internally. use_course(), use_zip(), create_download_url() support forming URL download .zip archive repo, based repo specification (e.g. OWNER/REPO) browser URL. helpers now form URL targets HEAD repo, .e. default branch.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"changes-to-gitgithub-functionality-2-0-0","dir":"Changelog","previous_headings":"","what":"Changes to Git/GitHub functionality","title":"usethis 2.0.0","text":"default Git protocol now “https” longer provide interactive choice, default, interactive sessions. always, user can express preference “ssh” individual function calls, R session via use_git_protocol(), R sessions via usethis.protocol option (#1262). pr_resume() new function resuming work existing local PR branch. can called argument-less, select branch interactively. pr_fetch() can also called arguments, select PR interactively. owner argument replaced target, choice source (default) primary repo. pr_forget() new function abandoning PR initiated locally fetched GitHub. local clean , example, doesn’t delete remote branch close PR (#1263). pr_view() can now called arguments. current branch associated open PR, target , otherwise, offer interactive selection. pr_finish() deletes remote PR branch PR merged current user power , .e. external contributor deleting branch maintainer deleting branch associated internal PR (#1150). longer errors PR branch already deleted (#1196). pr_pull_upstream() renamed pr_merge_main() emphasize merges main line development current branch, main line development taken mean default branch, reported git_branch_default(), source repo, either upstream origin, depending situation. create_from_github() create read-clone, due lack GitHub personal access token, explicitly directed via fork = FALSE. create_from_github() use_tidy_thanks() accept browser Git URLs repo_spec argument, friendlier copy/paste. URL passed, host also extracted . create_github_token() new name function previously known browse_github_token() browse_github_pat(). issue_close_community() issue_reprex_needed() two new functions maintainers process lots GitHub issues. automate canned replies actions, e.g. labelling closing (#940). GitHub Actions preferred platform continuous integration, tidyverse team currently uses maintains. Functions related Travis-CI AppVeyor soft-deprecated raise awareness change make clear , substantial maintenance becomes necessary, may elect retire function (#1169). browse_github_actions() new function open Actions page respective repo GitHub, similar existing browse_*() functions (@pat-s, #1102). use_github_pages() new function activate reconfigure GitHub Pages site associated repository (#224). use_tidy_pkgdown() implements complete pkgdown configuration used tidyverse team (#224). pr_sync() deprecated can replicated calling pr_pull(), pr_merge_main(), pr_push().","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"licensing-improvements-2-0-0","dir":"Changelog","previous_headings":"","what":"Licensing improvements","title":"usethis 2.0.0","text":"use_*_license() functions now work projects, just packages. use_apl2_license() (use_apache_license()) use_gpl3_license() longer modify license text (#1198). use_mit_license() now sets default copyright holder “{package} authors”. makes clear copyright holders contributors package; unless using CLA one copyright holder package (#1207). New use_gpl_license() use_agpl_license() make easier pick specific versions GPL AGPL licenses, choose whether include future versions license. default version 3 (). New use_proprietary_license() allows package pass R CMD check making clear code open source (#1163). Thanks @atheriel blog post suggesting wording: https://unconj.ca/blog/copyright--closed-source-r-packages--right-way.html use_lgpl_license() now uses version 3 (), gains new version include_future argument control version used. use_gpl3_license(), use_agpl3_license() use_apl2_license() deprecated favour new version argument use_gpl_license(), use_agpl_license() use_apache_license(). name argument use_mit_license() changed copyright_holder make purpose clear. name argument removed license functions needed; license makes assertion copyright holder .","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"rstudio-preferences-2-0-0","dir":"Changelog","previous_headings":"","what":"RStudio preferences","title":"usethis 2.0.0","text":"usethis now fully cognizant changes RStudio preferences RStudio 1.3: edit_rstudio_snippets() looks new location, snippets old location, automatically copy new location (#1204) New edit_rstudio_prefs() opens RStudio preferences file editing (#1148). use_blank_slate() can now configure global, .e. user-level, RStudio preference, addition project-level (#1018).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-changes-2-0-0","dir":"Changelog","previous_headings":"","what":"Other changes","title":"usethis 2.0.0","text":"browse_package() browse_project() new functions let user choose list URLs derived local Git remotes DESCRIPTION (local possibly CRAN) (#1113). legacy \"devtools.desc\" option longer consulted populating new DESCRIPTION file. must use \"usethis.description\" now (#1069). use_dev_package() gains remote parameter allow specify remote. existing behaviour, adds OWNER/REPO GitHub remote, remains default (#918, @ijlyttle). use_cpp11() new function set R package use cpp11. create_package(roxygen = FALSE) writes valid NAMESPACE file (also Roxygen* fields DESCRIPTION) (#1120). create_package(), create_project(), create_from_github(), proj_activate() work better relative paths, inside outside RStudio (#1122, #954). use_testthat() gains edition argument support testthat v3.0.0 (#1185) use_version() now updates src/version.c exists contains line matching PKG_version = \"x.y.z\";. usethis re-licensed MIT (#1252, #1253).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"dependency-changes-2-0-0","dir":"Changelog","previous_headings":"","what":"Dependency changes","title":"usethis 2.0.0","text":"New Imports: gert, jsonlite (already indirect dependency), lifecycle, rappdirs longer Imports: git2r, rematch2","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-163","dir":"Changelog","previous_headings":"","what":"usethis 1.6.3","title":"usethis 1.6.3","text":"CRAN release: 2020-09-17 Patch release refactor usage withr tests forward compatibility upcoming withr release. changes within usethis tests.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-161","dir":"Changelog","previous_headings":"","what":"usethis 1.6.1","title":"usethis 1.6.1","text":"CRAN release: 2020-04-29 Patch release align path handling internals update coming fs package. use_github_links() bit clever remotes (e.g. origin vs. upstream), makes easier make PR adds GitHub links package ’ve forked. use_pkgdown() now .gitignores destination directory adds destination directory config file departs default (docs/). use_tidy_ci() now deprecated favour use_tidy_github_actions() (#1098). use_github_action_check_standard() new intermediate workflow checks platforms _release, less exhaustive _full (@jimhester). create_tidy_package() now uses MIT license (@topepo, #1096).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-160","dir":"Changelog","previous_headings":"","what":"usethis 1.6.0","title":"usethis 1.6.0","text":"CRAN release: 2020-04-09","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"github-actions-1-6-0","dir":"Changelog","previous_headings":"","what":"GitHub actions","title":"usethis 1.6.0","text":"New use_github_actions(), use_github_action_check_release(), use_github_action_check_full(), use_github_action_pr_commands(), set GitHub Actions package (@jimhester). now recommend GitHub Actions instead Travis-CI AppVeyor, strongly recommend upgrading packages. Fix use_github_action() URL parameter ensure custom URLs allowed. (@coatless, #1065).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"package-creation-1-6-0","dir":"Changelog","previous_headings":"","what":"Package creation","title":"usethis 1.6.0","text":"create_package() gains roxygen argument. TRUE (default), adds RoxygenNote field DESCRIPTION (means first run devtools::check() re-document package, #963), creates empty NAMESPACE (means ’ll always need explicit @export want export functions, #927). also turns markdown processing default (#911). use_rstudio() now sets LineEndingConversion Posix packages created using usethis always use LF line endings, regardless contributes (#1002). usethis.description option, can now set Authors@R = person() directly, without wrap additional layer quotes. setting .Rprofile, ’ll need use utils::person() since utils package isn’t loaded profile executed.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"pr-helpers-1-6-0","dir":"Changelog","previous_headings":"","what":"PR helpers","title":"usethis 1.6.0","text":"new article Pull request helpers demonstrates use pr_*() functions (@mine-cetinkaya-rundel, #802). pr_finish() checks don’t local changes (#805), can optionally finish PR, just current (#1040). pr_pause() pr_fetch() now automatically pull get latest changes (#959, #960) refresh RStudio’s git pane (#706). pr_push() now works repository open pull requests (@maurolepore, #990). pr_pull() gives information files merge conflicts automatically opens conflicted files editing (#1056).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-new-features-1-6-0","dir":"Changelog","previous_headings":"","what":"Other new features","title":"usethis 1.6.0","text":"New rename_files() makes easy rename paired R/ test/ files (#784). New ui_silence() makes easier selectively silence UI output. New use_agpl3_license() (@pachamaltese, #870). New use_data_table() set package Import-ing data.table (@michaelchirico, #897). use_latest_dependencies() replaces use_tidy_version() new name better reflect usage (#771). New use_lifecycle() helper import lifecycle badges functions arguments package. Learn https://lifecycle.r-lib.org/. use_release_issue() include additional bullets package includes release_bullets() function returns character vector (package loaded load_all()) (#941).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"minor-improvements-and-bug-fixes-1-6-0","dir":"Changelog","previous_headings":"","what":"Minor improvements and bug fixes","title":"usethis 1.6.0","text":"writing files, usethis now respects line endings. Default line endings taken .Rproj file (available), otherwise DESCRIPTION, otherwise first file found R/, else failing platform default (#767). better job preserving UTF-8 files windows (#969). browse_github() now always goes canonical GitHub site: https://github.com/user/repo. slightly worse current behaviour makes function consistent across packages, considerably simplifies implementation. browse_circle() opens project dashboard Circle CI. create_download_url() new helper making “ZIP file download” URLs suitable use use_course() use_zip(), starting URLs mere mortals can usually get hands browser (@fmichonneau, #406). create_package() longer fails partway malformed usethis.description option (#961). create_package() now create package symlink directory (#794). create_package() use_description() gain check_name argument control whether check package names invalid CRAN (@noamross, #883). edit_file() use_test() gain open parameter allows control whether function opened editing user (#817). edit_rstudio_snippets() makes clear snippet types allowed user’s snippets mask built-snippets (@GegznaV, #885). git_sitrep() now reports project-specific user name email, set (#837), email(s) associated GitHub account (@dragosmg, #724). ui_yeah() ui_nope() allow override default “yes” “” strings opt-shuffling (@rundel, #796). use_circleci() uses correct delimiters template (@jdblischak, #835). use_circleci_badge() now exported (@pat-s, #920). use_code_of_conduct() now generates absolute link code conduct pkgdown website original source avoid R CMD check issues (#772). use_course() use_zip() now equipped retry capability, cope intermittent failure need longer connect timeout (#988). use_data() automatically bumps R dependency 2.10 (#962). use_data_raw() template quotes dataset name correctly (#736, @mitchelloharawild). use_description_defaults() now shows default fields combined options set. use_dev_package() now supports packages installed remote type, just GitHub (@antoine-sachet, #1071). use_git() now create initial commit needed (#852). use_github_release() longer fails news bullets (#1048). use_github_release() now tags latest local commit instead latest remote commit default branch (@davidchall, #1029). use_gpl3_license() now completes license providing additional information file named LICENSE, just like use_mit_license() friends (@Cervangirard, #683). use_logo() now generates correct href pkgdown url set (@mitchelloharawild, #986). use_make() gains missing closing parenthesis (@ryapric, #804). use_markdown_template() longer uses unexported function default arguments (@fmichonneau, #761). use_testthat() use_test() now work projects, just packages (#1017). use_test() works Windows called without arguments (#901). use_tidy_issue_template() uses current github format (@Maschette, #756). use_travis(), use_travis_badge(), browse_travis(), now default ext = \"com\" since travis-ci.com now recommended travis-ci.org (@riccardoporreca, #1038). use_release_issue() reminds re-generate README.md, needed (#767). use_r() use_test() throw clear error multiple names provided (@strboul, #862). use_rcpp() use_c() now ensure src/ contains least one .cpp .c placeholder file, package can built (@coatless, #720). usethis.destdir new option consulted deciding put new folder created use_course() create_from_github() (@malcolmbarrett, #1015). use_lifecycle() longer adds lifecycle package DESCRIPTION file. new roxygen markdown syntax including badges, lifecycle become build-time dependency.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"dependency-changes-1-6-0","dir":"Changelog","previous_headings":"","what":"Dependency changes","title":"usethis 1.6.0","text":"New Imports: cli, rematch2, rlang. gh minimum version bumped v.1.1.0, due changed behaviour around requests return nothing. clisymbols removed Imports.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-151","dir":"Changelog","previous_headings":"","what":"usethis 1.5.1","title":"usethis 1.5.1","text":"CRAN release: 2019-07-04 patch release various small features bug fixes.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"using-the-pipe--or-the-tidy-eval-toolkit-in-your-package-1-5-1","dir":"Changelog","previous_headings":"","what":"Using the pipe %>% or the tidy eval toolkit in your package","title":"usethis 1.5.1","text":"templates used use_pipe() use_tidy_eval() use robust form cross-reference links, linking files rather topics. silence warnings seen Windows install time (#730, #731 @jmgirard). use_pipe() gains logical export argument, can setup necessary use pipe operator re-exported (export = TRUE, default preserves previous behaviour) (export = FALSE) (#783).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"git-github-and-pull-requests-1-5-1","dir":"Changelog","previous_headings":"","what":"Git, GitHub, and pull requests","title":"usethis 1.5.1","text":"use_github() removes newline \\n characters description can cause initial push fail (#493, @muschellij2). git_sitrep() gives better feedback can’t validate GitHub PAT (#725, @ijlyttle). create_from_github() sets remote tracking branch master upstream/master, creates (clones) fork (#792). pr_pause() can switch back master even remote tracking branch (#715, @cderv).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"build-tools-and-continuous-integration-1-5-1","dir":"Changelog","previous_headings":"","what":"Build tools and continuous integration","title":"usethis 1.5.1","text":"use_tidy_ci() updated R 3.6, meaning R 3.2 oldest version R supported proactive testing. use_make() use_jenkins() add Makefile Jenkinsfile, respectively (#501, @ryapric). use_circleci() creates .circleci/config.yaml config file CircleCI (#703, @jdblischak).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-1-5-1","dir":"Changelog","previous_headings":"","what":"Other","title":"usethis 1.5.1","text":"use_zip() new variant use_course() downloads unpacks ZIP file, less pedantic behaviour re: destination directory. functions now also work ZIP files MIME type \"application/x-zip-compressed\" (#573). use_version() can detect \"(development version)\" NEWS header update actual version (#768, @DavisVaughan).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"dependency-changes-1-5-1","dir":"Changelog","previous_headings":"","what":"Dependency changes","title":"usethis 1.5.1","text":"R 3.1 longer explicitly supported tested. general practice support current release (3.6, time writing), devel, 4 previous versions R (3.5, 3.4, 3.3, 3.2). fs minimum version stated v1.3.0. glue minimum version stated v1.3.0.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-150","dir":"Changelog","previous_headings":"","what":"usethis 1.5.0","title":"usethis 1.5.0","text":"CRAN release: 2019-04-07","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"git-github-and-gitlab-1-5-0","dir":"Changelog","previous_headings":"","what":"Git, GitHub (and GitLab)","title":"usethis 1.5.0","text":"usethis gains several functions inspect manipulate Git situation current project = repository. also provide control visibility git2r’s workings, especially around credentials (usethis uses git2r Git operations). git_sitrep() lets know ’s Git, git2r GitHub config (#328). git_vaccinate() vaccinates global (.e. user-level) git ignore file. adds standard entries R users, .Rhistory .Rdata. decreases chance commit push files containing confidential information (#469). git_remotes() use_git_remote() new helpers inspect modify Git remote URLs repo associated active project (#649). git_protocol() + use_git_protocol() git_credentials() + use_git_credentials() new helpers summon set Git transport protocol (SSH HTTPS) git2r credentials, respectively. functions primarily internal use. users can rely default behaviour. Use helpers intervene git2r isn’t discovering right credentials (#653). usethis honors usethis.protocol option, allows express general preference SSH vs. HTTPS. improvements bug fixes: use_github() tries harder also fails earlier, informative messages, making less likely leave repo partially configured (#221). use_github() create_from_github() gain protocol argument (#494, @cderv). create_from_github() pulls upstream master fork (#695, @ijlyttle). use_release_issue() creates GitHub issue containing release checklist, reflecting standard practices tidyverse team (#338). use_github_release() creates draft GitHub release using entries NEWS.md (#137). use_gitlab_ci() creates gitlab-ci.yaml config file GitLab CI (#565, @overmar). use_git_config() now invisibly returns previous values settings. use_github_labels() rewritten flexible. can now supply repo name, descriptions, can set colours/descriptions independently creating labels. can also rename existing labels (#290).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"github-pull-requests-1-5-0","dir":"Changelog","previous_headings":"","what":"GitHub pull requests","title":"usethis 1.5.0","text":"’ve added experimental functions work GitHub pull requests. aimed maintainer (may make, review, modify pull requests) contributor (may make explore pull requests). git_sitrep() includes section end aimed describing “pull request readiness”. Expect develop expand. pr_init(), pr_fetch(), pr_push(), pr_pull(), pr_finish(), pr_view() constitute new family helpers. designed smart significance remotes standard names origin upstream facilitate internal external pull requests.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"partial-file-management-1-5-0","dir":"Changelog","previous_headings":"","what":"Partial file management","title":"usethis 1.5.0","text":"usethis gains tooling manage part file. currently used managing badges README roxygen import tags: use_badge() friends now automatically add badges README contains specially formatted badge block (#497): use_tibble() use_rcpp() automatically add roxygen tags {package}-package.R contains specially formatted namespace block (#517): Unfortunately means use_rcpp() longer supports non-roxygen2 workflows, suspect set people use usethis Rcpp roxygen2 small.","code":"<-- badge:start --> <-- badge:end --> ## usethis namespace: start ## usethis namespace: end NULL"},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"extending-and-wrapping-usethis-1-5-0","dir":"Changelog","previous_headings":"","what":"Extending and wrapping usethis","title":"usethis 1.5.0","text":"New proj_activate() lets activate project, either opening new RStudio session (use RStudio) changing working directory (#511). proj_get() proj_set() longer quiet argument. user-facing message setting project now control messages, .e. getOption(\"usethis.quiet\", default = FALSE) (#441). new set ui_*() functions makes possible give code user interface usethis (#308). use glue crayon packages power easy interpolation formatting. four families functions: block styles: ui_line(), ui_done(), ui_todo(), ui_oops(), ui_info(). conditions: ui_stop(), ui_warn(). questions: ui_yeah(), ui_nope(). inline styles: ui_field(), ui_value(), ui_path(), ui_code(). with_project() local_project() new withr-style functions temporarily set active usethis project. make usethis functions easier use ad hoc fashion another package (#441).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"tidyverse-standards-1-5-0","dir":"Changelog","previous_headings":"","what":"Tidyverse standards","title":"usethis 1.5.0","text":"standards (aspirationally) used tidyverse packages; welcome use find helpful. Call use_tidy_labels() update GitHub labels. Colours less saturated, docs now documentation, use emoji, performance longer automatically added repos (#519). Repo specific issues given colour #eeeeee emoji. Call use_logo() update package logo latest specifications: man/figure/logo.png 240 x 278, README contain . gives nicer display retina displays. logo also linked pkgdown site available (#536). creating new package, use create_tidy_package() start package following tidyverse standards (#461). NEWS.md development version use “(development version)” rather specific version (#440). pkgdown sites now built travis deployed automatically GitHub pages. use_pkgdown_travis() help set . starting release process, call use_release_issue() create release checklist issue (#338). Prior CRAN submission call use_tidy_release_test_env() update test environment section cran-comments() (#496). acceptance, try use_github_release() automatically create release. ’s created draft chance look publishing. use_vignette() includes standard initialisation chunk knitr::opts_chunk$set(comment = \"#>\", collapse = TRUE) used Rmds.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-functions-not-already-mentioned-1-5-0","dir":"Changelog","previous_headings":"","what":"New functions not already mentioned","title":"usethis 1.5.0","text":"use_devtools() (#624), use_conflicted() (#362), use_reprex() (#465) help add useful packages .Rprofile. use_partial_warnings() helps user add standard warning block .Rprofile (#64). edit_r_buildignore() opens .Rbuildignore manual editing (#462, @bfgray3). use_lgpl_license() automates set LGL license (#448, @krlmlr). use_ccby_license() adds CCBY 4.0 license (#547, @njtierney). use_rcpp_armadillo() use_rcpp_eigen() set package use RcppArmadillo RcppEigen, respectively (#421, @coatless, @duckmayr). use_c(\"foo\") sets src/ creates src/foo.c (#117). use_covr_ignore() makes easy ignore files test coverage (#434). use_pkgdown_travis() helps set pkgdown automatic build--deploy Travis-CI GitHub Pages (#524). use_addin() setup RStudio addins (#353, @haozhu233). use_tutorial() creates new interactive R Markdown tutorial, implemented learnr package (@angela-li, #645). use_article() creates articles, vignettes automatically added .Rbuildignore. appear pkgdown sites, included package (#281). use_citation() creates basic CITATION template puts right place (#100).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-minor-bug-fixes-and-improvements-1-5-0","dir":"Changelog","previous_headings":"","what":"Other minor bug fixes and improvements","title":"usethis 1.5.0","text":"write_union() appends novel lines, remove duplicates existing lines (#583, @khailper). use_rcpp(\"foo\") now creates src/foo.cpp (#117). use_data() gains version argument defaults serialization format version 2 (#675). use_data_raw() accepts name --prepared dataset opens templated R script (#646). browse_github() now falls back CRAN organisation (warning) package doesn’t GitHub repo (#186). create_*() restore active project error part way , use proj_activate() (#453, #511). edit_r_profile() edit_r_environ() now respect environment variables R_PROFILE_USER R_ENVIRON_USER, respectively (#480). use_description() prints generated description (#287). use_description_field() longer sensitive whitespace, allows use_vignette() work even VignetteBuilder field spread multiple lines (#439). use_logo() can override existing logo user gives permission (#454). also produces retina appropriate logos default, matches aspect ratio http://hexb./sticker.html specification (#499). use_news_md() optionally commit. use_package() gains min_version argument specify minimum version requirement (#498). Set TRUE use currently installed version (#386). used use_tidy_eval() order require version 0.1.2 greater rlang (#484). use_pkgdown() now configurable site options (@jayhesselberth, #467), longer creates docs/ directory (#495). use_test() longer forces filename lowercase (#613, @stufield). use_test() include context() generated file used testthat 2.1.0 (future release testthat) (#325). use_tidy_description() sets Encoding field DESCRIPTION (#502, @krlmlr). use_tidy_eval() re-exports := (#595, @jonthegeek). use_tidy_versions() source argument can choose use local CRAN versions (#309). use_travis() gains ext argument, defaulting \"org\". Use ext = \"com\" https://travis-ci.com (@cderv, #500). use_version() asks committing. use_vignette() now title argument used YAML header (two places needed). vignettes also lose default author date fields (@rorynolan, #445), R Markdown starter material. gain standard setup chunk. use_version(\"dev\") now creates standard “(development version)” heading NEWS.md (#440). use_vignette() now checks vignette name valid (starts letter consists letters, numbers, hyphen, underscore) throws error (@akgold, #555). restart_rstudio() now returns FALSE RStudio project open, fixing issue caused errors helpers suggest restarting RStudio (@gadenbuie, #571).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"dependency-changes-1-5-0","dir":"Changelog","previous_headings":"","what":"Dependency changes","title":"usethis 1.5.0","text":"withr moves Suggests Imports. purrr yaml new Imports.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-140","dir":"Changelog","previous_headings":"","what":"usethis 1.4.0","title":"usethis 1.4.0","text":"CRAN release: 2018-08-14","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"file-system-1-4-0","dir":"Changelog","previous_headings":"","what":"File system","title":"usethis 1.4.0","text":"usethis file system operations now use fs package (#177). change usethis functions, users may notice features fs-mediated paths: Paths “tidy”, meaning / path separator never multiple trailing /. Paths UTF-8 encoded. Windows user’s home directory interpreted C:\\Users\\username (typical Unix-oriented tools, like Git ssh; also matches Python), opposed C:\\Users\\username\\Documents (R’s default Windows). Read fs::path_expand().","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"extending-or-wrapping-usethis-1-4-0","dir":"Changelog","previous_headings":"","what":"Extending or wrapping usethis","title":"usethis 1.4.0","text":"changes make easier others extend usethis, .e. create workflow packages specific organization, use usethis packages. proj_path() newly exported. Use build paths within active project. Like proj_get() proj_set(), aimed end users, rather use extension packages. End users use rprojroot simpler companion, , programmatically detect project build paths within (#415, #425). edit_file(), write_over(), write_union() newly exported helpers. mostly internal use, can also useful packages extend customize usethis (#344, #366, #389). use_template() longer errors user chooses overwrite existing file simply exits confirmation file unchanged (#348, #350, @boshek). getOption(\"usethis.quiet\", default = FALSE) consulted printing user-facing messages. Set option TRUE suppress output, e.g., use usethis functions quietly another package. example, use withr::local_options(list(usethis.quiet = TRUE)) calling function (#416, #424).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-functions-1-4-0","dir":"Changelog","previous_headings":"","what":"New functions","title":"usethis 1.4.0","text":"proj_sitrep() reports current working directory, active usethis project, active RStudio Project. Call function things seem weird ’re sure ’s wrong fix . Designed interactive use debugging, programmatic use (#426). use_tibble() minimum setup necessary package returns exports tibble. example, guarantees tibble print tibble (#324 @martinjhnhadley). use_logo() resizes adds logo package (#358, @jimhester). use_spell_check() adds whitelist words unit test spell check package documentation R CMD check (#285 @jeroen).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-small-changes-and-bug-fixes-1-4-0","dir":"Changelog","previous_headings":"","what":"Other small changes and bug fixes","title":"usethis 1.4.0","text":"usethis new logo! (#429) use_course() reports progress download (#276, #380). use_git() makes initial commit files user gives explicit consent (#378). create_from_github(): repo argument renamed repo_spec, since takes input form “OWNER/REPO” (#376). use_depsy_badge() deprecated. Depsy project officially concluded longer maintained (#354). use_github() fails earlier, informative message, absence GitHub personal access token (PAT). Also looks PAT proactively usual environment variables (.e., GITHUB_PAT, GITHUB_TOKEN) (#320, #340, @cderv). logic setting DESCRIPTION fields create_package() use_description() got Spring Cleaning. Fields directly specified user take precedence, named list getOption(\"usethis.description\") consulted, finally defaults built usethis. use_description_defaults() new function reveals fields found options built usethis. Options specific one DESCRIPTION field, e.g. devtools.desc.license, longer supported. Instead, use single named list fields, preferably stored option named \"usethis.description\" (however,\"devtools.desc\" still consulted backwards compatibility). (#159, #233, #367)","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"dependency-changes-1-4-0","dir":"Changelog","previous_headings":"","what":"Dependency changes","title":"usethis 1.4.0","text":"New Imports: fs, glue, utils longer Imports: backports, httr, rematch2, rmarkdown (moved Suggests), styler (moved Suggests)","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-130","dir":"Changelog","previous_headings":"","what":"usethis 1.3.0","title":"usethis 1.3.0","text":"CRAN release: 2018-02-24 usethis website: https://usethis.r-lib.org (#217). includes article advice system setup, usethis R development generally. edit_*() functions now return target path, invisibly (#255). edit_git_ignore(scope = \"user\") prefers ~/.gitignore, detects existing ~/.gitignore_global, exists. new global gitignore file created, created ~/.gitignore recorded user’s git config core.excludesfile (#255). create_from_github() gains several arguments new functionality. protocol argument lets user convey whether remote URLs ssh https. case “fork clone”, original repo added upstream remote. now possible – although rarely necessary – directly specify GitHub PAT, credentials (git2r form), GitHub host (#214, #214, #253). use_github_labels() can create update colour arbitrary GitHub issue labels, defaulting set labels colours used tidyverse packages, now exposed via tidy_labels(). set now includes labels “good first issue” “help wanted” (#168, #249). appveyor_info() longer reverses repo’s URL image link. Corrects markdown produced use_appveyor_badge() (#240, @llrs). use_cran_badge() uses HTTPS URL CRAN badge image (#235, @jdblischak). create_package() create_project() return normalized path, even target directory pre-exist (#227, #228).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-functions-1-3-0","dir":"Changelog","previous_headings":"","what":"New functions","title":"usethis 1.3.0","text":"use_git_config() can set user’s Git name email, globally locally project/repo (#267). browse_github_pat() goes webpage GitHub user can create personal access token (PAT) GitHub API. user configures PAT, can use functions like create_from_github() use_github() easily create connect GitHub repos local projects. (#248, #257, @jeroen, via @jennybc). use_version() increments version active package, including interactive chooser. use_dev_version() now special case wrapper around . (#188, #223, @EmilHvitfeldt). use_tidy_github() creates standard set files make GitHub repository navigable users contributors: issue template, contributing guidelines, support documentation, code conduct. now placed .github/ subdirectory (#165, @batpigandme). use_bioc_badge creates Bioconductor badge links build report (#271, @LiNk-NY). use_binder_badge() creates badge indicating repository can launched executable environment via Binder (#242, @uribo).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-120","dir":"Changelog","previous_headings":"","what":"usethis 1.2.0","title":"usethis 1.2.0","text":"CRAN release: 2018-01-19","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-functions-1-2-0","dir":"Changelog","previous_headings":"","what":"New functions","title":"usethis 1.2.0","text":"use_course() downloads folder’s worth materials ZIP file, deliberate choices around default folder name location. Developed use start workshop. Helps participants obtain materials , e.g., DropBox folder GitHub repo (#196). use_blank_slate() provides way opt RStudio workflow user’s workspace neither saved reloaded R sessions. Automated scope = \"project\". Provides UI instructions scope = \"user\", now (#139). use_tidy_style() styles entire project according https://style.tidyverse.org (#72, #197 @lorenzwalthert). GitHub conventions common tidyverse packages enacted use_tidy_contributing(), use_tidy_issue_template(), use_tidy_support() (@batpigandme, #143, #166). changes New projects don’t exhibit obvious criteria “project” include sentinel, empty file named ., can recognized project. Project launching switching works RStudio server (#115, #129). use_template() newly exported, packages can provide templating functions using framework (@ijlyttle #120). use_readme_rmd() use_readme_md() work, similar fashion, projects package (#131, #135). use_readme_rmd() creates pre-commit git hook, help keep README.Rmd README.md sync (@PeteHaitch #41). Substantial increase unit test coverage.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-110","dir":"Changelog","previous_headings":"","what":"usethis 1.1.0","title":"usethis 1.1.0","text":"CRAN release: 2017-11-17","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-helpers-1-1-0","dir":"Changelog","previous_headings":"","what":"New helpers","title":"usethis 1.1.0","text":"browse_github(), browse_github_issues(), browse_github_pulls(), browse_cran() browse_travis() open useful websites related current project named package. (#96, #103). create_from_github() creates project existing GitHub repository, forking needed (#109). use_cc0_license() applies CC0 license, particularly appropriate data packages (#94) use_lifecycle_badge() creates badge describing current stage project lifecycle (#48). use_pkgdown() creates basics needed pkgdown website (#88). use_r(\"foo\") creates edit R/foo.R file. test file open, use_r() open corresponding .R file (#105). use_tidy_versions() sets minimum version requirement dependencies.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"bug-fixes-and-improvements-1-1-0","dir":"Changelog","previous_headings":"","what":"Bug fixes and improvements","title":"usethis 1.1.0","text":"use_dev_version() now correctly updates Version field package description file. (@tjmahr, #104) use_revdep() now also git-ignores SQLite database (#107). use_tidy_eval() tweaked reflect current guidance (#106)","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-100","dir":"Changelog","previous_headings":"","what":"usethis 1.0.0","title":"usethis 1.0.0","text":"CRAN release: 2017-10-22 new package extracts many functions previously lived devtools, well providing building blocks can create helpers. well many new helpers listed , three main improvements package: support general R projects, packages. notion “active” project commands operate . Refined output. usethis gradually evolving towards supporting general R “projects”, just packages. still work progress, please let know use function think work projects doesn’t. can also try new create_project() creates basic RStudio project. concept working directory “base path” refined. Rather using argument specify active project, use_ functions now use global active project setting, returned proj_get(). cached throughout session, although updated create_package() create_project(). ’ll now get clear error attempt use_something() outside project, create_something() warn ’re trying create inside existing project. output usethis commands reviewed informative overwhelming. usethis takes advantage colour (using crayon RStudio 1.1) help chunk output clearly differentiate need vs. done .","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-functions-1-0-0","dir":"Changelog","previous_headings":"","what":"New functions","title":"usethis 1.0.0","text":"use_apl2_license() want use Apache 2.0 license. use_depsy_badge() allows including Depsy badge (@gvegayon, #68). use_dev_package() works like use_package() also adds repo Remotes field (#32). use_github_labels() automatically set standard set labels, optionally removing default labels (#1). use_pipe() creates template use magrittr’s %>% package (#15). use_tidy_ci() sets travis codecov using tidyverse conventions (#14) use_tidy_description() puts description fields standard order alphabetises dependencies. use_tidy_eval() imports re-exports recommend set tidy eval helpers package uses tidy eval (#46). use_usethis() opens .Rprofile gives code copy paste .","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-edit-functions-1-0-0","dir":"Changelog","previous_headings":"","what":"New edit functions","title":"usethis 1.0.0","text":"new class functions make easy edit common config files: edit_r_profile_user() opens .Rprofile edit_r_environ_user() opens .Renviron edit_r_makevars_user() opens .R/Makevars edit_git_config_user() opens .gitconfig edit_git_ignore_user() opens .gitignore edit_rstudio_snippets(type) opens ~/R/snippets/{type}.snippets","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"updates-1-0-0","dir":"Changelog","previous_headings":"","what":"Updates","title":"usethis 1.0.0","text":"use_coverage(\"codecov\") now sets default threshold 1% try reduce false positives (#8). use_description() now sets ByteCompile: true can benefit byte compiler (#29) license functions (use_mit_license(), use_apl2_license(), use_gpl3_license()) save copy standard license text LICENSE.md, added .Rbuildignore. allows follow standard licensing best practices adhering CRANs requirements (#10). use_package_doc() uses modern roxygen2 template requires less duplication. use_test() use name currently open file RStudio don’t supply explicit name (#89). use_readme_rmd() now puts images man/figures/ longer adds .Rbuildgnore. ensures rendered README.md also work CRAN (#16, #19). first chunk now uses include = FALSE named setup (#19). use_revdep() creates structure use revdepcheck package, preferred way run revdepchecks. (#33)","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"building-blocks-1-0-0","dir":"Changelog","previous_headings":"","what":"Building blocks","title":"usethis 1.0.0","text":"New use_badge() adding badge README. Now prints todo message badge already exist. use_directory() now exported (#27).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"bug-fixes-and-minor-improvements-1-0-0","dir":"Changelog","previous_headings":"","what":"Bug fixes and minor improvements","title":"usethis 1.0.0","text":"Functions require code copied now automatically put code clipboard available (#52). create_package() longer creates dependency current version use_build_ignore() now strips trailing / use_git() restart RStudio needed (possible) (#42). use_github() now organisation parameter can create repos organisations (#4). use_template() use_test() now convert title slug contains lowercase letters, numbers, -. use_vignette() now adds *.html *.R .gitgnore don’t accidentally add compiled vignette products (#35). use_travis_badge() use_appveyor_badge() now exported functions, can used even ci separately set (#765, @smwindecker).","code":""}] +[{"path":[]},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"our-pledge","dir":"","previous_headings":"","what":"Our Pledge","title":"Contributor Covenant Code of Conduct","text":"members, contributors, leaders pledge make participation community harassment-free experience everyone, regardless age, body size, visible invisible disability, ethnicity, sex characteristics, gender identity expression, level experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, sexual identity orientation. pledge act interact ways contribute open, welcoming, diverse, inclusive, healthy community.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"our-standards","dir":"","previous_headings":"","what":"Our Standards","title":"Contributor Covenant Code of Conduct","text":"Examples behavior contributes positive environment community include: Demonstrating empathy kindness toward people respectful differing opinions, viewpoints, experiences Giving gracefully accepting constructive feedback Accepting responsibility apologizing affected mistakes, learning experience Focusing best just us individuals, overall community Examples unacceptable behavior include: use sexualized language imagery, sexual attention advances kind Trolling, insulting derogatory comments, personal political attacks Public private harassment Publishing others’ private information, physical email address, without explicit permission conduct reasonably considered inappropriate professional setting","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"enforcement-responsibilities","dir":"","previous_headings":"","what":"Enforcement Responsibilities","title":"Contributor Covenant Code of Conduct","text":"Community leaders responsible clarifying enforcing standards acceptable behavior take appropriate fair corrective action response behavior deem inappropriate, threatening, offensive, harmful. Community leaders right responsibility remove, edit, reject comments, commits, code, wiki edits, issues, contributions aligned Code Conduct, communicate reasons moderation decisions appropriate.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"scope","dir":"","previous_headings":"","what":"Scope","title":"Contributor Covenant Code of Conduct","text":"Code Conduct applies within community spaces, also applies individual officially representing community public spaces. Examples representing community include using official e-mail address, posting via official social media account, acting appointed representative online offline event.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"enforcement","dir":"","previous_headings":"","what":"Enforcement","title":"Contributor Covenant Code of Conduct","text":"Instances abusive, harassing, otherwise unacceptable behavior may reported community leaders responsible enforcement codeofconduct@posit.co. complaints reviewed investigated promptly fairly. community leaders obligated respect privacy security reporter incident.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"enforcement-guidelines","dir":"","previous_headings":"","what":"Enforcement Guidelines","title":"Contributor Covenant Code of Conduct","text":"Community leaders follow Community Impact Guidelines determining consequences action deem violation Code Conduct:","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_1-correction","dir":"","previous_headings":"Enforcement Guidelines","what":"1. Correction","title":"Contributor Covenant Code of Conduct","text":"Community Impact: Use inappropriate language behavior deemed unprofessional unwelcome community. Consequence: private, written warning community leaders, providing clarity around nature violation explanation behavior inappropriate. public apology may requested.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_2-warning","dir":"","previous_headings":"Enforcement Guidelines","what":"2. Warning","title":"Contributor Covenant Code of Conduct","text":"Community Impact: violation single incident series actions. Consequence: warning consequences continued behavior. interaction people involved, including unsolicited interaction enforcing Code Conduct, specified period time. includes avoiding interactions community spaces well external channels like social media. Violating terms may lead temporary permanent ban.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_3-temporary-ban","dir":"","previous_headings":"Enforcement Guidelines","what":"3. Temporary Ban","title":"Contributor Covenant Code of Conduct","text":"Community Impact: serious violation community standards, including sustained inappropriate behavior. Consequence: temporary ban sort interaction public communication community specified period time. public private interaction people involved, including unsolicited interaction enforcing Code Conduct, allowed period. Violating terms may lead permanent ban.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_4-permanent-ban","dir":"","previous_headings":"Enforcement Guidelines","what":"4. Permanent Ban","title":"Contributor Covenant Code of Conduct","text":"Community Impact: Demonstrating pattern violation community standards, including sustained inappropriate behavior, harassment individual, aggression toward disparagement classes individuals. Consequence: permanent ban sort public interaction within community.","code":""},{"path":"https://usethis.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"attribution","dir":"","previous_headings":"","what":"Attribution","title":"Contributor Covenant Code of Conduct","text":"Code Conduct adapted Contributor Covenant, version 2.1, available https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. Community Impact Guidelines inspired [Mozilla’s code conduct enforcement ladder][https://github.com/mozilla/inclusion]. answers common questions code conduct, see FAQ https://www.contributor-covenant.org/faq. Translations available https://www.contributor-covenant.org/translations.","code":""},{"path":"https://usethis.r-lib.org/dev/CONTRIBUTING.html","id":null,"dir":"","previous_headings":"","what":"Contributing to usethis","title":"Contributing to usethis","text":"outlines propose change usethis. detailed info contributing , tidyverse packages, please see development contributing guide.","code":""},{"path":"https://usethis.r-lib.org/dev/CONTRIBUTING.html","id":"fixing-typos","dir":"","previous_headings":"","what":"Fixing typos","title":"Contributing to usethis","text":"can fix typos, spelling mistakes, grammatical errors documentation directly using GitHub web interface, long changes made source file. generally means ’ll need edit roxygen2 comments .R, .Rd file. can find .R file generates .Rd reading comment first line.","code":""},{"path":"https://usethis.r-lib.org/dev/CONTRIBUTING.html","id":"bigger-changes","dir":"","previous_headings":"","what":"Bigger changes","title":"Contributing to usethis","text":"want make bigger change, ’s good idea first file issue make sure someone team agrees ’s needed. ’ve found bug, please file issue illustrates bug minimal reprex (also help write unit test, needed).","code":""},{"path":"https://usethis.r-lib.org/dev/CONTRIBUTING.html","id":"pull-request-process","dir":"","previous_headings":"Bigger changes","what":"Pull request process","title":"Contributing to usethis","text":"Fork package clone onto computer. haven’t done , recommend using usethis::create_from_github(\"r-lib/usethis\", fork = TRUE). Install development dependencies devtools::install_dev_deps(), make sure package passes R CMD check running devtools::check(). R CMD check doesn’t pass cleanly, ’s good idea ask help continuing. Create Git branch pull request (PR). recommend using usethis::pr_init(\"brief-description--change\"). Make changes, commit git, create PR running usethis::pr_push(), following prompts browser. title PR briefly describe change. body PR contain Fixes #issue-number. user-facing changes, add bullet top NEWS.md (.e. just first header). Follow style described https://style.tidyverse.org/news.html.","code":""},{"path":"https://usethis.r-lib.org/dev/CONTRIBUTING.html","id":"code-style","dir":"","previous_headings":"Bigger changes","what":"Code style","title":"Contributing to usethis","text":"New code follow tidyverse style guide. can use styler package apply styles, please don’t restyle code nothing PR. use roxygen2, Markdown syntax, documentation. use testthat unit tests. Contributions test cases included easier accept.","code":""},{"path":"https://usethis.r-lib.org/dev/CONTRIBUTING.html","id":"code-of-conduct","dir":"","previous_headings":"","what":"Code of Conduct","title":"Contributing to usethis","text":"Please note usethis project released Contributor Code Conduct. contributing project agree abide terms.","code":""},{"path":"https://usethis.r-lib.org/dev/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"MIT License","title":"MIT License","text":"Copyright (c) 2020 usethis authors Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://usethis.r-lib.org/dev/SUPPORT.html","id":null,"dir":"","previous_headings":"","what":"Getting help with usethis","title":"Getting help with usethis","text":"Thanks using usethis! filing issue, places explore pieces put together make process smooth possible.","code":""},{"path":"https://usethis.r-lib.org/dev/SUPPORT.html","id":"make-a-reprex","dir":"","previous_headings":"","what":"Make a reprex","title":"Getting help with usethis","text":"Start making minimal reproducible example using reprex package. haven’t heard used reprex , ’re treat! Seriously, reprex make R-question-asking endeavors easier (pretty incredible ROI five ten minutes ’ll take learn ’s ). additional reprex pointers, check Get help! section tidyverse site.","code":""},{"path":"https://usethis.r-lib.org/dev/SUPPORT.html","id":"where-to-ask","dir":"","previous_headings":"","what":"Where to ask?","title":"Getting help with usethis","text":"Armed reprex, next step figure ask. ’s question: start community.rstudio.com, /StackOverflow. people answer questions. ’s bug: ’re right place, file issue. ’re sure: let community help figure ! problem bug feature request, can easily return report . opening new issue, sure search issues pull requests make sure bug hasn’t reported /already fixed development version. default, search pre-populated :issue :open. can edit qualifiers (e.g. :pr, :closed) needed. example, ’d simply remove :open search issues repo, open closed.","code":""},{"path":"https://usethis.r-lib.org/dev/SUPPORT.html","id":"what-happens-next","dir":"","previous_headings":"","what":"What happens next?","title":"Getting help with usethis","text":"efficient possible, development tidyverse packages tends bursty, shouldn’t worry don’t get immediate response. Typically don’t look repo sufficient quantity issues accumulates, ’s burst intense activity focus efforts. makes development efficient avoids expensive context switching problems, cost taking longer get back . process makes good reprex particularly important might multiple months initial report start working . can’t reproduce bug, can’t fix !","code":""},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"markdown-image-link","dir":"Articles","previous_headings":"","what":"Markdown image link","title":"Exploring badge accessibility","text":"usethis currently inserts badges special “badge block” README, fenced HTML comment tags. Within badge block, badge hyperlinked image, alt text. basic form: Note alt_text static label explaining badge’s purpose, whereas dynamic information baked externally-served image. usethis definitely controls alt_text, something ’d like feedback .","code":"[![alt_text](http://path/to/the/badge/image)](http://path/to/more/details)"},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"badge-image","dir":"Articles","previous_headings":"","what":"Badge image","title":"Exploring badge accessibility","text":"badges days tend SVG files, fortunate, since SVGs can carry attributes support accessibility. demonstrate custom badge generated via shields.io web service. request badge URL: badge, hyperlink set https://shields.io/. badge inside HTML comment block, like usethis README badges. ’ve prefixed every field can influence “”; 3 fields: alt text. label. static text appears left side badge, grey background, describes badge. message. text appears right side badge, colored background. often dynamic part, color text convey dynamic fact, e.g. “passing” green background “failing” red background. Now inspect badge SVG. apologize advance amount data displayed , seems good show one badge full gory detail. Later, display badge information selectively. understanding two main pieces metadata title aria-label attribute. reveal just two items badge: badge carries information title aria-label, “my_label: my_message”. interested learn information included twice good bad thing screen reader experience.","code":"https://img.shields.io/badge/my__label-my__message-orange library(xml2) library(purrr) inspect_badge <- function(badge) { badge %>% read_xml() %>% as_list() %>% pluck(\"svg\") } inspect_badge(\"https://img.shields.io/badge/my__label-my__message-orange\") #> $title #> $title[[1]] #> [1] \"my_label: my_message\" #> #> #> $linearGradient #> $linearGradient$stop #> list() #> attr(,\"offset\") #> [1] \"0\" #> attr(,\"stop-color\") #> [1] \"#bbb\" #> attr(,\"stop-opacity\") #> [1] \".1\" #> #> $linearGradient$stop #> list() #> attr(,\"offset\") #> [1] \"1\" #> attr(,\"stop-opacity\") #> [1] \".1\" #> #> attr(,\"id\") #> [1] \"s\" #> attr(,\"x2\") #> [1] \"0\" #> attr(,\"y2\") #> [1] \"100%\" #> #> $clipPath #> $clipPath$rect #> list() #> attr(,\"width\") #> [1] \"144\" #> attr(,\"height\") #> [1] \"20\" #> attr(,\"rx\") #> [1] \"3\" #> attr(,\"fill\") #> [1] \"#fff\" #> #> attr(,\"id\") #> [1] \"r\" #> #> $g #> $g$rect #> list() #> attr(,\"width\") #> [1] \"61\" #> attr(,\"height\") #> [1] \"20\" #> attr(,\"fill\") #> [1] \"#555\" #> #> $g$rect #> list() #> attr(,\"x\") #> [1] \"61\" #> attr(,\"width\") #> [1] \"83\" #> attr(,\"height\") #> [1] \"20\" #> attr(,\"fill\") #> [1] \"#fe7d37\" #> #> $g$rect #> list() #> attr(,\"width\") #> [1] \"144\" #> attr(,\"height\") #> [1] \"20\" #> attr(,\"fill\") #> [1] \"url(#s)\" #> #> attr(,\"clip-path\") #> [1] \"url(#r)\" #> #> $g #> $g$text #> $g$text[[1]] #> [1] \"my_label\" #> #> attr(,\"aria-hidden\") #> [1] \"true\" #> attr(,\"x\") #> [1] \"315\" #> attr(,\"y\") #> [1] \"150\" #> attr(,\"fill\") #> [1] \"#010101\" #> attr(,\"fill-opacity\") #> [1] \".3\" #> attr(,\"transform\") #> [1] \"scale(.1)\" #> attr(,\"textLength\") #> [1] \"510\" #> #> $g$text #> $g$text[[1]] #> [1] \"my_label\" #> #> attr(,\"x\") #> [1] \"315\" #> attr(,\"y\") #> [1] \"140\" #> attr(,\"transform\") #> [1] \"scale(.1)\" #> attr(,\"fill\") #> [1] \"#fff\" #> attr(,\"textLength\") #> [1] \"510\" #> #> $g$text #> $g$text[[1]] #> [1] \"my_message\" #> #> attr(,\"aria-hidden\") #> [1] \"true\" #> attr(,\"x\") #> [1] \"1015\" #> attr(,\"y\") #> [1] \"150\" #> attr(,\"fill\") #> [1] \"#010101\" #> attr(,\"fill-opacity\") #> [1] \".3\" #> attr(,\"transform\") #> [1] \"scale(.1)\" #> attr(,\"textLength\") #> [1] \"730\" #> #> $g$text #> $g$text[[1]] #> [1] \"my_message\" #> #> attr(,\"x\") #> [1] \"1015\" #> attr(,\"y\") #> [1] \"140\" #> attr(,\"transform\") #> [1] \"scale(.1)\" #> attr(,\"fill\") #> [1] \"#fff\" #> attr(,\"textLength\") #> [1] \"730\" #> #> attr(,\"fill\") #> [1] \"#fff\" #> attr(,\"text-anchor\") #> [1] \"middle\" #> attr(,\"font-family\") #> [1] \"Verdana,Geneva,DejaVu Sans,sans-serif\" #> attr(,\"text-rendering\") #> [1] \"geometricPrecision\" #> attr(,\"font-size\") #> [1] \"110\" #> #> attr(,\"width\") #> [1] \"144\" #> attr(,\"height\") #> [1] \"20\" #> attr(,\"role\") #> [1] \"img\" #> attr(,\"aria-label\") #> [1] \"my_label: my_message\" #> attr(,\"xmlns\") #> [1] \"http://www.w3.org/2000/svg\" #> attr(,\"xmlns:xlink\") #> [1] \"http://www.w3.org/1999/xlink\" inspect_badge <- function(badge) { x <- badge %>% read_xml() %>% as_list() %>% pluck(\"svg\") list( title = pluck(x, \"title\", 1), `aria-label` = pluck(x, attr_getter(\"aria-label\")) ) } inspect_badge(\"https://img.shields.io/badge/my__label-my__message-orange\") #> $title #> [1] \"my_label: my_message\" #> #> $`aria-label` #> [1] \"my_label: my_message\""},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"shields-io-badges-are-accessible-today","dir":"Articles","previous_headings":"Badge image","what":"shields.io badges are accessible today","title":"Exploring badge accessibility","text":"One reasons inspected shields.io badge may provide usable alternative service whose official badge (yet?) screen-reader-friendly. custom badge completely static. shields.io also supports custom dynamic badges, necessary information (label, message, color) available suitable JSON endpoint. Finally, relevant usethis, shields.io offers pre-configured dynamic badges commonly “badged” services, including GitHub Actions Codecov. shields.io badge usethis’s R CMD check workflow GitHub Actions: , indicating fields control my_alt_text my_label, ’s easier get feedback usethis . title aria-label badge : Now take inventory main badges inserted usethis things stand re: accessibility.","code":"inspect_badge(\"https://img.shields.io/github/workflow/status/r-lib/usethis/R-CMD-check?label=my_label-R-CMD-check\") #> $title #> [1] \"my_label-R-CMD-check: https://github.com/badges/shields/issues/8671\" #> #> $`aria-label` #> [1] \"my_label-R-CMD-check: https://github.com/badges/shields/issues/8671\""},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"r-cmd-check-status","dir":"Articles","previous_headings":"","what":"R CMD check status","title":"Exploring badge accessibility","text":"generally obtain current R CMD check status GitHub Actions workflow. official badge provided GitHub: title aria-label badge : time writing (late December 2021), badge include information. requested GitHub’s Actions Packages Feedback forum response GitHub encouraging. Hopefully native badge gain improved accessibility early 2022. https://github.com/github/feedback/discussions/8974 meantime, one use shields.io badge report R CMD check status, demonstrated previous section. maintainer one-, GitHub badge upgrade slow coming, implement usethis::use_github_actions_badge().","code":"inspect_badge(\"https://github.com/r-lib/usethis/actions/workflows/R-CMD-check.yaml/badge.svg\") #> $title #> [1] \"R-CMD-check.yaml - failing\" #> #> $`aria-label` #> NULL"},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"package-lifecycle","dir":"Articles","previous_headings":"","what":"Package lifecycle","title":"Exploring badge accessibility","text":"usethis::use_lifecycle_badge() declares developmental stage package, using framework https://lifecycle.r-lib.org/articles/stages.html. function already inserts shields.io badge: title aria-label badge : ’s possible usethis using badge “owned” lifecycle package. think don’t now, declaring lifecycle stage whole package necessarily imply need take formal dependency lifecycle package, usually causes badges copied man/figures/ directory. Also, badges shipped lifecycle package currently accessible, another reason use . opened issue (https://github.com/r-lib/lifecycle/issues/117). relatively easy fix, since static badges. done, package maintainers need update SVGs stored man/figures/.","code":"inspect_badge(\"https://img.shields.io/badge/lifecycle-stable-brightgreen.svg\") #> $title #> [1] \"lifecycle: stable\" #> #> $`aria-label` #> [1] \"lifecycle: stable\""},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"cran-status","dir":"Articles","previous_headings":"","what":"CRAN status","title":"Exploring badge accessibility","text":"usethis::use_cran_badge() places badge indicates package version available CRAN. badge served METACRAN (https://www.r-pkg.org) maintainer Gábor Csárdi already incorporated aria-label badges (commit). available badges listed . ’s badge placed usethis::use_cran_badge(): title aria-label badge : time writing (late December 2021), aria-label present, title . interested know good situation using screen reader.","code":"inspect_badge(\"https://www.r-pkg.org/badges/version/usethis\") #> $title #> NULL #> #> $`aria-label` #> [1] \"CRAN 3.0.0\""},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"code-coverage","dir":"Articles","previous_headings":"","what":"Code coverage","title":"Exploring badge accessibility","text":"usethis::use_coverage(type = c(\"codecov\", \"coveralls\", ...) calls internal helper usethis:::use_codecov_badge() insert badge either Codecov Coveralls service. examples two badges (note usethis use Coveralls, ’m using different package demo): title aria-label badges:: time writing (late December 2021), neither badge offers title aria-label. badges shields.io Codecov Coveralls: title aria-label shields.io badges::","code":"inspect_badge(\"https://codecov.io/gh/r-lib/usethis/branch/main/graph/badge.svg\") #> $title #> NULL #> #> $`aria-label` #> NULL inspect_badge(\"https://coveralls.io/repos/github/trinker/sentimentr/badge.svg?branch=master\") #> $title #> NULL #> #> $`aria-label` #> NULL inspect_badge(\"https://img.shields.io/codecov/c/github/r-lib/usethis?label=test%20coverage&logo=codecov\") #> $title #> [1] \"test coverage: 59%\" #> #> $`aria-label` #> [1] \"test coverage: 59%\" inspect_badge(\"https://img.shields.io/coveralls/github/trinker/sentimentr?logo=coveralls\") #> $title #> [1] \"coverage: 19%\" #> #> $`aria-label` #> [1] \"coverage: 19%\""},{"path":"https://usethis.r-lib.org/dev/articles/badge-accessibility.html","id":"bioconductor","dir":"Articles","previous_headings":"","what":"Bioconductor","title":"Exploring badge accessibility","text":"package Bioconductor, usethis::use_bioc_badge() can used insert badge Bioconductor build status. badge: title aria-label badge: time writing (late December 2021), badge title aria-label. ’s immediately clear resolve , suspect Bioconductor receptive request create accessible badges.","code":"inspect_badge(\"http://www.bioconductor.org/shields/build/release/bioc/biocthis.svg\") #> $title #> NULL #> #> $`aria-label` #> NULL"},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"tldr-use-https-2fa-and-a-github-personal-access-token","dir":"Articles","previous_headings":"","what":"TL;DR: Use HTTPS, 2FA, and a GitHub Personal Access Token","title":"Managing Git(Hub) Credentials","text":"main recommendations : Adopt HTTPS Git transport protocol. Turn two-factor authentication GitHub account. Use personal access token (PAT) Git remote operations command line R. Allow tools store retrieve credentials Git credential store. previously set GitHub PAT .Renviron, stop . Next provide context rationale recommendations. following section, explain actually implement .","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"https-vs-ssh","dir":"Articles","previous_headings":"TL;DR: Use HTTPS, 2FA, and a GitHub Personal Access Token","what":"HTTPS vs SSH","title":"Managing Git(Hub) Credentials","text":"Instead HTTPS, use SSH. Many people valid reasons preferring SSH carry . recommendation HTTPS ’s easier SSH newcomers set correctly, especially Windows. GitHub also long recommended HTTPS new users. Finally, using HTTPS PAT kills two birds one stone: single credential can used authenticate GitHub regular Git server REST API. authenticate via SSH “regular” Git work, still set PAT work uses REST API.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"two-factor-authentication","dir":"Articles","previous_headings":"TL;DR: Use HTTPS, 2FA, and a GitHub Personal Access Token","what":"Two-factor authentication","title":"Managing Git(Hub) Credentials","text":"Turning two-factor authentication important online accounts just good idea, general. example, make 2FA hard requirement members tidyverse r-lib GitHub organizations. past, activating 2FA also forced using HTTPS use PAT, instead “username + password”, operations like git push. Using PAT now absolute requirement, operations using HTTPS protocol, longer anything 2FA. background deprecation “username + password” can found GitHub’s blog post Token authentication requirements Git operations.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"git-credential-helpers-and-the-credential-store","dir":"Articles","previous_headings":"TL;DR: Use HTTPS, 2FA, and a GitHub Personal Access Token","what":"Git credential helpers and the credential store","title":"Managing Git(Hub) Credentials","text":"’s awkward provide credentials every single Git transaction, ’s customary let system remember credentials. Git uses -called credential helpers , happily, tend “just work” days (especially, macOS Windows) 1. Git credential helpers take advantage official OS-provided credential stores, possible, macOS Keychain Windows Credential Manager. Recent innovations gert gh mean Git/GitHub operations R can also store discover credentials using official Git credential helpers. means can stop storing GitHub PATs plain text startup file, like .Renviron 2. , turn, reduces risk accidentally leaking credentials.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"practical-instructions","dir":"Articles","previous_headings":"","what":"Practical instructions","title":"Managing Git(Hub) Credentials","text":"actually implement recommendations? diagnostic functions usethis::gh_token_help() usethis::git_sitrep() offer advice see , directly R session.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"adopt-https","dir":"Articles","previous_headings":"Practical instructions","what":"Adopt HTTPS","title":"Managing Git(Hub) Credentials","text":"Make sure use HTTPS URLs, SSH, cloning repos adding new remotes: HTTPS URLs look like : https://github.com//.git SSH URLs look like : git@github.com:/.git usethis defaults HTTPS functions like create_from_github() use_github(), v2.0.03. ’s fine adopt HTTPS new work, even pre-existing repos use SSH. ’s fine use HTTPS one remote repo SSH another. ’s fine use HTTPS remotes one repo SSH remotes another. ’s fine interact GitHub repo via HTTPS one computer via SSH another. --nothing irreversible decision. long relevant tools can obtain necessary credentials cache , good go.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"turn-on-two-factor-authentication","dir":"Articles","previous_headings":"Practical instructions","what":"Turn on two-factor authentication","title":"Managing Git(Hub) Credentials","text":"See GitHub’s current instructions : Securing account two-factor authentication (2FA) don’t already use password manager 1Password Bitwarden, great time start! Among benefits, apps can serve authenticator 2FA. Turning 2FA recommended, optional.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"get-a-personal-access-token-pat","dir":"Articles","previous_headings":"Practical instructions","what":"Get a personal access token (PAT)","title":"Managing Git(Hub) Credentials","text":"Assuming ’re signed GitHub, create_github_token() takes pre-filled form create new PAT. can get page browser clicking “Generate new token” https://github.com/settings/tokens. advantage create_github_token() pre-selected recommended scopes, can look adjust clicking “Generate token”. good idea describe token’s purpose Note field, one day might multiple PATs. recommend naming token use case, computer project using , e.g. “personal-macbook-air” “vm--project-xyz”. future, find staring list tokens, inevitably ’ll need re-generate delete one . Make easy figure token need fiddle . GitHub encourages use perishable tokens, default Expiration period 30 days. Unless specific reason fight , recommend accepting default. assume GitHub’s security folks good reasons recommendation. , course, can adjust Expiration behaviour see fit, including “expiration”. ’re happy token’s Note, Expiration, Scopes, click “Generate token”. won’t able see token , don’t close navigate away browser window store PAT locally. Copy PAT clipboard, anticipating ’ll next: trigger prompt lets us store PAT Git credential store. Sidebar storing PAT: use password management app, 1Password Bitwarden (highly recommended!), might want add PAT (Note) entry GitHub. Storing PAT Git credential store semi-persistent convenience, sort like browser cache “remember ” website, ’s quite possible need re-enter PAT future. decide embrace impermanence PAT , somehow removed store, ’ll just re-generate new PAT re-enter . accept default 30-day expiration period, workflow ’ll using often anyway. create long-lasting tokens want play around functions setting clearing Git credentials, can handy record PAT secure place, like 1Password Bitwarden.","code":"usethis::create_github_token()"},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"put-your-pat-into-the-local-git-credential-store","dir":"Articles","previous_headings":"Practical instructions","what":"Put your PAT into the local Git credential store","title":"Managing Git(Hub) Credentials","text":"assume ’ve created PAT available clipboard. insert PAT Git credential store? R: gitcreds package installed, usethis v2.0.0, usethis uses gh, gh uses gitcreds. don’t PAT stored already, prompt enter PAT. Paste! already stored credential, gitcreds::gitcreds_set() reveals even let inspect . helps decide whether keep existing credential replace . doubt, embrace new, known---good credential old one, uncertain origins. previously made GitHub PAT available setting GITHUB_PAT environment variable .Renviron, need actively stop ! doubt previous practices, open .Renviron, look line setting GITHUB_PAT GITHUB_TOKEN environment variable, delete line. usethis::edit_r_environ() can helpful getting .Renviron open editing. Don’t forget restart R change take effect! can check PAT successfully stored usethis::gh_token_help() executed fresh R session: general function usethis::git_sitrep() also report PAT, along aspects Git/GitHub setup.","code":"gitcreds::gitcreds_set() > gitcreds::gitcreds_set() ? Enter password or token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -> Adding new credentials... -> Removing credentials from cache... -> Done. > gitcreds::gitcreds_set() -> Your current credentials for 'https://github.com': protocol: https host : github.com username: PersonalAccessToken password: <-- hidden --> -> What would you like to do? 1: Keep these credentials 2: Replace these credentials 3: See the password / token Selection: 2 -> Removing current credentials... ? Enter new password or token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -> Adding new credentials... -> Removing credentials from cache... -> Done. gh_token_help() git_sitrep()"},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"ongoing-pat-maintenance","dir":"Articles","previous_headings":"Practical instructions","what":"Ongoing PAT maintenance","title":"Managing Git(Hub) Credentials","text":"going (re-)generating (re-)storing PAT schedule dictated expiration period. default, per month. PAT expires, return https://github.com/settings/tokens click Note. (label tokens nicely use case, right? Right?) point, can optionally adjust scopes click “Regenerate token”. can optionally modify Expiration click “Regenerate token” (). , copy PAT clipboard, call gitcreds::gitcreds_set(), paste! Hopefully ’s becoming clear token’s Note important. actual token may changing, e.g., month, use case (scopes) much persistent stable. Sidebar: gitcreds package plays role gh credentials package gert. gitcreds credentials provide R interface Git credential store, targeting slightly different use cases. gitcreds credentials packages evolving convergently may, fact, merge one. meantime, chance use different “key”, “key-value” sense, storing retrieving PAT. Therefore, conceivable gert+credentials may also prompt PAT, case just provide . explicitly check gert+credentials can discover PAT, call credentials::set_github_pat(). , lead prompt can enter .","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"additional-resources","dir":"Articles","previous_headings":"","what":"Additional resources","title":"Managing Git(Hub) Credentials","text":"users ready work Git GitHub R now, specifically gert, gh, usethis. section, cover specialized topics apply certain users.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"github-enterprise","dir":"Articles","previous_headings":"Additional resources","what":"GitHub Enterprise","title":"Managing Git(Hub) Credentials","text":"v2.0.0, usethis fully support GitHub Enterprise deployments. find true, please open issue. usethis functions support explicit host argument, general, usethis honors GitHub host implicit URLs, e.g., locally configured Git remotes, inherits default behaviour gh. gh package honors GITHUB_API_URL environment variable , unset, falls back https://api.github.com. general, usethis, gh, gitcreds work GitHub Enterprise, long intended GitHub host discoverable specified. example, can store PAT GitHub Enterprise deployment like : can also troubleshoot PATs GHE usual functions: time writing, credentials::set_github_pat() hard-wired “github.com”, may generalized future.","code":"gitcreds::gitcreds_set(\"https://github.acme.com\") usethis::gh_token_help(\"https://github.acme.com\") # or usethis::git_sitrep()"},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"what-about--renviron","dir":"Articles","previous_headings":"Additional resources","what":"What about .Renviron?","title":"Managing Git(Hub) Credentials","text":"past, common way make GitHub PAT available R define GITHUB_PAT environment variable .Renviron startup file. still works, since gitcreds+gh credentials+gert check environment variables consult Git credential store. However, also means presence legacy GITHUB_PAT .Renviron can get way adoption new approach! doubt previous practices, open .Renviron, look line setting GITHUB_PAT environment variable, delete . usethis::edit_r_environ() can helpful getting .Renviron open editing. Don’t forget restart R change take effect. gitcreds+gh credentials+gert even check environment variables? retrieve PAT store, temporarily cache environment variable, persists duration current R session. allows discovered PAT reused, potentially multiple packages, repeatedly course R session. Using .Renviron primary PAT store less secure , can, safer keep PAT Git credential store let packages need discover upon first need. Linux users may still need use .Renviron method, since don’t easy access OS-managed stores like macOS Keychain Windows Credential Manager. still need use .Renviron method, usethis::edit_r_environ() opens file editing. Add line like , substitute PAT: Make sure file ends newline! Lack newline can lead silent failure load startup files, can tricky debug. Take care file accidentally pushed cloud, e.g. Google Drive GitHub. Restart R changes .Renviron take effect.","code":"usethis::edit_r_environ() GITHUB_PAT=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"what-about-the-remotes-and-pak-packages","dir":"Articles","previous_headings":"Additional resources","what":"What about the remotes and pak packages?","title":"Managing Git(Hub) Credentials","text":"remotes pak packages help us install R packages GitHub: Lifecycle-wise, remotes replaced pak, still transition period, maintained. packages potentially need GitHub PAT. PAT necessary, example, install private GitHub repo. Even accessing public resources, PAT helpful implies much higher rate limit requests GitHub API. pak uses PAT-finding approach usethis/gh/gitcreds. ’ve done setup described , pak “just work”, PAT everything else. remotes use new PAT-finding approach , instead, consults GITHUB_PAT environment variable, falling back built-generic credential. re: installing packages GitHub? personal recommendation: Use pak::pkg_install(\"OWNER/REPO\") explicit “install GitHub” needs. Allow remotes use fallback credential, ever gets called implicitly. define GITHUB_PAT .Renviron. want keep using remotes, instead pak, just rely built-credential. suffice rate-limiting concern, obviously provide access private repositories. really want use remotes, PAT, can “tickle” gitcreds, via gitcreds::gitcreds_get(), get load PAT store GITHUB_PAT environment variable, remotes happily find . done interactively needed, written individual scripts, even executed startup file. still avoids defining GITHUB_PAT .Renviron. use remotes, make sure update latest version, guarantee built-credential valid.","code":"remotes::install_github(\"r-lib/usethis\") pak::pkg_install(\"r-lib/usethis\") Sys.setenv(GITHUB_PAT = gitcreds::gitcreds_get(use_cache = FALSE)$password)"},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"continuous-integration","dir":"Articles","previous_headings":"Additional resources","what":"Continuous integration","title":"Managing Git(Hub) Credentials","text":"headless system, CI/CD platform like GitHub Actions, won’t able interactively store PAT gitcreds::gitcreds_set() credentials::set_github_pat(). case GitHub Actions, access token automatically available workflow can exposed R GITHUB_PAT environment variable like : automatic token doesn’t sufficient permissions, ’ll need create suitable token store repository secret. also general approach CI/CD platforms GitHub Actions: Provide PAT secure GITHUB_PAT environment variable. Use regular environment variables store less sensitive settings, API host. Take care expose PAT , e.g., printing environment variables log file.","code":"env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}"},{"path":"https://usethis.r-lib.org/dev/articles/git-credentials.html","id":"how-to-learn-more","dir":"Articles","previous_headings":"","what":"How to learn more","title":"Managing Git(Hub) Credentials","text":"gh gitcreds gh: gh.r-lib.org gh vignette: Managing Personal Access Tokens gitcreds: r-lib.github.io/gitcreds/ gert credentials gert: docs.ropensci.org/gert credentials: docs.ropensci.org/credentials rOpenSci tech note: better way manage GitHub personal access tokens","code":""},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"contributing-to-someone-elses-package","dir":"Articles","previous_headings":"","what":"Contributing to someone else’s package","title":"Pull request helpers","text":", want contribute R package? ’s fantastic! walk process making -called pull request praise package. package designed help package developers “build friendly R packages praise users done something good, just need feel better.” can use praise construct encouraging feedback sampling collection positive adjectives, adverbs, verbs, smileys, exclamations: going propose new adjective: “formidable”.","code":"library(praise) template <- \"${EXCLAMATION} - your pull request is ${adjective}!\" praise(template) #> [1] \"YEE-HAW - your pull request is groovy!\""},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"whats-a-pull-request","dir":"Articles","previous_headings":"","what":"What’s a pull request?","title":"Pull request helpers","text":"pull request propose change GitHub repository. Think request maintainer pull changes repo. pr_*() family functions designed make working GitHub pull requests painless possible, contributors package maintainers. designed support Git GitHub workflows recommended Happy Git GitHub useR. pull request (PR) involves two players, contributor reviewer. make clear runs code, code chunks article color coded: code executed contributor appears chunks light gray background code executed reviewer appears chunks beige background.","code":"# contributor code # reviewer code"},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"set-up-advice","dir":"Articles","previous_headings":"","what":"Set up advice","title":"Pull request helpers","text":"article assumes already done Git GitHub parts setup vignette configured GitHub personal access token, described Managing Git(Hub) Credentials. good way check ready use pr_* family functions run git_sitrep(), prints info current Git, gert, GitHub setup. Specifically, pr_*() functions make use : create_github_token() helps set one . usethis can’t figure , might ask . can set usethis.protocol option proactively address . use \"https\" protocol, GitHub PAT credential need. good reason choose \"https\"!","code":""},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"attach-usethis","dir":"Articles","previous_headings":"","what":"Attach usethis","title":"Pull request helpers","text":"code assumes ’ve attached usethis R session:","code":"library(usethis)"},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"fork-and-clone","dir":"Articles","previous_headings":"","what":"Fork and clone","title":"Pull request helpers","text":"first step fork source repository, get copy GitHub, clone , get local copy. many ways accomplish two steps, demonstrate usethis::create_from_github(): : Forks praise repo, owned rladies GitHub, GitHub account. origin remote set praise repo. upstream remote set praise repo owned rladies. master branch set track upstream/master, can pull upstream changes future. Opens new instance RStudio praise project, ’re working RStudio. Otherwise, switches current R session project. Arguments might like know : Specify fork = TRUE fork = FALSE don’t want defer default behaviour. Use destdir put praise specific location computer. can set usethis.destdir option always want usethis put new projects specific directory.","code":"create_from_github(\"rladies/praise\") #> ℹ Defaulting to 'https' Git protocol #> ✓ Setting `fork = TRUE` #> ✓ Creating '/Users/mine/Desktop/praise/' #> ✓ Forking 'rladies/praise' #> ✓ Cloning repo from 'https://github.com/mine-cetinkaya-rundel/praise.git' into '/Users/mine/Desktop/praise' #> ✓ Setting active project to '/Users/mine/Desktop/praise' #> ℹ Default branch is 'master' #> ✓ Adding 'upstream' remote: 'https://github.com/rladies/praise.git' #> ✓ Pulling in changes from default branch of the source repo 'upstream/master' #> ✓ Setting remote tracking branch for local 'master' branch to 'upstream/master' #> ✓ Opening '/Users/mine/Desktop/praise/' in new RStudio session #> ✓ Setting active project to ''"},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"branch-then-make-your-change","dir":"Articles","previous_headings":"","what":"Branch, then make your change","title":"Pull request helpers","text":"start process contributing package pr_init(), creates branch repository pull request. good idea make pull requests feature branch, repo’s default branch, master (another common choice main). ’ll call branch \"formidable\". creates local branch called formidable switch (“check ”). Now can work locally, making changes files committing Git. Let’s go ahead make change, adding word “formidable” R/adjective.R file package. diff commit associated change. might spot made two mistakes : intended add “formidable”, added “formidabel” instead. forgot comma end line. Let’s assume didn’t actually catch mistakes, didn’t build check package, revealed missing comma. make mistakes.","code":"pr_init(branch = \"formidable\") #> ✓ Setting active project to '/Users/mine/Desktop/praise' #> ℹ Pulling changes from 'upstream/master' #> ✓ Creating and switching to local branch 'formidable' #> ● Use `pr_push()` to create PR."},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"submit-pull-request","dir":"Articles","previous_headings":"","what":"Submit pull request","title":"Pull request helpers","text":"pr_push() pushes local change copy praise GitHub puts position make pull request. launches browser window URL specified last message, looks like following. Click “Create pull request” make PR. clicking able choose draft PR actual PR (opening draft PR, mark ready review ’re done, e.g. commits one new call pr_push()). GitHub ping package maintainer review pull request. can view pull request browser pr_view(). anyone can follow along PR rladies/praise#90.","code":"pr_push() #> ✓ Checking that local branch 'formidable' has the changes in 'origin/formidable' #> ✓ Pushing local 'formidable' branch to 'origin/formidable' #> ✓ Create PR at link given below #> ✓ Opening URL 'https://github.com/mine-cetinkaya-rundel/praise/compare/formidable' pr_view(90) #> ✔ Opening URL 'https://github.com/rladies/praise/pull/90'"},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"review-of-the-pull-request","dir":"Articles","previous_headings":"","what":"Review of the pull request","title":"Pull request helpers","text":"’re lucky, pull request perfect, maintainer accept , .k.. merge . However, case, PR still needs work. package maintainer leaves us comments requesting changes. somewhat new , try address one comments (fix spelling) neglect (forget add comma). make another change commit . Run pr_push() update branch fork, automatically reflected PR. Now reviewer gets another chance review changes. point might choose just make necessary changes push commits pull request finish things . , reviewer fetches PR local machine pr_fetch(). Fetching PR creates local branch called mine-cetinkaya-rundel-formidable, text string comprised GitHub username contributor name branch created PR. pr_fetch() also sets upstream tracking branch local branch got created switches branch reviewer can make changes correct branch. reviewer makes necessary changes, adding missing comma, run pr_push() push changes PR.","code":"pr_push() #> ✔ Pushing local 'formidable' branch to 'origin:formidable' #> ✔ Setting upstream tracking branch for 'formidable' to 'origin/formidable' #> ✔ Create PR at link given below #> ✔ Opening URL 'https://github.com/mine-cetinkaya-rundel/praise/compare/formidable' pr_fetch(90) #> ✔ Setting active project to '/Users/gaborcsardi/works/praise' #> ✔ Checking out PR 'rladies/praise/#90' (@mine-cetinkaya-rundel): 'Add \"formidable\" to adjectives' #> ✔ Adding remote 'mine-cetinkaya-rundel' as 'git@github.com:mine-cetinkaya-rundel/praise.git' #> ✔ Creating local branch 'mine-cetinkaya-rundel-formidable' #> ✔ Setting upstream tracking branch for 'mine-cetinkaya-rundel-formidable' to 'mine-cetinkaya-rundel/formidable' #> ✔ Switching to branch 'mine-cetinkaya-rundel-formidable' #> ✔ Pulling changes from GitHub PR pr_push() #> ✔ Checking that local branch 'mine-cetinkaya-rundel-formidable' has the changes in 'mine-cetinkaya-rundel/formidable' #> ✔ Pushing local 'mine-cetinkaya-rundel-formidable' branch to 'mine-cetinkaya-rundel:formidable' #> ✔ View PR at 'https://github.com/rladies/praise/pull/90' or call `pr_view()`"},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"merge-and-finish","dir":"Articles","previous_headings":"","what":"Merge and finish","title":"Pull request helpers","text":"Finally, reviewer merges pull request GitHub. Locally, can run pr_finish() switch back default branch (usually named main master), pull, delete local branch created process interacting PR, remove associated remote. Since reviewer contributed code pull request, can get code back computer pr_pull(). optional , since full PR already incorporated default branch source repo (usually named main master). pr_pull() can useful PRs rounds alternating contributions maintainer. Finally, can also conclude PR process end pr_finish(). Remember can see whole PR unfolded rladies/praise#90.","code":"pr_finish() #> ✔ Checking that remote branch 'mine-cetinkaya-rundel/formidable' has the changes in 'local/mine-cetinkaya-rundel-formidable' #> ✔ Switching back to 'master' branch #> ✔ Pulling changes from GitHub source repo 'origin/master' #> ✔ Deleting local 'mine-cetinkaya-rundel-formidable' branch #> ✔ Removing remote 'mine-cetinkaya-rundel' pr_pull() #> ✓ Pulling from 'origin/formidable' #> Performing fast-forward merge, no commit needed pr_finish() #> ✓ Checking that remote branch 'origin/formidable' has the changes in 'formidable' #> ✓ Switching back to default branch ('master') #> ℹ Pulling changes from 'origin/master' #> ✓ Deleting local 'formidable' branch"},{"path":"https://usethis.r-lib.org/dev/articles/pr-functions.html","id":"other-helpful-functions","dir":"Articles","previous_headings":"","what":"Other helpful functions","title":"Pull request helpers","text":"functions pr_*() family didn’t encounter PR scenario: pr_merge_main() used getting changes occurred main line development working PR. ’re working fork, git pull upstream master. ’re making PR internal branch, git pull origin master. can useful execute PR branch, big changes project PR become un-mergeable. also useful execute whenever return default branch (usually named main master) , indeed, pr_pause() includes . makes sure copy package --date source repo. pr_pause() makes sure ’re synced PR, switches back default branch, calls pr_merge_main() keep --date source repo. likely something package maintainer reviewing numerous PRs need use, switch back forth reviewing/extending PRs main line development default branch. pr_resume() helps resume work PR ’ve spent time another branch checked . give arguments, present interactive choice local branches indicates , , associated PR.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"block-styles","dir":"Articles","previous_headings":"","what":"Block styles","title":"Converting usethis's UI to use cli","text":"block styles exist produce bulleted output specific symbol, using specific color. Another important feature output can turned package-wide via usethis.quiet option. styles close can done cli::cli_bullets() way responds names input text. direct translation look something like : overall conversion plan switch new function, ui_bullets(), wrapper around cli::cli_bullets(), adds features: Early exit, without emitting messages, usethis.quiet option TRUE. usethis theme, changes color certain bullet styles adds new style todo’s. Summary ’ve done todo’s: Introduce new bullet shortcode todo. Proposal: _ (instead *), seems best single ascii character evokes place check something . Use cli::symbol$checkbox_off symbol (instead generic bullet). guess continue red. terms block styles, just leaves ui_code_block(), pretty different. ui_code_block() used put code screen optionally place clipboard. created new function, ui_code_snippet() built around cli::code_block(). Main observations: cli::code_block(language = \"R\") applies syntax highlighting hyperlinks (e.g. function help topics) R code, cool. Therefore language argument also exposed ui_code_snippet(), defaulting \"R\". Use \"\" anything ’s R code: > ui_code_snippet(\"x <- 1 + 2\") x <- 1 + 2 > ui_code_snippet(\"#include \", language = \"\") #include ui_code_snippet() takes scalar glue-type template string vector lines. Note two calls produce output. > ui_code_snippet(\" + options( + warnPartialMatchArgs = TRUE, + warnPartialMatchDollar = TRUE, + warnPartialMatchAttr = TRUE + )\") options( warnPartialMatchArgs = TRUE, warnPartialMatchDollar = TRUE, warnPartialMatchAttr = TRUE ) > # produces result > ui_code_snippet(c( + \"options(\", + \" warnPartialMatchArgs = TRUE,\", + \" warnPartialMatchDollar = TRUE,\", + \" warnPartialMatchAttr = TRUE\", + \")\")) options( warnPartialMatchArgs = TRUE, warnPartialMatchDollar = TRUE, warnPartialMatchAttr = TRUE ) Use interpolate = FALSE, don’t need interpolation. usual glue thing double , .e. {{ }}. becomes real pain, open issue/PR adding .open .close arguments ui_code_snippet().","code":"> f <- function() { + ui_todo(\"ui_todo(): red bullet\") + ui_done(\"ui_done(): green check\") + ui_oops(\"ui_oops(): red x\") + ui_info(\"ui_info(): yellow i\") + ui_line(\"ui_line(): (no symbol)\") + } > f() • ui_todo(): red bullet ✔ ui_done(): green check ✖ ui_oops(): red x ℹ ui_info(): yellow i ui_line(): (no symbol) > withr::with_options( + list(usethis.quiet = TRUE), + ui_info(\"You won't see this message.\") + ) > withr::with_options( + list(usethis.quiet = FALSE), # this is the default + ui_info(\"But you will see this one.\") + ) ℹ But you will see this one. > cli::cli_bullets(c( + \"noindent\", + \" \" = \"indent\", + \"*\" = \"bullet\", + \">\" = \"arrow\", + \"v\" = \"success\", + \"x\" = \"danger\", + \"!\" = \"warning\", + \"i\" = \"info\" + )) noindent indent • bullet → arrow ✔ success ✖ danger ! warning ℹ info > ui_bullets(c( + \"v\" = \"A great success!\", + \"_\" = \"Something you need to do.\", + \"x\" = \"Bad news.\", + \"i\" = \"The more you know.\", + \" \" = \"I'm just here for the indentation.\", + \"No indentation at all. Not used much in usethis.\" + )) ✔ A great success! ☐ Something you need to do. ✖ Bad news. ℹ The more you know. I'm just here for the indentation. No indentation at all. Not used much in usethis. > ui_code_snippet(\"x <- 1 + 2\") x <- 1 + 2 > ui_code_snippet(\"#include \", language = \"\") #include > ui_code_snippet(\" + options( + warnPartialMatchArgs = TRUE, + warnPartialMatchDollar = TRUE, + warnPartialMatchAttr = TRUE + )\") options( warnPartialMatchArgs = TRUE, warnPartialMatchDollar = TRUE, warnPartialMatchAttr = TRUE ) > # produces same result as > ui_code_snippet(c( + \"options(\", + \" warnPartialMatchArgs = TRUE,\", + \" warnPartialMatchDollar = TRUE,\", + \" warnPartialMatchAttr = TRUE\", + \")\")) options( warnPartialMatchArgs = TRUE, warnPartialMatchDollar = TRUE, warnPartialMatchAttr = TRUE )"},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"utility-functions","dir":"Articles","previous_headings":"","what":"Utility functions","title":"Converting usethis's UI to use cli","text":"block style functions route unexported utility functions. is_quiet() just consults usethis.quiet option implements default FALSE. ui_bullet() intermediate helper used ui_todo(), ui_done(), ui_oops() ui_info(). hygiene related indentation (using indent() utility function), calls ui_inform(). ui_line() ui_code() call ui_inform() directly. ui_inform() just wrapper around rlang::inform() guarded call is_quiet() is_quiet(), continue play role, anticipate longer need utilities (indent(), ui_bullet(), ui_inform()). Updates future: indent() turns still useful ui_code_snippet(), ’ve inlined , avoid reliance definitions ui-legacy.R. ui_bullet() renamed ui_legacy_bullet() auto-completion happiness new ui_bullets(). Let’s cover ui_silence() ’re , exported. ’s just withr::with_*() function executing code usethis.quiet = TRUE.","code":"is_quiet <- function() { isTRUE(getOption(\"usethis.quiet\", default = FALSE)) } ui_inform <- function(...) { if (!is_quiet()) { inform(paste0(...)) } invisible() } ui_silence <- function(code) { withr::with_options(list(usethis.quiet = TRUE), code) }"},{"path":[]},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"legacy-functions","dir":"Articles","previous_headings":"Inline styles","what":"Legacy functions","title":"Converting usethis's UI to use cli","text":"usethis inline styles (mostly) use inside functions like ui_todo(): ui_field() ui_value() ui_path() ui_code() ui_unset() inline styles enact combination : Color, e.g. crayon::green(x) Collapsing collection things one thing, e.g. c(\"\", \"b\", \"c\") “, b, c” Quoting, e.g. encodeString(x, quote = \"'\") ui_path() special potentially modifies input styling . ui_path() first makes path relative specific base (default, active project root) , path directory, also ensures trailing /. ui_unset() special purpose helper used need report something unknown, configured, nonexistent, etc.","code":"> new_val <- \"oxnard\" > x <- glue(\"{ui_field('name')} set to {ui_value(new_val)}\") > dput(x) structure(\"\\033[32mname\\033[39m set to \\033[34m'oxnard'\\033[39m\", class = c(\"glue\", \"character\")) > ui_done(x) ✔ name set to 'oxnard' > x <- glue(\"Your super secret password is {ui_unset()}.\") > dput(x) structure(\"Your super secret password is \\033[90m\\033[39m.\", clas s = c(\"glue\", \"character\")) > ui_info(x) ℹ Your super secret password is ."},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"cli-replacements","dir":"Articles","previous_headings":"Inline styles","what":"cli replacements","title":"Converting usethis's UI to use cli","text":"general, can move towards cli’s native inline-markup: https://cli.r-lib.org/reference/inline-markup.html ’s general conversion plan: ui_field() becomes {.field blah}. usethis_theme(), tweak .field style apply single quotes color available, ui_field() always done. ui_value() becomes {.val value}. ui_path() connected {.path path//thing}, , explained , ui_path() also . Therefore, abstracted “path math” internal helper, ui_path_impl(), aliased pth() compactness. ’s typical conversion: nice create custom inline class, e.g. {.ui_path {some_path}}, done , e.g., googledrive. ’s easy still inheriting cli’s file: hyperlink behaviour, desirable. leads somewhat clunky, verbose pattern , gives nice result. ui_code() gets replaced various inline styles, depending actual goal , : {.code some_text} {.arg some_argument} {.cls some_class} {.fun devtools::build_readme} {.help some_function} {.run usethis::usethis_function()} {.topic some_topic} {.var some_variable} ui_unset() replaced ui_special(), ’ll see . Currently intended grey color doesn’t show render document using solarized-dark far can’t get bottom :( isn’t grey “[Copied clipboard]” ui_code_snippet(), work?","code":"# using legacy functions ui_done(\"Setting {ui_field('LazyData')} to \\\\ {ui_value('true')} in {ui_path('DESCRIPTION')}\") # using new cli-based ui ui_bullets(c( \"v\" = \"Setting {.field LazyData} to {.val true} in {.path {pth('DESCRIPTION')}}.\" ))"},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"conditions","dir":"Articles","previous_headings":"","what":"Conditions","title":"Converting usethis's UI to use cli","text":"’m moving ui_stop(): ui_abort(): main point ui_abort() use cli_abort() (continue applying \"usethis_error\" class). also use ui_abort() apply different default bullet naming/styling. Starting \"x\" defaulting \"\" seems fit best usethis’s existing errors. bullets explicitly given honored. rlang::abort() cli::cli_abort() start \"!\" default, use \"*\" \" \", respectively. legacy functions also include ui_warn(). little usage , instead converting , ’ve eliminated use altogether favor \"!\" bullet: Sidebar: Now ’m looking lot new errors ui_abort() realize usethis also needs passing call argument along. ’m going leave future, separate effort.","code":"ui_stop <- function(x, .envir = parent.frame()) { x <- glue_collapse(x, \"\\n\") x <- glue(x, .envir = .envir) cnd <- structure( class = c(\"usethis_error\", \"error\", \"condition\"), list(message = x) ) stop(cnd) } ui_abort <- function(message, ..., class = NULL, .envir = parent.frame()) { cli::cli_div(theme = usethis_theme()) # bullet naming gymnastics, see below cli::cli_abort( message, class = c(class, \"usethis_error\"), .envir = .envir, ... ) } > block_start = \"# <<<\" > block_end = \"# >>>\" > ui_abort(c( + \"Invalid block specification.\", + \"Must start with {.code {block_start}} and end with {.code {block_en d}}.\" + )) Error: ✖ Invalid block specification. ℹ Must start with `# <<<` and end with `# >>>`. Run `rlang::last_trace()` to see where the error occurred. atever.\")) Error: ✔ It's weird to give a green check in an error, but whatever. Run `rlang::last_trace()` to see where the error occurred. > ui_abort(c( + \"!\" = \"Things are not ideal.\", + \">\" = \"Look at me!\" + )) Error: ! Things are not ideal. → Look at me! Run `rlang::last_trace()` to see where the error occurred. > ui_bullets(c(\"!\" = \"The guy she told you not to worry about.\")) ! The guy she told you not to worry about."},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"sitrep-and-format-helpers","dir":"Articles","previous_headings":"","what":"Sitrep and format helpers","title":"Converting usethis's UI to use cli","text":"small clump functions support sitrep-type output. hd_line() unexported , apparently, unused! now removed kv_line() unexported, new cli implementation ui_unset() exported succeeded ui_special() kv_line() stands “key-value line”. ’s used : Key features: Interpolates data applies inline style result. Works differently key value, ’re much likely use interpolation styling key value. special handling value NULL. Applies \"*\" bullet name/style result. won’t show updated source kv_line() usage show ’s capable : ui_special() successor ui_unset().","code":"> kv_line_legacy <- function(key, value, .envir = parent.frame()) { + value <- if (is.null(value)) ui_unset() else ui_value(value) + key <- glue(key, .envir = .envir) + ui_inform(glue(\"{cli::symbol$bullet} {key}: {value}\")) + } > > url <- \"https://github.com/r-lib/usethis.git\" > remote <- \"origin\" > kv_line_legacy(\"URL for the {ui_value(remote)} remote\", url) • URL for the 'origin' remote: 'https://github.com/r-lib/usethis.git' > > host <- \"github.com\" > kv_line_legacy(\"Personal access token for {ui_value(host)}\", NULL) • Personal access token for 'github.com': > noun <- \"thingy\" > value <- \"VALUE\" > kv_line(\"Let's reveal {.field {noun}}\", \"whatever\") • Let's reveal thingy: \"whatever\" > > kv_line(\"URL for the {.val {remote}} remote\", I(\"{.url {url}}\")) • URL for the \"origin\" remote: > > kv_line(\"Personal access token for {.val {host}}\", NULL) • Personal access token for \"github.com\": > > kv_line(\"Personal access token for {.val {host}}\", ui_special(\"discove red\")) • Personal access token for \"github.com\": "},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"questions","dir":"Articles","previous_headings":"","what":"Questions","title":"Converting usethis's UI to use cli","text":"’s currently drop-substitute ui_yeah() ui_nope() cli. Related issues: https://github.com/r-lib/cli/issues/228, https://github.com/r-lib/cli/issues/488. Therefore, meantime, ui_yeah() ui_nope() -quite-superseded external users. However, internally, ’ve switched unexported functions ui_yep() ui_nah() lightly modified versions ui_yeah() ui_nope() use cli styling.","code":"if (ui_nope(\" Current branch ({ui_value(actual)}) is not repo's default \\\\ branch ({ui_value(default_branch)}).{details}\")) { ui_abort(\"Cancelling. Not on desired branch.\") }"},{"path":"https://usethis.r-lib.org/dev/articles/ui-cli-conversion.html","id":"miscellaneous-notes","dir":"Articles","previous_headings":"","what":"Miscellaneous notes","title":"Converting usethis's UI to use cli","text":"’ve adding period end messages, general rule. terms whitespace indentation, ’ve settled conventions. overall goal get right user-facing output (obviously), making easy possible predict ’s going look like ’re writing code. Key points: Put ui_bullets(c( line, bullet items, followed )) line. Sometimes make exception bullet list exactly one, short bullet item. Use hard line breaks inside bullet text comply surrounding line length. subsequent lines, use indentation get just past opening \". extraneous white space later rationalized cli, handles wrapping. Surround bullet names like x quotes, even though don’t , ’s required names, ! _ ’s better consistent. ’s another style like applies ui_abort(), ’s just one, unnamed bullet, call doesn’t fit one line.","code":"ui_bullets(c( \"i\" = \"Downloading into {.path {pth(destdir)}}.\", \"_\" = \"Prefer a different location? Cancel, try again, and specify {.arg destdir}.\" )) ... ui_bullets(c(\"x\" = \"Things are very wrong.\")) pr <- list(pr_number = 13) ui_abort(\" The repo or branch where PR #{pr$pr_number} originates seems to have been deleted.\")"},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"use-usethis-or-devtools-in-interactive-work","dir":"Articles","previous_headings":"","what":"Use usethis or devtools in interactive work","title":"usethis setup","text":"usethis package carved devtools package part “conscious uncoupling” v2.0.0 release. note devtools makes usethis’s functions available feel like part devtools . addition, devtools offers functions exposes selected functionality packages. might enjoy making devtools (therefore usethis) available interactive R work. Call usethis::use_devtools() prompts : : Open .Rprofile startup file editing. Show necessary code snippet console put clipboard. Prompt paste, save, close, restart R. Done! suggested snippet looks like : resources .Rprofile: official Startup documentation Startup chapter Forgot Teach R workshop materials Kevin Ushey’s blog post RProfile Essentials","code":"library(devtools) ## or library(usethis) use_devtools() if (interactive()) { suppressMessages(require(devtools)) }"},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"store-default-values-for-description-fields-and-other-preferences","dir":"Articles","previous_headings":"","what":"Store default values for DESCRIPTION fields and other preferences","title":"usethis setup","text":"Certain options consulted usethis allow set personal defaults: usethis.full_name: consulted making, e.g., supplemental license files. usethis.protocol: specifies preferred transport protocol Git. Either “https” (usethis default) “ssh”. See help git_protocol() . usethis.description: named list default DESCRIPTION fields new packages made usethis::create_package(). usethis.quiet: TRUE, prevents usethis printing messages console. usethis.destdir: default directory use create_from_github() use_course(). usethis.overwrite: TRUE, usethis overwrites existing file without asking user confirmation file inside Git repo. rationale normal Git workflow makes easy see selectively accept/discard proposed changes. Define options .Rprofile, can opened editing via usethis::edit_r_profile(). example code: Save similar code .Rprofile restart R take effect.","code":"options( usethis.description = list( \"Authors@R\" = utils::person( \"Jane\", \"Doe\", email = \"jane@example.com\", role = c(\"aut\", \"cre\"), comment = c(ORCID = \"JANE'S-ORCID-ID\") ) ), usethis.destdir = \"~/the/place/where/I/keep/my/R/projects\", usethis.overwrite = TRUE )"},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"the-sitrep-functions","dir":"Articles","previous_headings":"","what":"The “sitrep” functions","title":"usethis setup","text":"functions gather information help others troubleshoot things: proj_sitrep(): prints info active usethis project, working directory, active RStudio Project. Points things peculiar fix. git_sitrep(): prints info current Git, gert, GitHub setup. “Sitrep” short “situation report”.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"get-a-github-com-account","dir":"Articles","previous_headings":"","what":"Get a GitHub.com account","title":"usethis setup","text":"Sign free account GitHub.com. Happy Git GitHub useR provides advice picking username.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"install-git","dir":"Articles","previous_headings":"","what":"Install Git","title":"usethis setup","text":"Please see Happy Git GitHub useR instructions install Git. beyond scope article. usethis actually need Git install, uses gert package wraps libgit2. , chances , want normal Git things, like diff commit push, RStudio shell must install Git. Gert’s credential management also works best official Git tooling available.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"configure-user-name-and-user-email","dir":"Articles","previous_headings":"","what":"Configure user.name and user.email","title":"usethis setup","text":"Git installed, introduce Git. usethis::use_git_config() helps configure user.name user.email. Substitute name email address. user name give Git? GitHub username, although can . Another good option actual first name last name. commits labelled name, informative potential collaborators. email give Git? must email associated GitHub account. usethis::git_sitrep() generates git situation-report. can help confirm things work expected; can also help diagnose problems.","code":"library(usethis) ## or library(devtools) use_git_config(user.name = \"Jane Doe\", user.email = \"jane@example.com\") # check by running a git situation-report: # - your user.name and user.email should appear in global Git config git_sitrep()"},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"equivalent-git-commands","dir":"Articles","previous_headings":"Configure user.name and user.email","what":"Equivalent Git commands","title":"usethis setup","text":"code chunk equivalent :","code":"git config --global user.name 'Jane Doe' git config --global user.email 'jane@example.com' git config --global --list"},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"optional-configure-gits-editor","dir":"Articles","previous_headings":"Configure user.name and user.email","what":"Optional: configure Git’s editor","title":"usethis setup","text":"Another Git option many people eventually configure editor. come use Git shell. point, fail give Git wants terms commit message kick editor. can distressing, ’s editor choice don’t even know save quit. can enforce executing R: thing command line Git, execute shell: Substitute preferred editor emacs . popular choice nano. default, don’t configure core.editor, usually vim.","code":"library(usethis) use_git_config(core.editor = \"nano\") git config --global core.editor emacs"},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"connections-git-github-rstudio","dir":"Articles","previous_headings":"","what":"Connections: Git, GitHub, RStudio","title":"usethis setup","text":"stated , usethis doesn’t actually use Git install absolute requirement use GitHub use RStudio. use usethis highly correlated desire things, pleasant way. plan use GitHub, need make sure local Git can pull push GitHub.com. beyond scope article, see Connect GitHub section Happy Git. probably don’t want enter username password time, either cache credentials HTTPS set SSH keys. SSH person, set usethis.protocol option “ssh” (v2.0.0, “https” usethis default). want use RStudio work Git (therefore GitHub, see previous paragraph), need make sure RStudio can find Git executable. usually “just works”. Connect RStudio Git GitHub section Happy Git helps confirm well. well, also troubleshooting tips.","code":""},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"get-and-store-a-github-personal-access-token","dir":"Articles","previous_headings":"","what":"Get and store a GitHub personal access token","title":"usethis setup","text":"GitHub personal access token (PAT) required want use use_github(), create_from_github(..., fork = TRUE), many usethis functions create something GitHub, repo, issue, pull request. Unlike pulling pushing, regular Git operations usual GitHub credentials necessarily work (although can, play cards right; see linked article). Git/GitHub credential management detailed separate article: Managing Git(Hub) Credentials","code":""},{"path":"https://usethis.r-lib.org/dev/articles/usethis-setup.html","id":"prepare-your-system-to-build-packages-from-source","dir":"Articles","previous_headings":"","what":"Prepare your system to build packages from source","title":"usethis setup","text":"participate R development, inevitably want run development versions people’s packages, .e. version available CRAN. typical way install package GitHub pak::pak(\"OWNER/REPO\"). , unlike using install.packages() CRAN, downloading installing source package, binary package. means system needs set building R packages. , long, need build R package compiled code . full description setting R development environment beyond scope article, give pointers diagnostics get started. Update R packages. expect keep frequently. work RStudio, often assist setting dev environment upon first need. Call devtools::has_devel() get initial sense whether R package build tools installed available. pkgbuild::check_build_tools() another function report system , interactive RStudio session, trigger automatic installation build tools. also possible install build tools . macOS: convenient way get tools needed compilation install Xcode Command Line Tools. Note much smaller full Xcode. shell, enter xcode-select --install. installing almost anything else, consider using Homebrew. Windows: Install Rtools. R package! “collection resources building packages R Microsoft Windows, building R ”. Go https://cran.r-project.org/bin/windows/Rtools/ install instructed.","code":""},{"path":"https://usethis.r-lib.org/dev/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Hadley Wickham. Author. Jennifer Bryan. Author, maintainer. Malcolm Barrett. Author. Andy Teucher. Author. . Copyright holder, funder.","code":""},{"path":"https://usethis.r-lib.org/dev/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Wickham H, Bryan J, Barrett M, Teucher (2024). usethis: Automate Package Project Setup. R package version 3.0.0.9000, https://github.com/r-lib/usethis, https://usethis.r-lib.org.","code":"@Manual{, title = {usethis: Automate Package and Project Setup}, author = {Hadley Wickham and Jennifer Bryan and Malcolm Barrett and Andy Teucher}, year = {2024}, note = {R package version 3.0.0.9000, https://github.com/r-lib/usethis}, url = {https://usethis.r-lib.org}, }"},{"path":"https://usethis.r-lib.org/dev/index.html","id":"usethis-","dir":"","previous_headings":"","what":"Automate Package and Project Setup","title":"Automate Package and Project Setup","text":"usethis workflow package: automates repetitive tasks arise project setup development, R packages non-package projects.","code":""},{"path":"https://usethis.r-lib.org/dev/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"Automate Package and Project Setup","text":"Install released version usethis CRAN: install development version GitHub :","code":"install.packages(\"usethis\") # install.packages(\"pak\") pak::pak(\"r-lib/usethis\")"},{"path":"https://usethis.r-lib.org/dev/index.html","id":"usage","dir":"","previous_headings":"","what":"Usage","title":"Automate Package and Project Setup","text":"use_*() functions operate active project: literally, directory computer. ’ve just used usethis create new package project, active project. Otherwise, usethis verifies current working directory valid project directory becomes active project. Use proj_get() proj_sitrep() manually query project read docs. usethis functions strong connections projects expect provide path. usethis quite chatty, explaining ’s assigning tasks. ✔ indicates something usethis done . ☐ indicates ’ll need work . quick look usethis can help set package. remember, many usethis functions also applicable analytical projects packages.","code":"library(usethis) # Create a new package ------------------------------------------------- path <- file.path(tempdir(), \"mypkg\") create_package(path) #> ✔ Creating '/tmp/RtmpCJHMlj/mypkg/'. #> ✔ Setting active project to \"/private/tmp/RtmpCJHMlj/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.3.2 #> ✔ Writing 'NAMESPACE'. #> ✔ Setting active project to \"\". # only needed since this session isn't interactive proj_activate(path) #> ✔ Setting active project to \"/private/tmp/RtmpCJHMlj/mypkg\". #> ✔ Changing working directory to '/tmp/RtmpCJHMlj/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 ggplot2 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\" and \"y\" to \"data/x.rda\" and \"data/y.rda\". #> ☐ Document your data (see ). # Use git ------------------------------------------------------------ use_git() #> ✔ Initialising Git repo. #> ✔ Adding \".Rproj.user\", \".Rhistory\", \".Rdata\", \".httr-oauth\", \".DS_Store\", and #> \".quarto\" to '.gitignore'."},{"path":"https://usethis.r-lib.org/dev/index.html","id":"code-of-conduct","dir":"","previous_headings":"","what":"Code of Conduct","title":"Automate Package and Project Setup","text":"Please note usethis project released Contributor Code Conduct. contributing project, agree abide terms.","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":null,"dir":"","previous_headings":"","what":"usethis design principles","title":"usethis design principles","text":"experiment making key package design principles explicit, versus implicit code. goal make maintenance easier, spread time across people.","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"active-project","dir":"","previous_headings":"","what":"Active project","title":"usethis design principles","text":"Many usethis functions act active project, path stored internal environment proj, specifically proj$cur. instead constantly passing around base path relying working directory. implied functions create modify files inside active project. mostly true use_*() functions, though exceptions. example, use_course() makes reference active project. project activated upon first need, .e. eventually function calls proj_get() , proj$cur NULL, attempt activate project () current working directory. Direct read/write proj$cur never happen, even internally. Instead, use proj_get() proj_set(). possible (.e. don’t want trigger project activation), use proj_get_() proj_set_(). one must use proj_set_() directly, remember stored project path processed proj_path_prep(). Form paths files within project proj_path(). Get paths relative project proj_rel_path().","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"activation-upon-load-or-attach-no","dir":"","previous_headings":"Active project","what":"Activation upon load or attach? No.","title":"usethis design principles","text":"’ve contemplated project activation .onLoad() .onAttach(), ’s clear appropriate. suggests neither appropriate. ever , zzz.R include something like : .onAttach()? package imported usethis also need set project attach. Currently user can open R, attach (load) usethis, change working directory target project. long project first time proj_get() called, correct project made active. preferred workflow, common.","code":".onLoad <- function(libname, pkgname) { try(proj_set(\".\", quiet = TRUE), silent = TRUE) }"},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"helper-functions","dir":"","previous_headings":"","what":"Helper functions","title":"usethis design principles","text":"ambivalence, internally-oriented helpers like write_union() exported. helps developers extending usethis create package standardize project setup within organization. downside aren’t exactly sure yet ’re willing guarantee helpers.","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"permission-to-overwrite","dir":"","previous_headings":"Helper functions","what":"Permission to overwrite","title":"usethis design principles","text":"write_over() returns FALSE nothing need overwrite (proposed file contents existing) user says “” returns TRUE overwrites. downstream logic depends whether something new written, consult return value. write_over() rarely called directly, usually called via use_template(), case handling apply return value.","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"helpers-and-the-active-project","dir":"","previous_headings":"Helper functions","what":"Helpers and the active project","title":"usethis design principles","text":"Two opposing mindsets: Helpers low-level general make direct use active project, change active project (activate first place). .e. project-based paths formed caller. Everything refer active project, unless ’s specific reason . Ideally, exported file writing helpers make direct reference active project. However, violate , due care, benefits us: write_utf8() potentially consults project path lives re: line ending. implementation takes care respect , also change active project. write_over() (can_overwrite(), really) , except case ’re determining whether path within Git repo. write_union() uses active project, exists, create humane path message. also actively avoids activating changing project. Git/GitHub helpers generally assume ’re working Git repo also active project. unexported. Prefer git_repo() proj_get(), choice, get benefit check_uses_git() ’s git_repo().","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"home-directory","dir":"","previous_headings":"","what":"Home directory","title":"usethis design principles","text":"usethis relies fs file system operations. main thing users notice treatment home directory Windows. Windows user’s home directory interpreted C:\\Users\\username (typical Unix-oriented tools, like Git ssh; also matches Python), opposed C:\\Users\\username\\Documents (R’s default Windows). order consistent everywhere, paths supplied user processed user_path_prep().","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"communicating-with-the-user","dir":"","previous_headings":"","what":"Communicating with the user","title":"usethis design principles","text":"User-facing messages ALWAYS emitted via helpers utils-ui.R. intentional preserved. can control verbosity package-wide usethis.quiet option, defaults FALSE. Exploited usethis tests: option set unset setup.R teardown.R, suppress output default. Individual tests need output, e.g. snapshot testing, include withr::local_options(usethis.quiet = FALSE). packages can muffle usethis call similar means. ui_silence() convenience helper executing small bits code silently. Note usethis exports many ui_*() functions historical reasons, defined ui-legacy.R, marked superseded now. See developer-facing article “Converting usethis’s UI use cli” .","code":""},{"path":"https://usethis.r-lib.org/dev/principles.html","id":"gitgithub","dir":"","previous_headings":"","what":"Git/GitHub","title":"usethis design principles","text":"GitHub remote configs pr_*() functions accept, plus : pr_init() calls github_remote_config(github_get = NA) challenges configs “” “fork”. want work “maybe” configs, sometimes ’re offline don’t PAT credential store. come development. pr_resume() checks config (indirectly) calls choose_branch(). want able use function offline absence PAT, since main job switch branches. seems inappropriate hard check GitHub remote config. pr_pause() calls target_repo(github_get = FALSE, ask = FALSE) therefore accept “maybe” configs. Similar reasoning pr_resume(): seems like work, e.g., offline, since ’s mostly switching branches. Eventually calls pr_pull_source_override(). pr_view() gets target repo github_get = NA, works “maybe” configs. Seems low stakes enough picky. pr_fetch(), pr_pull(), pr_merge_main(), pr_finish(), require “” “fork”, via early call target_repo(github_get = TRUE) check_for_config(). probably work configs, e.g., “”, ’s worth added complexity. pr_push() requires “” “fork” , fact, gets actual config, ’s potentially used select remote push (origin upstream) user can push . need create new Git URL decide HTTPS SSH: Consult existing remotes repo, probably origin, possible Call git_protocol(), something sensible default summoning Git credentials GitHub PAT doesn’t work user, help diagnose . credential management business aren’t going offer fine control , say, level individual functions. Functions might make commit use challenge_uncommitted_changes() initial sanity-checking block encourage starting clean state, .e. uncommitted files , untracked = TRUE specified, also untracked files. allow people proceed risk. Always make commits git_commit_ask(). git_commit(), wraps gert::git_add() gert::git_commit(), defined inside git_commit_ask(). Whenever possible, specify paths git_commit_ask(). almost always possible know exactly files might touched created. need make commit noninteractive context, like test, use gert::git_commit(). Use git_uncommitted(untracked = TRUE) git_ask_commit(untracked = TRUE) ’s possible work ’ve done created new file tracked. Use untracked = FALSE work modify pre-existing file.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/badges.html","id":null,"dir":"Reference","previous_headings":"","what":"README badges — badges","title":"README badges — badges","text":"helpers produce markdown text need README include badges report information, CRAN version test coverage, link relevant external resources. add badges automatically ensure badge block starts line containing ends line containing .","code":""},{"path":"https://usethis.r-lib.org/dev/reference/badges.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"README badges — badges","text":"","code":"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)"},{"path":"https://usethis.r-lib.org/dev/reference/badges.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"README badges — badges","text":"badge_name Badge name. Used error message alt text href, src Badge link image src stage Stage package lifecycle. One \"experimental\", \"stable\", \"superseded\", \"deprecated\". ref Git branch, tag, SHA urlpath optional urlpath component add link, e.g. \"rstudio\" open RStudio IDE instead Jupyter notebook. See binder documentation additional examples. url link existing Posit Cloud project. See Posit Cloud documentation details set project access obtain project link.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/badges.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"README badges — badges","text":"use_badge(): general helper used badge functions use_bioc_badge(): badge indicates BioConductor build status use_cran_badge(): badge indicates version package available CRAN, powered https://www.r-pkg.org use_lifecycle_badge(): badge declares developmental stage package according https://lifecycle.r-lib.org/articles/stages.html. use_binder_badge(): badge indicates repository can launched executable environment https://mybinder.org/ use_posit_cloud_badge(): badge indicates repository can launched Posit Cloud project use_rscloud_badge(): : Use use_posit_cloud_badge() instead.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/badges.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"README badges — badges","text":"","code":"if (FALSE) { # \\dontrun{ use_cran_badge() use_lifecycle_badge(\"stable\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/browse-this.html","id":null,"dir":"Reference","previous_headings":"","what":"Visit important project-related web pages — browse-this","title":"Visit important project-related web pages — browse-this","text":"functions take various web pages associated project (often, R package) return target URL(s) invisibly. form URLs consult: Git remotes configured active project appear hosted GitHub deployment DESCRIPTION file active project specified package. DESCRIPTION file sought first local package library CRAN. Fixed templates: Circle CI: https://circleci.com/gh/{OWNER}/{PACKAGE} CRAN landing page: https://cran.r-project.org/package={PACKAGE} GitHub mirror CRAN package: https://github.com/cran/{PACKAGE} Templated URLs checked existence, guarantee content destination.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/browse-this.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Visit important project-related web pages — browse-this","text":"","code":"browse_package(package = NULL) browse_project() browse_github(package = NULL) browse_github_issues(package = NULL, number = NULL) browse_github_pulls(package = NULL, number = NULL) browse_github_actions(package = NULL) browse_circleci(package = NULL) browse_cran(package = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/browse-this.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Visit important project-related web pages — browse-this","text":"package Name package. NULL, active project targeted, regardless whether R package . number Optional, specify individual GitHub issue pull request. Can number \"new\".","code":""},{"path":"https://usethis.r-lib.org/dev/reference/browse-this.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Visit important project-related web pages — browse-this","text":"browse_package(): Assembles list URLs lets user choose one visit web browser. non-interactive session, returns discovered URLs. browse_project(): Thin wrapper around browse_package() always targets active usethis project. browse_github(): Visits GitHub repository associated project. case fork, might asked specify interested source repo fork. browse_github_issues(): Visits GitHub Issues index one specific issue. browse_github_pulls(): Visits GitHub Pull Request index one specific pull request. browse_circleci(): Visits project's page Circle CI. browse_cran(): Visits package CRAN, via canonical URL.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/browse-this.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Visit important project-related web pages — browse-this","text":"","code":"# works on the active project # browse_project() browse_package(\"httr\") browse_github(\"gh\") #> ☐ Open URL . browse_github_issues(\"fs\") #> ☐ Open URL . browse_github_issues(\"fs\", 1) #> ☐ Open URL . browse_github_pulls(\"curl\") #> ☐ Open URL . browse_github_pulls(\"curl\", 183) #> ☐ Open URL . browse_cran(\"MASS\") #> ☐ Open URL ."},{"path":"https://usethis.r-lib.org/dev/reference/create_from_github.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a project from a GitHub repo — create_from_github","title":"Create a project from a GitHub repo — create_from_github","text":"Creates new local project Git repository repo GitHub, either cloning fork--cloning. fork--clone case, create_from_github() also additional remote branch setup, leaving perfect position make pull request pr_init(), one several functions working pull requests. create_from_github() works best GitHub credentials discoverable. See authentication.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/create_from_github.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a project from a GitHub repo — create_from_github","text":"","code":"create_from_github( repo_spec, destdir = NULL, fork = NA, rstudio = NULL, open = rlang::is_interactive(), protocol = git_protocol(), host = NULL )"},{"path":"https://usethis.r-lib.org/dev/reference/create_from_github.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a project from a GitHub repo — create_from_github","text":"repo_spec string identifying GitHub repo one forms: Plain OWNER/REPO spec Browser URL, \"https://github.com/OWNER/REPO\" HTTPS Git URL, \"https://github.com/OWNER/REPO.git\" SSH Git URL, \"git@github.com:OWNER/REPO.git\" destdir Destination new folder, named according REPO extracted repo_spec. Defaults location stored global option usethis.destdir, defined, user's Desktop similarly conspicuous place otherwise. fork FALSE, clone repo_spec. TRUE, fork repo_spec, clone fork, additional setup favorable future pull requests: source repo, repo_spec, configured upstream remote, using indicated protocol. local DEFAULT branch set track upstream/DEFAULT, DEFAULT typically main master. also immediately pulled, cover case pre-existing, --date fork. fork = NA (default), check permissions repo_spec. can push, set fork = FALSE, , set fork = TRUE. rstudio Initiate RStudio Project? Defaults TRUE RStudio session project pre-existing .Rproj file. Defaults FALSE otherwise (note cloned repo may already RStudio Project, .e. may already .Rproj file). open TRUE, activates new project: using RStudio desktop, package opened new session. RStudio server, current RStudio project activated. Otherwise, working directory active project changed. protocol One \"https\" \"ssh\" host GitHub host target, passed .api_url argument gh::gh(). repo_spec URL, host extracted . unspecified, gh defaults \"https://api.github.com\", although gh's default can customised setting GITHUB_API_URL environment variable. hypothetical GitHub Enterprise instance, either \"https://github.acme.com/api/v3\" \"https://github.acme.com\" acceptable.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/create_from_github.html","id":"git-github-authentication","dir":"Reference","previous_headings":"","what":"Git/GitHub Authentication","title":"Create a project from a GitHub repo — create_from_github","text":"Many usethis functions, including documented , potentially interact GitHub two different ways: Via GitHub REST API. Examples: create repo, fork, pull request. conventional Git remote. Examples: clone, fetch, push. Therefore two types auth can happen credentials must discoverable. credentials mean? GitHub personal access token (PAT) must discoverable gh package, used GitHub operations via REST API. See gh_token_help() getting configuring PAT. use HTTPS protocol Git remotes, PAT also used Git operations, git push. Usethis uses gert package , PAT must discoverable gert. Generally gert gh discover use PAT. ability \"kill two birds one stone\" HTTPS + PAT recommended auth strategy new Git GitHub PRs. use SSH remotes, SSH keys must also discoverable, addition PAT. public key must added GitHub account. Git/GitHub credential management covered dedicated article: Managing Git(Hub) Credentials","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/create_from_github.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create a project from a GitHub repo — create_from_github","text":"","code":"if (FALSE) { # \\dontrun{ create_from_github(\"r-lib/usethis\") # repo_spec can be a URL create_from_github(\"https://github.com/r-lib/usethis\") # a URL repo_spec also specifies the host (e.g. GitHub Enterprise instance) create_from_github(\"https://github.acme.com/OWNER/REPO\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/create_package.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a package or project — create_package","title":"Create a package or project — create_package","text":"functions create R project: create_package() creates R package create_project() creates non-package project, .e. data analysis project functions can called existing project; asked existing files changed.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/create_package.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a package or project — create_package","text":"","code":"create_package( path, fields = list(), rstudio = rstudioapi::isAvailable(), roxygen = TRUE, check_name = TRUE, open = rlang::is_interactive() ) create_project( path, rstudio = rstudioapi::isAvailable(), open = rlang::is_interactive() )"},{"path":"https://usethis.r-lib.org/dev/reference/create_package.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a package or project — create_package","text":"path path. exists, used. exist, created, provided parent path exists. fields named list fields add DESCRIPTION, potentially overriding default values. See use_description() can set personalized defaults using package options. rstudio TRUE, calls use_rstudio() make new package project RStudio Project. FALSE non-package project, sentinel .file placed directory can recognized project rprojroot packages. roxygen plan use roxygen2 document package? check_name Whether check name valid CRAN throw error . open TRUE, activates new project: using RStudio desktop, package opened new session. RStudio server, current RStudio project activated. Otherwise, working directory active project changed.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/create_package.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create a package or project — create_package","text":"Path newly created project package, invisibly.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/edit.html","id":null,"dir":"Reference","previous_headings":"","what":"Open configuration files — edit","title":"Open configuration files — edit","text":"edit_r_profile() opens .Rprofile edit_r_environ() opens .Renviron edit_r_makevars() opens .R/Makevars edit_git_config() opens .gitconfig .git/config edit_git_ignore() opens global (user-level) gitignore file ensures path declared global Git config. edit_pkgdown_config opens pkgdown YAML configuration file current Project. edit_rstudio_snippets() opens RStudio's snippet config given type. edit_rstudio_prefs() opens RStudio's preference file.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/edit.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Open configuration files — edit","text":"","code":"edit_r_profile(scope = c(\"user\", \"project\")) edit_r_environ(scope = c(\"user\", \"project\")) edit_r_buildignore() edit_r_makevars(scope = c(\"user\", \"project\")) edit_rstudio_snippets( type = c(\"r\", \"markdown\", \"c_cpp\", \"css\", \"html\", \"java\", \"javascript\", \"python\", \"sql\", \"stan\", \"tex\", \"yaml\") ) edit_rstudio_prefs() edit_git_config(scope = c(\"user\", \"project\")) edit_git_ignore(scope = c(\"user\", \"project\")) edit_pkgdown_config()"},{"path":"https://usethis.r-lib.org/dev/reference/edit.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Open configuration files — edit","text":"scope Edit globally current user, locally current project type Snippet type (case insensitive text).","code":""},{"path":"https://usethis.r-lib.org/dev/reference/edit.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Open configuration files — edit","text":"Path file, invisibly.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/edit.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Open configuration files — edit","text":"edit_r_*() functions consult R's notion user's home directory. edit_git_*() functions (usethis general) inherit home directory behaviour fs package, differs R Windows. fs default conventional terms location user-level Git config files. See fs::path_home() details. Files created edit_rstudio_snippets() mask, supplement, built-default snippets. like built-snippets, copy include custom snippets.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/edit_file.html","id":null,"dir":"Reference","previous_headings":"","what":"Open file for editing — edit_file","title":"Open file for editing — edit_file","text":"Opens file editing RStudio, active environment, via utils::file.edit() otherwise. file exist, created. parent directory exist, also created. edit_template() specifically opens templates inst/templates use use_template().","code":""},{"path":"https://usethis.r-lib.org/dev/reference/edit_file.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Open file for editing — edit_file","text":"","code":"edit_file(path, open = rlang::is_interactive()) edit_template(template = NULL, open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/edit_file.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Open file for editing — edit_file","text":"path Path target file. open Whether open file interactive editing. template target template file. specified, existing template files offered interactive selection.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/edit_file.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Open file for editing — edit_file","text":"Target path, invisibly.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/edit_file.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Open file for editing — edit_file","text":"","code":"if (FALSE) { # \\dontrun{ edit_file(\"DESCRIPTION\") edit_file(\"~/.gitconfig\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":null,"dir":"Reference","previous_headings":"","what":"Get or set the default Git branch — git-default-branch","title":"Get or set the default Git branch — git-default-branch","text":"git_default_branch*() functions put structure around somewhat fuzzy (definitely real) concept default branch. particular, support new conventions around Git default branch name, globally specific project / Git repository.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Get or set the default Git branch — git-default-branch","text":"","code":"git_default_branch() git_default_branch_configure(name = \"main\") git_default_branch_rediscover(current_local_default = NULL) git_default_branch_rename(from = NULL, to = \"main\")"},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Get or set the default Git branch — git-default-branch","text":"name Default name initial branch new Git repositories. current_local_default Name local branch currently functioning default branch. unspecified, can often inferred. Name branch currently functioning default branch. New name default branch.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Get or set the default Git branch — git-default-branch","text":"Name default branch.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"background-on-the-default-branch","dir":"Reference","previous_headings":"","what":"Background on the default branch","title":"Get or set the default Git branch — git-default-branch","text":"Technically, Git official concept default branch. reality, almost Git repos effective default branch. one branch, ! branch bug fixes features get merged . branch see first visit repo site GitHub. Git remote, branch HEAD points . Historically, master common name default branch, main increasingly popular choice.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"git-default-branch-configure-","dir":"Reference","previous_headings":"","what":"git_default_branch_configure()","title":"Get or set the default Git branch — git-default-branch","text":"configures init.defaultBranch global (.k.user) level. setting determines name branch gets created make first commit new Git repo. init.defaultBranch affects local Git repos create future.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"git-default-branch-","dir":"Reference","previous_headings":"","what":"git_default_branch()","title":"Get or set the default Git branch — git-default-branch","text":"figures default branch current Git repo, integrating information local repo , applicable, upstream origin remote. local vs. remote mismatch, git_default_branch() throws error advice call git_default_branch_rediscover() repair situation. remote repo, default branch branch HEAD points . local repo, one branch, must default! Otherwise try identify relevant local branch looking specific branch names, order: whatever default branch upstream origin , applicable main master value Git option init.defaultBranch, usual deal local value, present, takes precedence global (.k.. user-level) value","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"git-default-branch-rediscover-","dir":"Reference","previous_headings":"","what":"git_default_branch_rediscover()","title":"Get or set the default Git branch — git-default-branch","text":"consults external authority – specifically, remote source repo GitHub – learn default branch current project / repo. match apparent local default branch (example, project switched master main), corresponding branch renaming local repo , relevant, fork. See https://happygitwithr.com/common-remote-setups.html GitHub remote configurations , e.g., mean source repo. function works configurations \"\", \"fork\", \"\".","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"git-default-branch-rename-","dir":"Reference","previous_headings":"","what":"git_default_branch_rename()","title":"Get or set the default Git branch — git-default-branch","text":"Note: works repo effectively . terms GitHub, must source repo personally , organization-owned, must admin permission source repo. renames default branch source repo GitHub calls git_default_branch_rediscover(), make necessary changes local repo , relevant, personal fork. See https://happygitwithr.com/common-remote-setups.html GitHub remote configurations , e.g., mean source repo. function works configurations \"\", \"fork\", \"no_github\". Regarding \"no_github\": course, function expect local repo GitHub remotes, primary use case.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git-default-branch.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Get or set the default Git branch — git-default-branch","text":"","code":"if (FALSE) { # \\dontrun{ git_default_branch() } # } if (FALSE) { # \\dontrun{ git_default_branch_configure() } # } if (FALSE) { # \\dontrun{ git_default_branch_rediscover() # you can always explicitly specify the local branch that's been playing the # role of the default git_default_branch_rediscover(\"unconventional_default_branch_name\") } # } if (FALSE) { # \\dontrun{ git_default_branch_rename() # you can always explicitly specify one or both branch names git_default_branch_rename(from = \"this\", to = \"that\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/git_branch_default.html","id":null,"dir":"Reference","previous_headings":"","what":"Deprecated Git functions — git_branch_default","title":"Deprecated Git functions — git_branch_default","text":"git_branch_default() replaced git_default_branch().","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git_branch_default.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Deprecated Git functions — git_branch_default","text":"","code":"git_branch_default()"},{"path":"https://usethis.r-lib.org/dev/reference/git_protocol.html","id":null,"dir":"Reference","previous_headings":"","what":"See or set the default Git protocol — git_protocol","title":"See or set the default Git protocol — git_protocol","text":"Git operations address remote use -called \"transport protocol\". usethis supports HTTPS SSH. protocol dictates Git URL format used usethis needs configure first GitHub remote repo: protocol = \"https\" implies https://github.com//.git protocol = \"ssh\" implies git@github.com:/.git Two helper functions available: git_protocol() reveals protocol \"force\". usethis v2.0.0, defaults \"https\". can change duration R session use_git_protocol(). Change default R sessions code like .Rprofile (easily editable via edit_r_profile()): use_git_protocol() sets Git protocol current R session protocol affects Git URL newly configured remotes. existing Git remote URLs always respected, whether HTTPS SSH.","code":"options(usethis.protocol = \"ssh\")"},{"path":"https://usethis.r-lib.org/dev/reference/git_protocol.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"See or set the default Git protocol — git_protocol","text":"","code":"git_protocol() use_git_protocol(protocol)"},{"path":"https://usethis.r-lib.org/dev/reference/git_protocol.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"See or set the default Git protocol — git_protocol","text":"protocol One \"https\" \"ssh\"","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git_protocol.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"See or set the default Git protocol — git_protocol","text":"protocol, either \"https\" \"ssh\"","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git_protocol.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"See or set the default Git protocol — git_protocol","text":"","code":"if (FALSE) { # \\dontrun{ git_protocol() use_git_protocol(\"ssh\") git_protocol() use_git_protocol(\"https\") git_protocol() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/git_sitrep.html","id":null,"dir":"Reference","previous_headings":"","what":"Git/GitHub sitrep — git_sitrep","title":"Git/GitHub sitrep — git_sitrep","text":"Get situation report current Git/GitHub status. Useful diagnosing problems. default report values; provide values tool scope specific.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git_sitrep.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Git/GitHub sitrep — git_sitrep","text":"","code":"git_sitrep(tool = c(\"git\", \"github\"), scope = c(\"user\", \"project\"))"},{"path":"https://usethis.r-lib.org/dev/reference/git_sitrep.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Git/GitHub sitrep — git_sitrep","text":"tool Report git, github scope Report globally current user, locally current project","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git_sitrep.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Git/GitHub sitrep — git_sitrep","text":"","code":"if (FALSE) { # \\dontrun{ # report all git_sitrep() # report git for current user git_sitrep(\"git\", \"user\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/git_vaccinate.html","id":null,"dir":"Reference","previous_headings":"","what":"Vaccinate your global gitignore file — git_vaccinate","title":"Vaccinate your global gitignore file — git_vaccinate","text":"Adds .Rproj.user, .Rhistory, .Rdata, .httr-oauth, .DS_Store, .quarto global (.k.. user-level) .gitignore. good practice decreases chance accidentally leak credentials GitHub. git_vaccinate() also tries detect fix situation global gitignore file, missing global Git config.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/git_vaccinate.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Vaccinate your global gitignore file — git_vaccinate","text":"","code":"git_vaccinate()"},{"path":"https://usethis.r-lib.org/dev/reference/github-token.html","id":null,"dir":"Reference","previous_headings":"","what":"Get help with GitHub personal access tokens — github-token","title":"Get help with GitHub personal access tokens — github-token","text":"personal access token (PAT) needed certain tasks usethis via GitHub API, creating repository, fork, pull request. use HTTPS remotes, PAT also used interacting GitHub conventional Git remote. functions help get manage PAT: gh_token_help() guides token troubleshooting setup. create_github_token() opens browser window GitHub form generate PAT, suggested scopes pre-selected. also offers advice storing PAT. gitcreds::gitcreds_set() helps register PAT Git credential manager used operating system. Later, packages, usethis, gert, gh can automatically retrieve PAT use work GitHub behalf. Usually, first time PAT retrieved R session, cached environment variable, easier reuse duration R session. initial acquisition storage, happen automatically background. GitHub encouraging use PATs expire , e.g., 30 days, prepare re-generate re-store PAT periodically. Git/GitHub credential management covered dedicated article: Managing Git(Hub) Credentials","code":""},{"path":"https://usethis.r-lib.org/dev/reference/github-token.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Get help with GitHub personal access tokens — github-token","text":"","code":"create_github_token( scopes = c(\"repo\", \"user\", \"gist\", \"workflow\"), description = \"DESCRIBE THE TOKEN'S USE CASE\", host = NULL ) gh_token_help(host = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/github-token.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Get help with GitHub personal access tokens — github-token","text":"scopes Character vector token scopes, pre-selected web form. Final choices made GitHub form. Read GitHub API scopes https://docs.github.com/apps/building-oauth-apps/understanding-scopes--oauth-apps/. description Short description nickname token. might (eventually) multiple tokens GitHub account label can help keep track token . host GitHub host target, passed .api_url argument gh::gh(). unspecified, gh defaults \"https://api.github.com\", although gh's default can customised setting GITHUB_API_URL environment variable. hypothetical GitHub Enterprise instance, either \"https://github.acme.com/api/v3\" \"https://github.acme.com\" acceptable.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/github-token.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Get help with GitHub personal access tokens — github-token","text":"Nothing","code":""},{"path":"https://usethis.r-lib.org/dev/reference/github-token.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Get help with GitHub personal access tokens — github-token","text":"create_github_token() previously gone names: browse_github_token() browse_github_pat().","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/github-token.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Get help with GitHub personal access tokens — github-token","text":"","code":"if (FALSE) { # \\dontrun{ create_github_token() } # } if (FALSE) { # \\dontrun{ gh_token_help() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/issue-this.html","id":null,"dir":"Reference","previous_headings":"","what":"Helpers for GitHub issues — issue-this","title":"Helpers for GitHub issues — issue-this","text":"issue_* family functions allows perform common operations GitHub issues within R. designed help efficiently deal large numbers issues, particularly motivated challenges faced tidyverse team. issue_close_community() closes issue, bug report feature request, points author towards Posit Community better place discuss usage (https://forum.posit.co). issue_reprex_needed() labels issue \"reprex\" label gives author advice needed.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/issue-this.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Helpers for GitHub issues — issue-this","text":"","code":"issue_close_community(number, reprex = FALSE) issue_reprex_needed(number)"},{"path":"https://usethis.r-lib.org/dev/reference/issue-this.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Helpers for GitHub issues — issue-this","text":"number Issue number reprex issue also need reprex?","code":""},{"path":"https://usethis.r-lib.org/dev/reference/issue-this.html","id":"saved-replies","dir":"Reference","previous_headings":"","what":"Saved replies","title":"Helpers for GitHub issues — issue-this","text":"Unlike GitHub's \"saved replies\", functions can: shared people Perform actions, like labelling, closing additional arguments Include randomness (like friendly gifs)","code":""},{"path":"https://usethis.r-lib.org/dev/reference/issue-this.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Helpers for GitHub issues — issue-this","text":"","code":"if (FALSE) { # \\dontrun{ issue_close_community(12, reprex = TRUE) issue_reprex_needed(241) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/licenses.html","id":null,"dir":"Reference","previous_headings":"","what":"License a package — licenses","title":"License a package — licenses","text":"Adds necessary infrastructure declare package licensed one popular open source licenses: Permissive: MIT: simple permissive. Apache 2.0: MIT + provides patent protection. Copyleft: GPL v2: requires sharing improvements. GPL v3: requires sharing improvements. AGPL v3: requires sharing improvements. LGPL v2.1: requires sharing improvements. LGPL v3: requires sharing improvements. Creative commons licenses appropriate data packages: CC0: dedicated public domain. CC-: Free share adapt, must give appropriate credit. See https://choosealicense.com details options. Alternatively, code want share others, use_proprietary_license() makes clear rights reserved, code open source.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/licenses.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"License a package — licenses","text":"","code":"use_mit_license(copyright_holder = NULL) use_gpl_license(version = 3, include_future = TRUE) use_agpl_license(version = 3, include_future = TRUE) use_lgpl_license(version = 3, include_future = TRUE) use_apache_license(version = 2, include_future = TRUE) use_cc0_license() use_ccby_license() use_proprietary_license(copyright_holder)"},{"path":"https://usethis.r-lib.org/dev/reference/licenses.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"License a package — licenses","text":"copyright_holder Name copyright holder holders. defaults \"{package name} authors\"; change use CLA assign copyright single entity. version License version. defaults latest version licenses. include_future TRUE, license package current potential future versions license. generally considered good practice means package automatically include \"bug\" fixes licenses.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/licenses.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"License a package — licenses","text":"CRAN permit include copies standard licenses package, functions save license LICENSE.md add .Rbuildignore.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/proj_activate.html","id":null,"dir":"Reference","previous_headings":"","what":"Activate a project — proj_activate","title":"Activate a project — proj_activate","text":"Activates project usethis, R session, (relevant) RStudio senses. RStudio, open new RStudio session. , change working directory active project.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/proj_activate.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Activate a project — proj_activate","text":"","code":"proj_activate(path)"},{"path":"https://usethis.r-lib.org/dev/reference/proj_activate.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Activate a project — proj_activate","text":"path Project directory","code":""},{"path":"https://usethis.r-lib.org/dev/reference/proj_activate.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Activate a project — proj_activate","text":"Single logical value indicating current session modified.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/proj_sitrep.html","id":null,"dir":"Reference","previous_headings":"","what":"Report working directory and usethis/RStudio project — proj_sitrep","title":"Report working directory and usethis/RStudio project — proj_sitrep","text":"proj_sitrep() reports current working directory active usethis project active RStudio Project Call function things seem weird sure wrong fix . Usually, three coincide (unset) proj_sitrep() provides suggested commands getting back happy state.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/proj_sitrep.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Report working directory and usethis/RStudio project — proj_sitrep","text":"","code":"proj_sitrep()"},{"path":"https://usethis.r-lib.org/dev/reference/proj_sitrep.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Report working directory and usethis/RStudio project — proj_sitrep","text":"named list, S3 class sitrep (printing purposes), reporting current working directory, active usethis project, active RStudio Project","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/proj_sitrep.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Report working directory and usethis/RStudio project — proj_sitrep","text":"","code":"proj_sitrep() #> • working_directory: #> \"/home/runner/work/usethis/usethis/docs/dev/reference\" #> • active_usethis_proj: #> • active_rstudio_proj: #> ℹ There is currently no active usethis project. #> ℹ usethis attempts to activate a project upon first need. #> ☐ Call `usethis::proj_get()` to initiate project discovery. #> ☐ Call `proj_set(\"path/to/project\")` or #> `proj_activate(\"path/to/project\")` to provide an explicit path."},{"path":"https://usethis.r-lib.org/dev/reference/proj_utils.html","id":null,"dir":"Reference","previous_headings":"","what":"Utility functions for the active project — proj_utils","title":"Utility functions for the active project — proj_utils","text":"use_*() functions act active project. unset, usethis uses rprojroot find project root current working directory. establishes project root looking .file, RStudio Project, package DESCRIPTION, Git infrastructure, remake.yml file, .projectile file. stores active project use remainder session. general, end user scripts contain direct calls usethis::proj_*() utility functions. internal functions exported occasional interactive use use packages extend usethis. End user code call functions rprojroot simpler companion, , programmatically detect project build paths within . puzzled path (usually current working directory) appear inside project, can helpful call ::dr_here() get much verbose feedback.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/proj_utils.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Utility functions for the active project — proj_utils","text":"","code":"proj_get() proj_set(path = \".\", force = FALSE) proj_path(..., ext = \"\") with_project( path = \".\", code, force = FALSE, setwd = TRUE, quiet = getOption(\"usethis.quiet\", default = FALSE) ) local_project( path = \".\", force = FALSE, setwd = TRUE, quiet = getOption(\"usethis.quiet\", default = FALSE), .local_envir = parent.frame() )"},{"path":"https://usethis.r-lib.org/dev/reference/proj_utils.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Utility functions for the active project — proj_utils","text":"path Path set. path exist NULL. force TRUE, use path without checking usual criteria project. Use sparingly! main application solve temporary chicken-egg problem: need set active project order add project-signalling infrastructure, initialising Git repo adding DESCRIPTION file. ... character vectors, values NA, result also NA. paths follow recycling rules used tibble package, namely length 1 arguments recycled. ext optional extension append generated path. code Code run temporary active project setwd Whether also temporarily set working directory active project, NULL quiet Whether suppress user-facing messages, operating temporary active project .local_envir environment use scoping. Defaults current execution environment.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/proj_utils.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Utility functions for the active project — proj_utils","text":"proj_get(): Retrieves active project , necessary, attempts set first place. proj_set(): Sets active project. proj_path(): Builds paths within active project returned proj_get(). Thin wrapper around fs::path(). with_project(): Runs code temporary active project , optionally, working directory. example with_*() functions withr. local_project(): Sets active project , optionally, working directory current execution environment goes scope, e.g. end current function test. example local_*() functions withr.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/proj_utils.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Utility functions for the active project — proj_utils","text":"","code":"if (FALSE) { # \\dontrun{ ## see the active project proj_get() ## manually set the active project proj_set(\"path/to/target/project\") ## build a path within the active project (both produce same result) proj_path(\"R/foo.R\") proj_path(\"R\", \"foo\", ext = \"R\") ## build a path within SOME OTHER project with_project(\"path/to/some/other/project\", proj_path(\"blah.R\")) ## convince yourself that with_project() temporarily changes the project with_project(\"path/to/some/other/project\", print(proj_sitrep())) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":null,"dir":"Reference","previous_headings":"","what":"Helpers for GitHub pull requests — pull-requests","title":"Helpers for GitHub pull requests — pull-requests","text":"pr_* family functions designed make working GitHub pull requests (PRs) painless possible contributors package maintainers. use pr_* functions, project must Git repo one GitHub remote configurations: \"\": can push GitHub remote configured origin fork. \"fork\": can push GitHub remote configured origin, fork, parent configured upstream. origin points personal copy upstream points source repo. \"\" \"fork\" two several GitHub remote configurations examined Common remote setups Happy Git GitHub useR. Pull Request Helpers article walks process making pull request pr_* functions. pr_* functions also use Git/GitHub credentials carry various remote operations; see auth. pr_* functions also proactively check agreement re: default branch local repo source repo. See git_default_branch() .","code":""},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Helpers for GitHub pull requests — pull-requests","text":"","code":"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()"},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Helpers for GitHub pull requests — pull-requests","text":"branch Name new existing local branch. creating new branch, note usually consist lower case letters, numbers, -. number Number PR. target repo target? question case fork. fork, slim chance want consider pull requests fork (primary repo, .e. origin) instead source repo (.e. upstream, default).","code":""},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":"git-github-authentication","dir":"Reference","previous_headings":"","what":"Git/GitHub Authentication","title":"Helpers for GitHub pull requests — pull-requests","text":"Many usethis functions, including documented , potentially interact GitHub two different ways: Via GitHub REST API. Examples: create repo, fork, pull request. conventional Git remote. Examples: clone, fetch, push. Therefore two types auth can happen credentials must discoverable. credentials mean? GitHub personal access token (PAT) must discoverable gh package, used GitHub operations via REST API. See gh_token_help() getting configuring PAT. use HTTPS protocol Git remotes, PAT also used Git operations, git push. Usethis uses gert package , PAT must discoverable gert. Generally gert gh discover use PAT. ability \"kill two birds one stone\" HTTPS + PAT recommended auth strategy new Git GitHub PRs. use SSH remotes, SSH keys must also discoverable, addition PAT. public key must added GitHub account. Git/GitHub credential management covered dedicated article: Managing Git(Hub) Credentials","code":""},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":"for-contributors","dir":"Reference","previous_headings":"","what":"For contributors","title":"Helpers for GitHub pull requests — pull-requests","text":"contribute package, first use create_from_github(\"OWNER/REPO\"). forks source repository checks local copy. Next use pr_init() create branch PR. best practice never make commits default branch branch fork (usually named main master), . pull request always come feature branch. much easier pull upstream changes fork parent allow work feature branches. also much easier maintainer explore extend PR create feature branch. Work locally, branch, making changes files, committing work. ready create PR, run pr_push() push local branch GitHub, open webpage lets initiate PR (draft PR). learn process making pull request, read Pull Request Helpers vignette. lucky, PR perfect, maintainer accept . can run pr_finish() delete PR branch. cases, however, maintainer ask make changes. Make changes, run pr_push() update PR. also possible maintainer contribute code PR: get changes back onto computer, run pr_pull(). can also happen changes occurred package since first created PR. might need merge default branch (usually named main master) PR branch. running pr_merge_main(): makes sure PR compatible primary repo's main line development. pr_pull() pr_merge_main() can result merge conflicts, prepared resolve continuing.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":"for-maintainers","dir":"Reference","previous_headings":"","what":"For maintainers","title":"Helpers for GitHub pull requests — pull-requests","text":"download PR locally can experiment , run pr_fetch() select PR , already know number, call pr_fetch(). make changes, run pr_push() push back GitHub. merged PR, run pr_finish() delete local branch remove remote associated contributor's fork.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":"overview-of-all-the-functions","dir":"Reference","previous_headings":"","what":"Overview of all the functions","title":"Helpers for GitHub pull requests — pull-requests","text":"pr_init(): contributor, start work new PR ensuring local repo --date, creating checking new branch. Nothing pushed created GitHub call pr_push(). pr_fetch(): maintainer, review contribute changes existing PR creating local branch tracks remote PR. pr_fetch() little work possible, can also use resume work PR already local branch (also ensure local branch --date). called arguments, 9 open PRs offered interactive selection. pr_resume(): Resume work PR switching existing local branch pulling changes upstream tracking branch, one. called arguments, 9 local branches offered interactive selection, preference branches connected PRs branches recent activity. pr_push(): first time called, PR branch pushed GitHub taken webpage new PR (draft PR) can created. also sets local branch track remote counterpart. Subsequent calls pr_push() make sure local branch remote changes , , pushes local changes, thereby updating PR. pr_pull(): Pulls changes local branch's remote tracking branch. maintainer extended PR, bring changes back local work. pr_merge_main(): Pulls changes default branch source repo current local branch. can used local branch default branch PR branch. pr_pause(): Makes sure --date remote changes PR. switches back default branch pulls source repo. Use pr_resume() name branch use pr_fetch() resume using PR number. pr_view(): Visits PR associated current branch browser (default) specific PR identified number. (FYI browse_github_pulls() handy way visit list PRs current project.) pr_forget(): local clean current branch actual notional PR want abandon. Maybe initiated , via pr_init(), used pr_fetch() explore PR GitHub. local operations: update delete remote branches, close PRs. Alerts user uncommitted unpushed work risk lost. user chooses proceed, switches back default branch, pulls changes source repo, deletes local PR branch. associated Git remote deleted, \"forgotten\" PR branch using . pr_finish(): post-PR clean , actually merge close PR (maintainer browser). number given, infers PR upstream tracking branch current branch. number given, matter whether PR exists locally. PR exists locally, alerts user uncommitted unpushed changes, switches back default branch, pulls changes source repo, deletes local PR branch. PR came external fork, associated Git remote deleted, provided use local branches. PR merged user permission, deletes remote branch (remote operation pr_finish() potentially ).","code":""},{"path":"https://usethis.r-lib.org/dev/reference/pull-requests.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Helpers for GitHub pull requests — pull-requests","text":"","code":"if (FALSE) { # \\dontrun{ pr_fetch(123) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/rename_files.html","id":null,"dir":"Reference","previous_headings":"","what":"Automatically rename paired R/ and test/ files — rename_files","title":"Automatically rename paired R/ and test/ files — rename_files","text":"Moves R/{old}.R R/{new}.R Moves src/{old}.* src/{new}.* Moves tests/testthat/test-{old}.R tests/testthat/test-{new}.R Moves tests/testthat/test-{old}-*.* tests/testthat/test-{new}-*.* updates paths test file. Removes context() calls test file, unnecessary (discouraged) testthat v2.1.0. potentially dangerous operation, must using Git order use function.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/rename_files.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Automatically rename paired R/ and test/ files — rename_files","text":"","code":"rename_files(old, new)"},{"path":"https://usethis.r-lib.org/dev/reference/rename_files.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Automatically rename paired R/ and test/ files — rename_files","text":"old, new Old new file names (without .R extensions).","code":""},{"path":"https://usethis.r-lib.org/dev/reference/rprofile-helper.html","id":null,"dir":"Reference","previous_headings":"","what":"Helpers to make useful changes to .Rprofile — rprofile-helper","title":"Helpers to make useful changes to .Rprofile — rprofile-helper","text":"functions open .Rprofile give code need paste . use_devtools(): makes devtools available interactive sessions. use_usethis(): makes usethis available interactive sessions. use_reprex(): makes reprex available interactive sessions. use_conflicted(): makes conflicted available interactive sessions. use_partial_warnings(): warns partial matches.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/rprofile-helper.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Helpers to make useful changes to .Rprofile — rprofile-helper","text":"","code":"use_conflicted() use_reprex() use_usethis() use_devtools() use_partial_warnings()"},{"path":"https://usethis.r-lib.org/dev/reference/tidyverse.html","id":null,"dir":"Reference","previous_headings":"","what":"Helpers for tidyverse development — use_tidy_github_actions","title":"Helpers for tidyverse development — use_tidy_github_actions","text":"helpers follow tidyverse conventions generally little stricter defaults, reflecting need greater rigor commonly used packages.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/tidyverse.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Helpers for tidyverse development — use_tidy_github_actions","text":"","code":"use_tidy_github_actions(ref = NULL) create_tidy_package(path, copyright_holder = NULL) use_tidy_description() use_tidy_dependencies() use_tidy_contributing() use_tidy_support() use_tidy_issue_template() use_tidy_coc() use_tidy_github() use_tidy_style(strict = TRUE) use_tidy_logo(geometry = \"240x278\", retina = TRUE) use_tidy_upkeep_issue(last_upkeep = last_upkeep_year())"},{"path":"https://usethis.r-lib.org/dev/reference/tidyverse.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Helpers for tidyverse development — use_tidy_github_actions","text":"ref Desired Git reference, usually name tag (\"v2\") branch (\"main\"). possibilities include commit SHA (\"d1c516d\") \"HEAD\" (meaning \"tip remote's default branch\"). specified, defaults latest published release r-lib/actions (https://github.com/r-lib/actions/releases). path path. exists, used. exist, created, provided parent path exists. copyright_holder Name copyright holder holders. defaults \"{package name} authors\"; change use CLA assign copyright single entity. strict Boolean indicating whether strict version styling applied. See styler::tidyverse_style() details. geometry magick::geometry string specifying size. default assumes hex logo using spec http://hexb./sticker.html. retina TRUE, default, scales image README, assuming geometry double desired size. last_upkeep Year last upkeep. default, Config/usethis/last-upkeep field DESCRIPTION consulted , defined. information last upkeep, issue contain full checklist.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/tidyverse.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Helpers for tidyverse development — use_tidy_github_actions","text":"use_tidy_github_actions(): Sets following workflows using GitHub Actions: Run R CMD check current release, devel, four previous versions R. build matrix also ensures R CMD check run least three major operating systems (Linux, macOS, Windows). Report test coverage. Build deploy pkgdown site. Provide two commands used pull requests: /document run roxygen2::roxygenise() update PR, /style run styler::style_pkg() update PR. tidyverse team checks packages, overkill less widely used packages. Consider using streamlined workflows set use_github_actions() use_github_action_check_standard(). create_tidy_package(): creates new package, immediately applies many tidyverse conventions possible, issues reminders, activates new package. use_tidy_dependencies(): sets standard dependencies used tidyverse packages (except packages designed dependency free). use_tidy_description(): puts fields standard order alphabetises dependencies. use_tidy_eval(): imports standard set helpers facilitate programming tidy eval toolkit. use_tidy_style(): styles source code according tidyverse style guide. function overwrite files! See usage advice. use_tidy_contributing(): adds standard tidyverse contributing guidelines. use_tidy_issue_template(): adds standard tidyverse issue template. use_tidy_release_test_env(): updates test environment section cran-comments.md. use_tidy_support(): adds standard description support resources tidyverse. use_tidy_coc(): equivalent use_code_of_conduct(), puts document .github/ subdirectory. use_tidy_github(): convenience wrapper calls use_tidy_contributing(), use_tidy_issue_template(), use_tidy_support(), use_tidy_coc(). use_tidy_github_labels() calls use_github_labels() implement tidyverse conventions around GitHub issue label names colours. use_tidy_upkeep_issue() creates issue containing checklist actions bring package current tidyverse standards. Also records current date Config/usethis/last-upkeep field DESCRIPTION. use_tidy_logo() calls use_logo() appropriate hex sticker PNG file https://github.com/rstudio/hex-stickers.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/tidyverse.html","id":"use-tidy-style-","dir":"Reference","previous_headings":"","what":"use_tidy_style()","title":"Helpers for tidyverse development — use_tidy_github_actions","text":"Uses styler package package style code package, project, directory, according tidyverse style guide. Warning: function overwrite files! strongly suggested style files version control first create backup copy. Invisibly returns data frame one row per file, indicates whether styling caused change.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-legacy-functions.html","id":null,"dir":"Reference","previous_headings":"","what":"Legacy functions related to user interface — ui-legacy-functions","title":"Legacy functions related to user interface — ui-legacy-functions","text":"functions now superseded. External users usethis::ui_*() functions encouraged use cli package instead. cli package required functionality usethis::ui_*() functions created, now superior option. even cli vignette make transition: vignette(\"usethis-ui\", package = \"cli\"). usethis now uses cli internally UI, new functions exported presumably never . developer-focused article process transitioning usethis's UI use cli: Converting usethis's UI use cli.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-legacy-functions.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Legacy functions related to user interface — ui-legacy-functions","text":"","code":"ui_line(x = character(), .envir = parent.frame()) ui_todo(x, .envir = parent.frame()) ui_done(x, .envir = parent.frame()) ui_oops(x, .envir = parent.frame()) ui_info(x, .envir = parent.frame()) ui_code_block(x, copy = rlang::is_interactive(), .envir = parent.frame()) ui_stop(x, .envir = parent.frame()) ui_warn(x, .envir = parent.frame()) ui_field(x) ui_value(x) ui_path(x, base = NULL) ui_code(x) ui_unset(x = \"unset\")"},{"path":"https://usethis.r-lib.org/dev/reference/ui-legacy-functions.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Legacy functions related to user interface — ui-legacy-functions","text":"x character vector. block styles, conditions, questions, element vector becomes line, result processed glue::glue(). inline styles, element vector becomes entry comma separated list. .envir Used ensure glue::glue() gets correct environment. expert use . copy TRUE, session interactive, clipr package installed, copy code block clipboard. base specified, paths displayed relative path.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-legacy-functions.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Legacy functions related to user interface — ui-legacy-functions","text":"block styles, conditions, questions called side-effect. inline styles return string.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-legacy-functions.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Legacy functions related to user interface — ui-legacy-functions","text":"ui_ functions can broken four main categories: block styles: ui_line(), ui_done(), ui_todo(), ui_oops(), ui_info(). conditions: ui_stop(), ui_warn(). questions: ui_yeah(), ui_nope(). inline styles: ui_field(), ui_value(), ui_path(), ui_code(), ui_unset(). question functions ui_yeah() ui_nope() help page. UI output (apart ui_yeah()/ui_nope() prompts) can silenced setting options(usethis.quiet = TRUE). Use ui_silence() silence selected actions.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-legacy-functions.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Legacy functions related to user interface — ui-legacy-functions","text":"","code":"new_val <- \"oxnard\" ui_done(\"{ui_field('name')} set to {ui_value(new_val)}\") #> ✔ name set to 'oxnard' ui_todo(\"Redocument with {ui_code('devtools::document()')}\") #> • Redocument with `devtools::document()` ui_code_block(c( \"Line 1\", \"Line 2\", \"Line 3\" )) #> Line 1 #> Line 2 #> Line 3"},{"path":"https://usethis.r-lib.org/dev/reference/ui-questions.html","id":null,"dir":"Reference","previous_headings":"","what":"User interface - Questions — ui-questions","title":"User interface - Questions — ui-questions","text":"ui_yeah() ui_nope() technically superseded, , unlike rest legacy ui_*() functions, yet drop-replacement available cli package. ui_yeah() ui_nope() longer used internally usethis.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-questions.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"User interface - Questions — ui-questions","text":"","code":"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() )"},{"path":"https://usethis.r-lib.org/dev/reference/ui-questions.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"User interface - Questions — ui-questions","text":"x character vector. block styles, conditions, questions, element vector becomes line, result processed glue::glue(). inline styles, element vector becomes entry comma separated list. yes character vector \"yes\" strings, randomly sampled populate menu. character vector \"\" strings, randomly sampled populate menu. n_yes integer. number \"yes\" strings include. n_no integer. number \"\" strings include. shuffle logical. order menu options randomly shuffled? .envir Used ensure glue::glue() gets correct environment. expert use .","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-questions.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"User interface - Questions — ui-questions","text":"logical. ui_yeah() returns TRUE user selects \"yes\" option FALSE otherwise, .e. user selects \"\" option refuses make selection (cancels). ui_nope() logical opposite ui_yeah().","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui-questions.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"User interface - Questions — ui-questions","text":"","code":"if (FALSE) { # \\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) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/ui_silence.html","id":null,"dir":"Reference","previous_headings":"","what":"Suppress usethis's messaging — ui_silence","title":"Suppress usethis's messaging — ui_silence","text":"Execute bit code without usethis's normal messaging.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui_silence.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Suppress usethis's messaging — ui_silence","text":"","code":"ui_silence(code)"},{"path":"https://usethis.r-lib.org/dev/reference/ui_silence.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Suppress usethis's messaging — ui_silence","text":"code Code execute usual UI output silenced.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui_silence.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Suppress usethis's messaging — ui_silence","text":"Whatever code returns.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/ui_silence.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Suppress usethis's messaging — ui_silence","text":"","code":"# compare the messaging you see from this: browse_github(\"usethis\") #> ☐ Open URL . # vs. this: ui_silence( browse_github(\"usethis\") )"},{"path":"https://usethis.r-lib.org/dev/reference/use_addin.html","id":null,"dir":"Reference","previous_headings":"","what":"Add minimal RStudio Addin binding — use_addin","title":"Add minimal RStudio Addin binding — use_addin","text":"function helps add minimal RStudio Addin binding inst/rstudio/addins.dcf.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_addin.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add minimal RStudio Addin binding — use_addin","text":"","code":"use_addin(addin = \"new_addin\", open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_addin.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add minimal RStudio Addin binding — use_addin","text":"addin Name addin function, defined R folder. open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_author.html","id":null,"dir":"Reference","previous_headings":"","what":"Add an author to the Authors@R field in DESCRIPTION — use_author","title":"Add an author to the Authors@R field in DESCRIPTION — use_author","text":"use_author() adds person Authors@R field DESCRIPTION file, creating field necessary. modify, e.g., role(s) email existing author (judged using \"Given Family\" name). recommend editing DESCRIPTION directly. , programmatic use, consider calling specialized functions available desc package directly. use_author() also surfaces two situations might want address: Explicit use fields Author Maintainer. recommend switching modern Authors@R field instead, offers richer metadata various downstream uses. (Note Authors@R eventually processed create Author Maintainer fields, tar.gz built package source.) Presence fake author placed create_package() use_description(). happens usethis create DESCRIPTION file user given author information via fields argument global option \"usethis.description\". placeholder looks something like First Last [aut, cre] (-ORCID-ID) use_author() offers remove interactive sessions.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_author.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add an author to the Authors@R field in DESCRIPTION — use_author","text":"","code":"use_author(given = NULL, family = NULL, ..., role = \"ctb\")"},{"path":"https://usethis.r-lib.org/dev/reference/use_author.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add an author to the Authors@R field in DESCRIPTION — use_author","text":"given character vector given names, list thereof. family character string family name, list thereof. ... Arguments passed utils::person middle character string collapsed middle name(s). Deprecated, see Details. email character string (vector) giving e-mail address (), list thereof. comment character string (vector) providing comments, list thereof. first character string giving first name. Deprecated, see Details. last character string giving last name. Deprecated, see Details. role character vector specifying role(s) person (see Details), list thereof.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_author.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add an author to the Authors@R field in DESCRIPTION — use_author","text":"","code":"if (FALSE) { # \\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\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_blank_slate.html","id":null,"dir":"Reference","previous_headings":"","what":"Don't save/load user workspace between sessions — use_blank_slate","title":"Don't save/load user workspace between sessions — use_blank_slate","text":"R can save reload user's workspace sessions via .RData file current directory. However, long-term reproducibility enhanced turn feature clear R's memory every restart. Starting blank slate provides timely feedback encourages development scripts complete self-contained. detail can found blog post Project-oriented workflow.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_blank_slate.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Don't save/load user workspace between sessions — use_blank_slate","text":"","code":"use_blank_slate(scope = c(\"user\", \"project\"))"},{"path":"https://usethis.r-lib.org/dev/reference/use_blank_slate.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Don't save/load user workspace between sessions — use_blank_slate","text":"scope Edit globally current user, locally current project","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_build_ignore.html","id":null,"dir":"Reference","previous_headings":"","what":"Add files to .Rbuildignore — use_build_ignore","title":"Add files to .Rbuildignore — use_build_ignore","text":".Rbuildignore regular expression line, usually easier work specific file names. default, use_build_ignore() (crudely) turn filename regular expression match path. Repeated entries silently removed. use_build_ignore() designed ignore individual files. want ignore files given extension, consider providing \"-\" regular expression, using escape = FALSE; see examples.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_build_ignore.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add files to .Rbuildignore — use_build_ignore","text":"","code":"use_build_ignore(files, escape = TRUE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_build_ignore.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add files to .Rbuildignore — use_build_ignore","text":"files Character vector path names. escape TRUE, default, escape . \\\\. surround ^ $.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_build_ignore.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add files to .Rbuildignore — use_build_ignore","text":"","code":"if (FALSE) { # \\dontrun{ # ignore all Excel files use_build_ignore(\"[.]xlsx$\", escape = FALSE) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_citation.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a CITATION template — use_citation","title":"Create a CITATION template — use_citation","text":"Use want encourage users package cite article book.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_citation.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a CITATION template — use_citation","text":"","code":"use_citation()"},{"path":"https://usethis.r-lib.org/dev/reference/use_code_of_conduct.html","id":null,"dir":"Reference","previous_headings":"","what":"Add a code of conduct — use_code_of_conduct","title":"Add a code of conduct — use_code_of_conduct","text":"Adds CODE_OF_CONDUCT.md file active project lists .Rbuildignore, case package. goal code conduct foster environment inclusiveness, explicitly discourage inappropriate behaviour. template comes https://www.contributor-covenant.org, version 2.1: https://www.contributor-covenant.org/version/2/1/code_of_conduct/.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_code_of_conduct.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add a code of conduct — use_code_of_conduct","text":"","code":"use_code_of_conduct(contact, path = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_code_of_conduct.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add a code of conduct — use_code_of_conduct","text":"contact Contact details making code conduct report. Usually email address. path Path directory put CODE_OF_CONDUCT.md , relative active project. Passed along use_directory(). Default locate top-level, .github/ also common.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_code_of_conduct.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Add a code of conduct — use_code_of_conduct","text":"package going CRAN, link CoC README must absolute link rendered website CODE_OF_CONDUCT.md included package sent CRAN. use_code_of_conduct() automatically generate link (1) use pkgdown (2) set url field _pkgdown.yml; otherwise link copy CoC https://www.contributor-covenant.org.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":null,"dir":"Reference","previous_headings":"","what":"Helpers to download and unpack a ZIP file — use_course_details","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"Details internal helper functions power use_course() use_zip(). create_download_url() exported.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"","code":"tidy_download(url, destdir = getwd()) tidy_unzip(zipfile, cleanup = FALSE) create_download_url(url)"},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"url GitHub, DropBox, Google Drive URL. create_download_url(): URL copied web browser. tidy_download(): download link ZIP file, possibly behind shortlink redirect. create_download_url() can helpful creating URL typical browser URLs. destdir Path existing local directory ZIP file stored. Defaults current working directory, note use_course() different default behavior. zipfile Path local ZIP file. cleanup Whether delete ZIP file unpacking. interactive session, cleanup = NA leads asking user want delete keep ZIP file.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"tidy-download-","dir":"Reference","previous_headings":"","what":"tidy_download()","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"Special-purpose function download ZIP file automatically determine file name, often determines folder name unpacking. Developed DropBox GitHub primary targets, possibly via shortlinks. platforms offer way download entire folder repo ZIP file, information original folder repo transmitted Content-Disposition header. absence header, filename generated input URL. either case, filename sanitized. Returns path downloaded ZIP file, invisibly. tidy_download() setup retry download failure. interactive session, asks user's consent. retries use longer connect timeout.","code":"# how it's used inside use_course() tidy_download( # url has been processed with internal helper normalize_url() url, # conspicuous_place() = `getOption('usethis.destdir')` or desktop or home # directory or working directory destdir = destdir %||% conspicuous_place() )"},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"dropbox","dir":"Reference","previous_headings":"","what":"DropBox","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"make folder available ZIP download, create shared link : https://help.dropbox.com/share/create--share-link shared link form: Replace dl=0 end dl=1 create download link: can use create_download_url() conversion. download link (shortlink points ) suitable input tidy_download(). one redirections, link eventually lead download URL. details, see https://help.dropbox.com/share/force-download https://help.dropbox.com/sync/download-entire-folders.","code":"https://www.dropbox.com/sh/12345abcde/6789wxyz?dl=0 https://www.dropbox.com/sh/12345abcde/6789wxyz?dl=1"},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"github","dir":"Reference","previous_headings":"","what":"GitHub","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"Click repo's \"Clone download\" button, reveal \"Download ZIP\" button. Capture URL, form: download link (shortlink points ) suitable input tidy_download(). one redirections, link eventually lead download URL. links also lead ZIP download, albeit different filenaming scheme (REF branch name, tag, SHA): can use create_download_url() create \"Download ZIP\" URL typical GitHub browser URL.","code":"https://github.com/r-lib/usethis/archive/main.zip https://github.com/github.com/r-lib/usethis/zipball/HEAD https://api.github.com/repos/r-lib/rematch2/zipball/REF https://api.github.com/repos/r-lib/rematch2/zipball/HEAD https://api.github.com/repos/r-lib/usethis/zipball/REF"},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"google-drive","dir":"Reference","previous_headings":"","what":"Google Drive","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"knowledge, possible download Google Drive folder ZIP archive. however possible share ZIP file stored Google Drive. get URL, click \"Get shareable link\" (within \"Share\" menu). URL allow direct download, designed processed web browser first. sharing link looks like: able get URL suitable direct download, need extract \"id\" element URL include URL format: Use create_download_url() perform transformation automatically.","code":"https://drive.google.com/open?id=123456789xxyyyzzz https://drive.google.com/uc?export=download&id=123456789xxyyyzzz"},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"tidy-unzip-","dir":"Reference","previous_headings":"","what":"tidy_unzip()","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"Special-purpose function unpack ZIP file (attempt ) create directory structure people want. unpacking archive, easy get one one less level nesting expected. especially important finesse directory structure : want local result unzipping content either GitHub DropBox ZIP files, pack things differently. intent: ZIP archive foo.zip contain single top-level directory, .e. packed \"loose parts\", unzip directory named foo. Typical DropBox ZIP files. ZIP archive foo.zip single top-level directory (, way, necessarily called \"foo\"), unpack said directory. Typical GitHub ZIP files. Returns path directory holding unpacked files, invisibly. DropBox: ZIP files produced DropBox special. file list tends contain spurious directory \"/\", ignore unzip. Also, directory Git repo /RStudio Project, unzip-ignore various hidden files, .RData, .Rhistory, .git/ .Rproj.user.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_course_details.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Helpers to download and unpack a ZIP file — use_course_details","text":"","code":"if (FALSE) { # \\dontrun{ tidy_download(\"https://github.com/r-lib/rematch2/archive/main.zip\") tidy_unzip(\"rematch2-main.zip\") } # } # GitHub create_download_url(\"https://github.com/r-lib/usethis\") #> [1] \"https://github.com/r-lib/usethis/zipball/HEAD\" create_download_url(\"https://github.com/r-lib/usethis/issues\") #> [1] \"https://github.com/r-lib/usethis/zipball/HEAD\" # DropBox create_download_url(\"https://www.dropbox.com/sh/12345abcde/6789wxyz?dl=0\") #> [1] \"https://www.dropbox.com/sh/12345abcde/6789wxyz?dl=1\" # Google Drive create_download_url(\"https://drive.google.com/open?id=123456789xxyyyzzz\") #> [1] \"https://drive.google.com/uc?export=download&id=123456789xxyyyzzz\" create_download_url(\"https://drive.google.com/open?id=123456789xxyyyzzz/view\") #> [1] \"https://drive.google.com/uc?export=download&id=123456789xxyyyzzz\""},{"path":"https://usethis.r-lib.org/dev/reference/use_coverage.html","id":null,"dir":"Reference","previous_headings":"","what":"Test coverage — use_coverage","title":"Test coverage — use_coverage","text":"Adds test coverage reporting package, using either Codecov (https://codecov.io) Coveralls (https://coveralls.io).","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_coverage.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Test coverage — use_coverage","text":"","code":"use_coverage(type = c(\"codecov\", \"coveralls\"), repo_spec = NULL) use_covr_ignore(files)"},{"path":"https://usethis.r-lib.org/dev/reference/use_coverage.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Test coverage — use_coverage","text":"type web service use. repo_spec Optional GitHub repo specification form: owner/repo. can usually inferred GitHub remotes active project. files Character vector file globs.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_cpp11.html","id":null,"dir":"Reference","previous_headings":"","what":"Use C++ via the cpp11 package — use_cpp11","title":"Use C++ via the cpp11 package — use_cpp11","text":"Adds infrastructure needed use cpp11 package, header-R package helps R package developers handle R objects C++ code: Creates src/ Adds cpp11 DESCRIPTION Creates src/code.cpp, initial placeholder .cpp file","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_cpp11.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use C++ via the cpp11 package — use_cpp11","text":"","code":"use_cpp11()"},{"path":"https://usethis.r-lib.org/dev/reference/use_cran_comments.html","id":null,"dir":"Reference","previous_headings":"","what":"CRAN submission comments — use_cran_comments","title":"CRAN submission comments — use_cran_comments","text":"Creates cran-comments.md, template communications CRAN submitting package. goal clearly communicate steps taken check package wide range operating systems. submitting update package used packages, also need summarize results reverse dependency checks.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_cran_comments.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"CRAN submission comments — use_cran_comments","text":"","code":"use_cran_comments(open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_cran_comments.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"CRAN submission comments — use_cran_comments","text":"open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_data.html","id":null,"dir":"Reference","previous_headings":"","what":"Create package data — use_data","title":"Create package data — use_data","text":"use_data() makes easy save package data correct format. recommend save scripts generate package data data-raw: use use_data_raw() set . also need document exported datasets.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_data.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create package data — use_data","text":"","code":"use_data( ..., internal = FALSE, overwrite = FALSE, compress = \"bzip2\", version = 3, ascii = FALSE ) use_data_raw(name = \"DATASET\", open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_data.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create package data — use_data","text":"... Unquoted names existing objects save. internal FALSE, saves object .rda file data/ directory. data files bypass usual export mechanism available whenever package loaded (via data() LazyData true). TRUE, stores objects single R/sysdata.rda file. Objects file follow usual export rules. Note means exported using common exportPattern() rule exports objects except start .. overwrite default, use_data() overwrite existing files. really want , set TRUE. compress Choose type compression used save(). one \"gzip\", \"bzip2\", \"xz\". version serialization format version use. default, 3, can read R versions 3.5.0 higher. R 1.4.0 3.5.3, use version 2. ascii TRUE, ASCII representation data written. default value ascii FALSE leads binary file written. NA version >= 2, different ASCII representation used writes double/complex numbers binary fractions. name Name dataset prepared inclusion package. open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_data.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create package data — use_data","text":"","code":"if (FALSE) { # \\dontrun{ x <- 1:10 y <- 1:100 use_data(x, y) # For external use use_data(x, y, internal = TRUE) # For internal use } # } if (FALSE) { # \\dontrun{ use_data_raw(\"daisy\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_data_table.html","id":null,"dir":"Reference","previous_headings":"","what":"Prepare for importing data.table — use_data_table","title":"Prepare for importing data.table — use_data_table","text":"use_data_table() imports data.table() function data.table package, well several important symbols: :=, .SD, ., .N, ., .GRP, .NGRP, .EACHI. minimal setup can learn much \"Importing data.table\" vignette: https://rdatatable.gitlab.io/data.table/articles/datatable-importing.html. addition importing functions, use_data_table() also blocks usage data.table Depends field DESCRIPTION file; data.table used imported suggested package . See discussion.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_data_table.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Prepare for importing data.table — use_data_table","text":"","code":"use_data_table()"},{"path":"https://usethis.r-lib.org/dev/reference/use_description.html","id":null,"dir":"Reference","previous_headings":"","what":"Create or modify a DESCRIPTION file — use_description","title":"Create or modify a DESCRIPTION file — use_description","text":"use_description() creates DESCRIPTION file. Although mostly associated R packages, DESCRIPTION file can also used declare dependencies non-package project. Within project, devtools::install_deps() can used install required packages. Note , default, use_decription() checks CRAN-compliant package name. can turn check_name = FALSE. usethis consults following sources, order, set DESCRIPTION fields: fields argument create_package() use_description() getOption(\"usethis.description\") Defaults built usethis fields discovered via options usethis package can viewed use_description_defaults(). create lot packages, consider storing personalized defaults named list option named \"usethis.description\". example code include .Rprofile, can opened via edit_r_profile(): Prior usethis v2.0.0, getOption(\"devtools.desc\") consulted backwards compatibility, now \"usethis.description\" option supported.","code":"options( usethis.description = list( \"Authors@R\" = utils::person( \"Jane\", \"Doe\", email = \"jane@example.com\", role = c(\"aut\", \"cre\"), comment = c(ORCID = \"YOUR-ORCID-ID\") ), Language = \"es\", License = \"MIT + file LICENSE\" ) )"},{"path":"https://usethis.r-lib.org/dev/reference/use_description.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create or modify a DESCRIPTION file — use_description","text":"","code":"use_description(fields = list(), check_name = TRUE, roxygen = TRUE) use_description_defaults(package = NULL, roxygen = TRUE, fields = list())"},{"path":"https://usethis.r-lib.org/dev/reference/use_description.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create or modify a DESCRIPTION file — use_description","text":"fields named list fields add DESCRIPTION, potentially overriding default values. Default values taken \"usethis.description\" option usethis package (order), can viewed use_description_defaults(). check_name Whether check name valid CRAN throw error . roxygen TRUE, sets RoxygenNote current roxygen2 version package Package name","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_description.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create or modify a DESCRIPTION file — use_description","text":"","code":"if (FALSE) { # \\dontrun{ use_description() use_description(fields = list(Language = \"es\")) use_description_defaults() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_directory.html","id":null,"dir":"Reference","previous_headings":"","what":"Use a directory — use_directory","title":"Use a directory — use_directory","text":"use_directory() creates directory (already exist) project's top-level directory. function powers many use_ functions use_data() use_vignette().","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_directory.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use a directory — use_directory","text":"","code":"use_directory(path, ignore = FALSE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_directory.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use a directory — use_directory","text":"path Path directory create, relative project. ignore newly created file added .Rbuildignore?","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_directory.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Use a directory — use_directory","text":"","code":"if (FALSE) { # \\dontrun{ use_directory(\"inst\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_git.html","id":null,"dir":"Reference","previous_headings":"","what":"Initialise a git repository — use_git","title":"Initialise a git repository — use_git","text":"use_git() initialises Git repository adds important files .gitignore. user consents, also makes initial commit.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Initialise a git repository — use_git","text":"","code":"use_git(message = \"Initial commit\")"},{"path":"https://usethis.r-lib.org/dev/reference/use_git.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Initialise a git repository — use_git","text":"message Message use first commit.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_git.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Initialise a git repository — use_git","text":"","code":"if (FALSE) { # \\dontrun{ use_git() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_git_config.html","id":null,"dir":"Reference","previous_headings":"","what":"Configure Git — use_git_config","title":"Configure Git — use_git_config","text":"Sets Git options, either user project (\"global\" \"local\", Git terminology). Wraps gert::git_config_set() gert::git_config_global_set(). inspect Git config, see gert::git_config().","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git_config.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Configure Git — use_git_config","text":"","code":"use_git_config(scope = c(\"user\", \"project\"), ...)"},{"path":"https://usethis.r-lib.org/dev/reference/use_git_config.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Configure Git — use_git_config","text":"scope Edit globally current user, locally current project ... Name-value pairs, processed .","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git_config.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Configure Git — use_git_config","text":"Invisibly, previous values modified components, named list.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_git_config.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Configure Git — use_git_config","text":"","code":"if (FALSE) { # \\dontrun{ # set the user's global user.name and user.email use_git_config(user.name = \"Jane\", user.email = \"jane@example.org\") # set the user.name and user.email locally, i.e. for current repo/project use_git_config( scope = \"project\", user.name = \"Jane\", user.email = \"jane@example.org\" ) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_git_hook.html","id":null,"dir":"Reference","previous_headings":"","what":"Add a git hook — use_git_hook","title":"Add a git hook — use_git_hook","text":"Sets git hook using specified script. Creates hook directory needed, sets correct permissions hook.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git_hook.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add a git hook — use_git_hook","text":"","code":"use_git_hook(hook, script)"},{"path":"https://usethis.r-lib.org/dev/reference/use_git_hook.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add a git hook — use_git_hook","text":"hook Hook name. One \"pre-commit\", \"prepare-commit-msg\", \"commit-msg\", \"post-commit\", \"applypatch-msg\", \"pre-applypatch\", \"post-applypatch\", \"pre-rebase\", \"post-rewrite\", \"post-checkout\", \"post-merge\", \"pre-push\", \"pre-auto-gc\". script Text script run","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_git_ignore.html","id":null,"dir":"Reference","previous_headings":"","what":"Tell Git to ignore files — use_git_ignore","title":"Tell Git to ignore files — use_git_ignore","text":"Tell Git ignore files","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git_ignore.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tell Git to ignore files — use_git_ignore","text":"","code":"use_git_ignore(ignores, directory = \".\")"},{"path":"https://usethis.r-lib.org/dev/reference/use_git_ignore.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Tell Git to ignore files — use_git_ignore","text":"ignores Character vector ignores, specified file globs. directory Directory relative active project set ignores","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_git_remote.html","id":null,"dir":"Reference","previous_headings":"","what":"Configure and report Git remotes — use_git_remote","title":"Configure and report Git remotes — use_git_remote","text":"Two helpers available: use_git_remote() sets remote associated name url. git_remotes() reports configured remotes, similar git remote -v.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git_remote.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Configure and report Git remotes — use_git_remote","text":"","code":"use_git_remote(name = \"origin\", url, overwrite = FALSE) git_remotes()"},{"path":"https://usethis.r-lib.org/dev/reference/use_git_remote.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Configure and report Git remotes — use_git_remote","text":"name string giving short name remote. url string giving url remote. overwrite Logical. Controls whether existing remote can modified.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git_remote.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Configure and report Git remotes — use_git_remote","text":"Named list Git remotes.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_git_remote.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Configure and report Git remotes — use_git_remote","text":"","code":"if (FALSE) { # \\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) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_github.html","id":null,"dir":"Reference","previous_headings":"","what":"Connect a local repo with GitHub — use_github","title":"Connect a local repo with GitHub — use_github","text":"use_github() takes local project : Checks initial state good go: Project already Git repo Current branch default branch, e.g. main master uncommitted changes pre-existing origin remote Creates associated repo GitHub Adds GitHub repo local repo origin remote Makes initial push GitHub Calls use_github_links(), project R package Configures origin/DEFAULT upstream branch local DEFAULT branch, e.g. main master See authentication setup necessary work.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Connect a local repo with GitHub — use_github","text":"","code":"use_github( organisation = NULL, private = FALSE, visibility = c(\"public\", \"private\", \"internal\"), protocol = git_protocol(), host = NULL )"},{"path":"https://usethis.r-lib.org/dev/reference/use_github.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Connect a local repo with GitHub — use_github","text":"organisation supplied, repo created organisation, instead login associated GitHub token discovered host. user's role token's scopes must permission create repositories organisation. private TRUE, creates private repository. visibility relevant organisation-owned repos associated certain GitHub Enterprise products. special \"internal\" visibility grants read permission organisation members, .e. intermediate \"private\" \"public\", within GHE. specified, visibility takes precedence private = TRUE/FALSE. protocol One \"https\" \"ssh\" host GitHub host target, passed .api_url argument gh::gh(). unspecified, gh defaults \"https://api.github.com\", although gh's default can customised setting GITHUB_API_URL environment variable. hypothetical GitHub Enterprise instance, either \"https://github.acme.com/api/v3\" \"https://github.acme.com\" acceptable.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github.html","id":"git-github-authentication","dir":"Reference","previous_headings":"","what":"Git/GitHub Authentication","title":"Connect a local repo with GitHub — use_github","text":"Many usethis functions, including documented , potentially interact GitHub two different ways: Via GitHub REST API. Examples: create repo, fork, pull request. conventional Git remote. Examples: clone, fetch, push. Therefore two types auth can happen credentials must discoverable. credentials mean? GitHub personal access token (PAT) must discoverable gh package, used GitHub operations via REST API. See gh_token_help() getting configuring PAT. use HTTPS protocol Git remotes, PAT also used Git operations, git push. Usethis uses gert package , PAT must discoverable gert. Generally gert gh discover use PAT. ability \"kill two birds one stone\" HTTPS + PAT recommended auth strategy new Git GitHub PRs. use SSH remotes, SSH keys must also discoverable, addition PAT. public key must added GitHub account. Git/GitHub credential management covered dedicated article: Managing Git(Hub) Credentials","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Connect a local repo with GitHub — use_github","text":"","code":"if (FALSE) { # \\dontrun{ pkgpath <- file.path(tempdir(), \"testpkg\") create_package(pkgpath) ## now, working inside \"testpkg\", initialize git repository use_git() ## create github repository and configure as git remote use_github() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_action.html","id":null,"dir":"Reference","previous_headings":"","what":"Set up a GitHub Actions workflow — use_github_action","title":"Set up a GitHub Actions workflow — use_github_action","text":"Sets continuous integration (CI) R package developed GitHub using GitHub Actions. CI can used trigger various operations push pull request, e.g. running R CMD check building deploying pkgdown site.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_action.html","id":"workflows","dir":"Reference","previous_headings":"","what":"Workflows","title":"Set up a GitHub Actions workflow — use_github_action","text":"four particularly important workflows used many packages: check-standard: Run R CMD check using R-latest Linux, Mac, Windows, using R-devel R-oldrel Linux. good baseline plan submitting package CRAN. test-coverage: Compute test coverage report https://.codecov.io calling covr::codecov(). pkgdown: Automatically build publish pkgdown website. recommend instead calling use_pkgdown_github_pages() performs important set . pr-commands: Enables use two R-specific commands pull request issue comments: /document run roxygen2::roxygenise() /style run styler::style_pkg(). update PR changes done. call use_github_action() without arguments, prompted pick one . Otherwise can see complete list possibilities provided r-lib https://github.com/r-lib/actions/tree/v2/examples, can supply url use workflow.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_action.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Set up a GitHub Actions workflow — use_github_action","text":"","code":"use_github_action( name = NULL, ref = NULL, url = NULL, save_as = NULL, readme = NULL, ignore = TRUE, open = FALSE, badge = NULL )"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_action.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Set up a GitHub Actions workflow — use_github_action","text":"name use_github_action(): Name one example workflow https://github.com/r-lib/actions/tree/v2/examples (without extension), e.g. \"pkgdown\", \"check-standard.yaml\". name starts check-, save_as default R-CMD-check.yaml badge default TRUE. ref Desired Git reference, usually name tag (\"v2\") branch (\"main\"). possibilities include commit SHA (\"d1c516d\") \"HEAD\" (meaning \"tip remote's default branch\"). specified, defaults latest published release r-lib/actions (https://github.com/r-lib/actions/releases). url full URL .yaml file GitHub. See details use_github_file(). save_as Name local workflow file. Defaults name fs::path_file(url) use_github_action(). specify part path; parent directory always .github/workflows, within active project. readme full URL README file provides details workflow. Ignored url NULL. ignore newly created file added .Rbuildignore? open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise. badge add badge README?","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_action.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Set up a GitHub Actions workflow — use_github_action","text":"","code":"if (FALSE) { # \\dontrun{ use_github_action() use_github_action_check_standard() use_github_action(\"pkgdown\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_actions.html","id":null,"dir":"Reference","previous_headings":"","what":"Deprecated GitHub Actions functions — use_github_actions","title":"Deprecated GitHub Actions functions — use_github_actions","text":"use_github_actions() deprecated just alias use_github_action_check_release(). use_github_action_check_full() overkill packages recommended. use_github_action_check_release(), use_github_action_check_standard(), use_github_action_pr_commands() deprecated favor use_github_action(), can now suggest specific workflows use.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_actions.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Deprecated GitHub Actions functions — use_github_actions","text":"","code":"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 )"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_actions_badge.html","id":null,"dir":"Reference","previous_headings":"","what":"Generates a GitHub Actions badge — use_github_actions_badge","title":"Generates a GitHub Actions badge — use_github_actions_badge","text":"Generates GitHub Actions badge . exists primarily internal use.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_actions_badge.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generates a GitHub Actions badge — use_github_actions_badge","text":"","code":"use_github_actions_badge(name = \"R-CMD-check.yaml\", repo_spec = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_actions_badge.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generates a GitHub Actions badge — use_github_actions_badge","text":"name Name workflow's YAML configuration file (without extension), e.g. \"R-CMD-check\", \"R-CMD-check.yaml\".","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_file.html","id":null,"dir":"Reference","previous_headings":"","what":"Copy a file from any GitHub repo into the current project — use_github_file","title":"Copy a file from any GitHub repo into the current project — use_github_file","text":"Gets content file GitHub, repo user can read, writes active project. function wraps endpoint GitHub API supports specifying target reference (.e. branch, tag, commit) follows symlinks.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_file.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Copy a file from any GitHub repo into the current project — use_github_file","text":"","code":"use_github_file( repo_spec, path = NULL, save_as = NULL, ref = NULL, ignore = FALSE, open = FALSE, overwrite = FALSE, host = NULL )"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_file.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Copy a file from any GitHub repo into the current project — use_github_file","text":"repo_spec string identifying GitHub repo , alternatively, GitHub file URL. Acceptable forms: Plain OWNER/REPO spec blob URL, \"https://github.com/OWNER/REPO/blob/REF/path///file\" raw URL, \"https://raw.githubusercontent.com/OWNER/REPO/REF/path///file\" case URL, path, ref, host extracted , addition repo_spec. path Path file copy, relative GitHub repo lives . extracted repo_spec user provides URL. save_as Path file create, relative root active project. Defaults last part path, sense basename(path) fs::path_file(path). ref name branch, tag, commit. default, file path copied current state repo's default branch. extracted repo_spec user provides URL. ignore newly created file added .Rbuildignore? open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise. overwrite Force overwrite existing file? host GitHub host target, passed .api_url argument gh::gh(). unspecified, gh defaults \"https://api.github.com\", although gh's default can customised setting GITHUB_API_URL environment variable. hypothetical GitHub Enterprise instance, either \"https://github.acme.com/api/v3\" \"https://github.acme.com\" acceptable.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_file.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Copy a file from any GitHub repo into the current project — use_github_file","text":"logical indicator whether file written, invisibly.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_file.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Copy a file from any GitHub repo into the current project — use_github_file","text":"","code":"if (FALSE) { # \\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\" ) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Manage GitHub issue labels — use_github_labels","title":"Manage GitHub issue labels — use_github_labels","text":"use_github_labels() can create new labels, update colours descriptions, optionally delete GitHub's default labels (delete_default = TRUE). never delete labels associated issues. use_tidy_github_labels() calls use_github_labels() tidyverse conventions powered tidy_labels(), tidy_labels_rename(), tidy_label_colours() tidy_label_descriptions().","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_labels.html","id":"tidyverse-label-usage","dir":"Reference","previous_headings":"","what":"tidyverse label usage","title":"Manage GitHub issue labels — use_github_labels","text":"Labels used part issue-triage process, designed minimise time spent re-reading issues. absence label indicates issue new, yet triaged. four mutually exclusive labels indicate overall \"type\" issue: bug: unexpected problem unintended behavior. documentation: requires changes docs. feature: feature requests enhancement. upkeep: general package maintenance work makes future development easier. five labels needed repositories: breaking change: issue/PR requires breaking change included patch releases. reprex indicates issue minimal reproducible example, reply sent requesting one user. good first issue indicates good issue first-time contributors. help wanted indicates maintainer wants help issue. wip indicates someone working promised . Finally larger repos accumulate labels specific areas functionality. example, usethis labels like \"description\", \"paths\", \"readme\", time shown common sources problems. labels helpful grouping issues can tackle related problems time. Repo-specific issues grey background (#eeeeee) emoji. keeps issue page visually harmonious still giving enough variation easily distinguish different types label.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Manage GitHub issue labels — use_github_labels","text":"","code":"use_github_labels( labels = character(), rename = character(), colours = character(), descriptions = character(), delete_default = FALSE ) use_tidy_github_labels() tidy_labels() tidy_labels_rename() tidy_label_colours() tidy_label_descriptions()"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Manage GitHub issue labels — use_github_labels","text":"labels character vector giving labels add. rename named vector names giving old names values giving new names. colours, descriptions Named character vectors giving hexadecimal colours (like e02a2a) longer descriptions. names match label names, anything unmatched left unchanged. create new label, supply colours, given random colour. delete_default TRUE, removes GitHub default labels appear labels vector associated issues.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_labels.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Manage GitHub issue labels — use_github_labels","text":"","code":"if (FALSE) { # \\dontrun{ # typical use in, e.g., a new tidyverse project use_github_labels(delete_default = TRUE) # create labels without changing colours/descriptions use_github_labels( labels = c(\"foofy\", \"foofier\", \"foofiest\"), colours = NULL, descriptions = NULL ) # change descriptions without changing names/colours use_github_labels( labels = NULL, colours = NULL, descriptions = c(\"foofiest\" = \"the foofiest issue you ever saw\") ) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_links.html","id":null,"dir":"Reference","previous_headings":"","what":"Use GitHub links in URL and BugReports — use_github_links","title":"Use GitHub links in URL and BugReports — use_github_links","text":"Populates URL BugReports fields GitHub-using R package appropriate links. GitHub repo link determined current project's GitHub remotes: working fork, function expects origin GitHub remote links target repo. working fork, function expects find two GitHub remotes: origin (fork) upstream (fork's parent) remote. interactive session, user can confirm repo use links. noninteractive session, links formed using upstream.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_links.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use GitHub links in URL and BugReports — use_github_links","text":"","code":"use_github_links(overwrite = FALSE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_links.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use GitHub links in URL and BugReports — use_github_links","text":"overwrite default, use_github_links() overwrite existing fields. Set TRUE overwrite existing links.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_links.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Use GitHub links in URL and BugReports — use_github_links","text":"","code":"if (FALSE) { # \\dontrun{ use_github_links() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_pages.html","id":null,"dir":"Reference","previous_headings":"","what":"Configure a GitHub Pages site — use_github_pages","title":"Configure a GitHub Pages site — use_github_pages","text":"Activates reconfigures GitHub Pages site project hosted GitHub. function anticipates two specific usage modes: Publish root directory gh-pages branch, assumed (least primarily) remote branch. Typically gh-pages branch managed automatic \"build deploy\" job, one configured use_github_action(\"pkgdown\"). Publish \"/docs\" directory \"regular\" branch, probably repo's default branch. user assumed plan manage content \"/docs\".","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_pages.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Configure a GitHub Pages site — use_github_pages","text":"","code":"use_github_pages(branch = \"gh-pages\", path = \"/\", cname = NA)"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_pages.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Configure a GitHub Pages site — use_github_pages","text":"branch, path Branch path site source. default branch = \"gh-pages\" path = \"/\" reflects strong GitHub support configuration: gh-pages branch first created, automatically published Pages, using source found \"/\". gh-pages branch yet exist host, use_github_pages() creates empty, orphan remote branch. common alternative use repo's default branch, coupled path = \"/docs\". user's responsibility ensure branch pre-exists host. Note GitHub support arbitrary path , time writing, \"/\" \"/docs\" accepted. cname Optional, custom domain name. NA default means \"set change \", whereas value NULL removes previously configured custom domain. Note can add modify CNAME file repository. using Pages host pkgdown site, better specify URL pkgdown config file let pkgdown manage CNAME.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_pages.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Configure a GitHub Pages site — use_github_pages","text":"Site metadata returned GitHub API, invisibly","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_github_pages.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Configure a GitHub Pages site — use_github_pages","text":"","code":"if (FALSE) { # \\dontrun{ use_github_pages() use_github_pages(branch = git_default_branch(), path = \"/docs\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_release.html","id":null,"dir":"Reference","previous_headings":"","what":"Publish a GitHub release — use_github_release","title":"Publish a GitHub release — use_github_release","text":"Pushes current branch (safe) publishes GitHub release latest CRAN submission. use devtools::submit_cran() submit CRAN, information submitted state captured CRAN-SUBMISSION file. use_github_release() uses info populate GitHub release notes , success, deletes file. absence file, assume current state (SHA HEAD, package version, NEWS) submitted state.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_github_release.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Publish a GitHub release — use_github_release","text":"","code":"use_github_release(publish = TRUE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_github_release.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Publish a GitHub release — use_github_release","text":"publish TRUE, publishes release. FALSE, creates draft release.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_gitlab_ci.html","id":null,"dir":"Reference","previous_headings":"","what":"Continuous integration setup and badges — use_gitlab_ci","title":"Continuous integration setup and badges — use_gitlab_ci","text":"functions actively used tidyverse team, may currently work. Use risk. Sets third-party continuous integration (CI) services R package GitLab CircleCI. functions: Add service-specific configuration files add .Rbuildignore. Activate service give user detailed prompt. Provide markdown insert badge README.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_gitlab_ci.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Continuous integration setup and badges — use_gitlab_ci","text":"","code":"use_gitlab_ci() use_circleci(browse = rlang::is_interactive(), image = \"rocker/verse:latest\") use_circleci_badge(repo_spec = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_gitlab_ci.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Continuous integration setup and badges — use_gitlab_ci","text":"browse Open browser window enable automatic builds package. image Docker image use build. Must available DockerHub. rocker/verse image includes TeXLive, pandoc, tidyverse packages. minimal image, try rocker/r-ver. specify version R, change tag latest version want, e.g. rocker/r-ver:3.5.3. repo_spec Optional GitHub repo specification form: owner/repo. can usually inferred GitHub remotes active project.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_gitlab_ci.html","id":"use-gitlab-ci-","dir":"Reference","previous_headings":"","what":"use_gitlab_ci()","title":"Continuous integration setup and badges — use_gitlab_ci","text":"Adds basic .gitlab-ci.yml top-level directory package. configuration file GitLab CI/CD continuous integration service.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_gitlab_ci.html","id":"use-circleci-","dir":"Reference","previous_headings":"","what":"use_circleci()","title":"Continuous integration setup and badges — use_gitlab_ci","text":"Adds basic .circleci/config.yml top-level directory package. configuration file CircleCI continuous integration service.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_gitlab_ci.html","id":"use-circleci-badge-","dir":"Reference","previous_headings":"","what":"use_circleci_badge()","title":"Continuous integration setup and badges — use_gitlab_ci","text":"adds Circle CI badge. Use project Circle CI already configured.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_import_from.html","id":null,"dir":"Reference","previous_headings":"","what":"Import a function from another package — use_import_from","title":"Import a function from another package — use_import_from","text":"use_import_from() imports function another package adding roxygen2 @importFrom tag package-level documentation (can created use_package_doc()). Importing function another package allows refer without namespace (e.g., fun() instead package::fun()). use_import_from() also re-documents NAMESPACE, re-load current package. ensures fun immediately available development session.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_import_from.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Import a function from another package — use_import_from","text":"","code":"use_import_from(package, fun, load = is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_import_from.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Import a function from another package — use_import_from","text":"package Package name fun vector function names load Logical. Re-load pkgload::load_all()?","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_import_from.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Import a function from another package — use_import_from","text":"Invisibly, TRUE package document changed, FALSE .","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_import_from.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Import a function from another package — use_import_from","text":"","code":"if (FALSE) { # \\dontrun{ use_import_from(\"glue\", \"glue\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_jenkins.html","id":null,"dir":"Reference","previous_headings":"","what":"Create Jenkinsfile for Jenkins CI Pipelines — use_jenkins","title":"Create Jenkinsfile for Jenkins CI Pipelines — use_jenkins","text":"use_jenkins() adds basic Jenkinsfile R packages project root directory. Jenkinsfile stages take advantage calls make, calling function also run use_make() Makefile already exist project root.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_jenkins.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create Jenkinsfile for Jenkins CI Pipelines — use_jenkins","text":"","code":"use_jenkins()"},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_latest_dependencies.html","id":null,"dir":"Reference","previous_headings":"","what":"Use ","title":"Use ","text":"Pins minimum versions Imports Depends dependencies latest ones (determined source). Useful tidyverse package, otherwise used extreme care.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_latest_dependencies.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use ","text":"","code":"use_latest_dependencies(overwrite = TRUE, source = c(\"CRAN\", \"local\"))"},{"path":"https://usethis.r-lib.org/dev/reference/use_latest_dependencies.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use ","text":"overwrite default (TRUE), dependencies modified. Set FALSE modify dependencies without version specifications. source Use \"CRAN\" \"local\" package versions.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_lifecycle.html","id":null,"dir":"Reference","previous_headings":"","what":"Use lifecycle badges — use_lifecycle","title":"Use lifecycle badges — use_lifecycle","text":"helper: Adds lifecycle dependency. Imports lifecycle::deprecated() use function arguments. Copies lifecycle badges man/figures. Reminds use badge syntax. Learn https://lifecycle.r-lib.org/articles/communicate.html","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_lifecycle.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use lifecycle badges — use_lifecycle","text":"","code":"use_lifecycle()"},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_logo.html","id":null,"dir":"Reference","previous_headings":"","what":"Use a package logo — use_logo","title":"Use a package logo — use_logo","text":"function helps use logo package: Enforces specific size Stores logo image file man/figures/logo.png Produces markdown text need README include logo","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_logo.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use a package logo — use_logo","text":"","code":"use_logo(img, geometry = \"240x278\", retina = TRUE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_logo.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use a package logo — use_logo","text":"img path existing image file geometry magick::geometry string specifying size. default assumes hex logo using spec http://hexb./sticker.html. retina TRUE, default, scales image README, assuming geometry double desired size.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_logo.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Use a package logo — use_logo","text":"","code":"if (FALSE) { # \\dontrun{ use_logo(\"usethis.png\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_make.html","id":null,"dir":"Reference","previous_headings":"","what":"Create Makefile — use_make","title":"Create Makefile — use_make","text":"use_make() adds basic Makefile project root directory.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_make.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create Makefile — use_make","text":"","code":"use_make()"},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_namespace.html","id":null,"dir":"Reference","previous_headings":"","what":"Use a basic NAMESPACE — use_namespace","title":"Use a basic NAMESPACE — use_namespace","text":"roxygen TRUE generates empty NAMESPACE exports nothing; need explicitly export functions @export. roxygen FALSE, generates default NAMESPACE exports functions except start ..","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_namespace.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use a basic NAMESPACE — use_namespace","text":"","code":"use_namespace(roxygen = TRUE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_namespace.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use a basic NAMESPACE — use_namespace","text":"roxygen plan manage NAMESPACE roxygen2?","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_news_md.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a simple NEWS.md — use_news_md","title":"Create a simple NEWS.md — use_news_md","text":"creates basic NEWS.md root directory.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_news_md.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a simple NEWS.md — use_news_md","text":"","code":"use_news_md(open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_news_md.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a simple NEWS.md — use_news_md","text":"open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_package.html","id":null,"dir":"Reference","previous_headings":"","what":"Depend on another package — use_package","title":"Depend on another package — use_package","text":"use_package() adds CRAN package dependency DESCRIPTION offers little advice best use . use_dev_package() adds dependency -development package, adding dev repo Remotes automatically installed correct location. helper remove dependency: , simply remove package DESCRIPTION file. use_package() exists support couple common maneuvers: Add dependency Imports Suggests LinkingTo. Add minimum version dependency. Specify minimum supported version R. use_package() probably works slightly exotic modifications, point, edit DESCRIPTION hand. intention account possible edge cases.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_package.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Depend on another package — use_package","text":"","code":"use_package(package, type = \"Imports\", min_version = NULL) use_dev_package(package, type = \"Imports\", remote = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_package.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Depend on another package — use_package","text":"package Name package depend . type Type dependency: must one \"Imports\", \"Depends\", \"Suggests\", \"Enhances\", \"LinkingTo\" (unique abbreviation). Matching case insensitive. min_version Optionally, supply minimum version package. Set TRUE use currently installed version use version string suitable numeric_version(), \"2.5.0\". remote default, OWNER/REPO GitHub remote inserted. Optionally, can supply character string specify remote, e.g. \"gitlab::jimhester/covr\", using syntax supported remotes package.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_package.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Depend on another package — use_package","text":"","code":"if (FALSE) { # \\dontrun{ use_package(\"ggplot2\") use_package(\"dplyr\", \"suggests\") use_dev_package(\"glue\") # Depend on R version 4.1 use_package(\"R\", type = \"Depends\", min_version = \"4.1\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_package_doc.html","id":null,"dir":"Reference","previous_headings":"","what":"Package-level documentation — use_package_doc","title":"Package-level documentation — use_package_doc","text":"Adds dummy .R file cause roxygen2 generate basic package-level documentation. package named \"foo\", make help available user via ?foo package?foo. call devtools::document(), roxygen2 flesh .Rd file using data DESCRIPTION. ensures need repeat (remember update!) information multiple places. .R file also good place roxygen directives apply whole package (vs. specific function), global namespace tags like @importFrom.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_package_doc.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Package-level documentation — use_package_doc","text":"","code":"use_package_doc(open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_package_doc.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Package-level documentation — use_package_doc","text":"open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_pipe.html","id":null,"dir":"Reference","previous_headings":"","what":"Use magrittr's pipe in your package — use_pipe","title":"Use magrittr's pipe in your package — use_pipe","text":"setup necessary use magrittr's pipe operator, %>% package. function requires use roxygen2. Adds magrittr \"Imports\" DESCRIPTION. Imports pipe operator specifically, necessary internal use. Exports pipe operator, export = TRUE, necessary make %>% available users package.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_pipe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use magrittr's pipe in your package — use_pipe","text":"","code":"use_pipe(export = TRUE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_pipe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use magrittr's pipe in your package — use_pipe","text":"export TRUE, file R/utils-pipe.R added, provides roxygen template import re-export %>%. FALSE, necessary roxygen directive added, possible, otherwise instructions given.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_pipe.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Use magrittr's pipe in your package — use_pipe","text":"","code":"if (FALSE) { # \\dontrun{ use_pipe() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_pkgdown.html","id":null,"dir":"Reference","previous_headings":"","what":"Use pkgdown — use_pkgdown","title":"Use pkgdown — use_pkgdown","text":"pkgdown makes easy turn package beautiful website. usethis provides two functions help use pkgdown: use_pkgdown(): creates pkgdown config file adds relevant files directories .Rbuildignore .gitignore. use_pkgdown_github_pages(): implements GitHub setup needed automatically publish pkgdown site GitHub pages: (first, calls use_pkgdown()) use_github_pages() prepares publish pkgdown site gh-pages branch use_github_action(\"pkgdown\") configures GitHub Action automatically build pkgdown site deploy via GitHub Pages pkgdown site's URL added pkgdown configuration file, URL field DESCRIPTION, GitHub repo. Packages owned certain GitHub organizations (tidyverse, r-lib, tidymodels) get special treatment, terms anticipating (eventual) site URL use pkgdown template.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_pkgdown.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use pkgdown — use_pkgdown","text":"","code":"use_pkgdown(config_file = \"_pkgdown.yml\", destdir = \"docs\") use_pkgdown_github_pages()"},{"path":"https://usethis.r-lib.org/dev/reference/use_pkgdown.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use pkgdown — use_pkgdown","text":"config_file Path pkgdown yaml config file, relative project. destdir Target directory pkgdown docs.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_r.html","id":null,"dir":"Reference","previous_headings":"","what":"Create or edit R or test files — use_r","title":"Create or edit R or test files — use_r","text":"pair functions makes easy create paired R test files, using convention tests R/foofy.R live tests/testthat/test-foofy.R. can use create new files scratch supplying name, use RStudio, can call create (navigate ) companion file based currently open file. also works test snapshot file active, .e. looking tests/testthat/_snaps/foofy.md, use_r() use_test() take R/foofy.R tests/testthat/test-foofy.R, respectively.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_r.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create or edit R or test files — use_r","text":"","code":"use_r(name = NULL, open = rlang::is_interactive()) use_test(name = NULL, open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_r.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create or edit R or test files — use_r","text":"name Either string giving file name (without directory) NULL take name currently open file RStudio. open Whether open file interactive editing.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_r.html","id":"renaming-files-in-an-existing-package","dir":"Reference","previous_headings":"","what":"Renaming files in an existing package","title":"Create or edit R or test files — use_r","text":"tips aligning file names across R/ tests/testthat/ existing package necessarily follow convention . script generates data frame R/ test files can help identify missed opportunities pairing: rename_files() function can also helpful.","code":"library(fs) library(tidyverse) bind_rows( tibble( type = \"R\", path = dir_ls(\"R/\", regexp = \"\\\\.[Rr]$\"), name = as.character(path_ext_remove(path_file(path))), ), tibble( type = \"test\", path = dir_ls(\"tests/testthat/\", regexp = \"/test[^/]+\\\\.[Rr]$\"), name = as.character(path_ext_remove(str_remove(path_file(path), \"^test[-_]\"))), ) ) %>% pivot_wider(names_from = type, values_from = path) %>% print(n = Inf)"},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_r.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create or edit R or test files — use_r","text":"","code":"if (FALSE) { # \\dontrun{ # create a new .R file below R/ use_r(\"coolstuff\") # if `R/coolstuff.R` is active in a supported IDE, you can now do: use_test() # if `tests/testthat/test-coolstuff.R` is active in a supported IDE, you can # return to `R/coolstuff.R` with: use_r() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_rcpp.html","id":null,"dir":"Reference","previous_headings":"","what":"Use C, C++, RcppArmadillo, or RcppEigen — use_rcpp","title":"Use C, C++, RcppArmadillo, or RcppEigen — use_rcpp","text":"Adds infrastructure commonly needed using compiled code: Creates src/ Adds required packages DESCRIPTION May create initial placeholder .c .cpp file Creates Makevars Makevars.win files (use_rcpp_armadillo() )","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rcpp.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use C, C++, RcppArmadillo, or RcppEigen — use_rcpp","text":"","code":"use_rcpp(name = NULL) use_rcpp_armadillo(name = NULL) use_rcpp_eigen(name = NULL) use_c(name = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_rcpp.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use C, C++, RcppArmadillo, or RcppEigen — use_rcpp","text":"name Either string giving file name (without directory) NULL take name currently open file RStudio.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_readme_rmd.html","id":null,"dir":"Reference","previous_headings":"","what":"Create README files — use_readme_rmd","title":"Create README files — use_readme_rmd","text":"Creates skeleton README files possible stubs high-level description project/package goals R code install GitHub, GitHub usage detected basic example Use Rmd want rich intermingling code output. Use md basic README. README.Rmd automatically added .Rbuildignore. resulting README populated default YAML frontmatter R fenced code blocks (md) chunks (Rmd). use Rmd, still need render regularly, keep README.md --date. devtools::build_readme() handy . also use GitHub Actions re-render README.Rmd every time push. example workflow can found examples/ directory : https://github.com/r-lib/actions/. current project Git repo, use_readme_rmd() automatically configures pre-commit hook helps keep README.Rmd README.md, synchronized. hook creates friction try commit README.Rmd edited recently README.md. hook causes problems solves , implemented .git/hooks/pre-commit, can modify even delete.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_readme_rmd.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create README files — use_readme_rmd","text":"","code":"use_readme_rmd(open = rlang::is_interactive()) use_readme_md(open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_readme_rmd.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create README files — use_readme_rmd","text":"open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_readme_rmd.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create README files — use_readme_rmd","text":"","code":"if (FALSE) { # \\dontrun{ use_readme_rmd() use_readme_md() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_release_issue.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a release checklist in a GitHub issue — use_release_issue","title":"Create a release checklist in a GitHub issue — use_release_issue","text":"preparing release package CRAN quite steps need performed, steps can take multiple hours. function creates checklist GitHub issue : Help keep track process Feel sense satisfaction progress towards final submission Help watchers package stay informed. checklist contains generic set steps found helpful, based type release (\"patch\", \"minor\", \"major\"). encouraged edit issue customize list meet needs.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_release_issue.html","id":"customization","dir":"Reference","previous_headings":"","what":"Customization","title":"Create a release checklist in a GitHub issue — use_release_issue","text":"want consistently add extra bullets every release, can include custom bullets providing (unexported) release_bullets() function returns character vector. (historical reasons, release_questions() also supported). want check additional packages revdep check process, provide (unexported) release_extra_revdeps() function returns character vector. currently supported Posit internal check tooling.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_release_issue.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a release checklist in a GitHub issue — use_release_issue","text":"","code":"use_release_issue(version = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_release_issue.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a release checklist in a GitHub issue — use_release_issue","text":"version Optional version number release. unspecified, can make interactive choice.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_release_issue.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create a release checklist in a GitHub issue — use_release_issue","text":"","code":"if (FALSE) { # \\dontrun{ use_release_issue(\"2.0.0\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_revdep.html","id":null,"dir":"Reference","previous_headings":"","what":"Reverse dependency checks — use_revdep","title":"Reverse dependency checks — use_revdep","text":"Performs set checking reverse dependencies R package, implemented revdepcheck package: Creates revdep/ directory adds .Rbuildignore Populates revdep/.gitignore prevent tracking various revdep artefacts Prompts user run checks revdepcheck::revdep_check()","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_revdep.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Reverse dependency checks — use_revdep","text":"","code":"use_revdep()"},{"path":"https://usethis.r-lib.org/dev/reference/use_rmarkdown_template.html","id":null,"dir":"Reference","previous_headings":"","what":"Add an RMarkdown Template — use_rmarkdown_template","title":"Add an RMarkdown Template — use_rmarkdown_template","text":"Adds files directories necessary add custom rmarkdown template RStudio. creates: inst/rmarkdown/templates/{{template_dir}}. Main directory. skeleton/skeleton.Rmd. template Rmd file. template.yml basic information filled .","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rmarkdown_template.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add an RMarkdown Template — use_rmarkdown_template","text":"","code":"use_rmarkdown_template( template_name = \"Template Name\", template_dir = NULL, template_description = \"A description of the template\", template_create_dir = FALSE )"},{"path":"https://usethis.r-lib.org/dev/reference/use_rmarkdown_template.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add an RMarkdown Template — use_rmarkdown_template","text":"template_name name printed template menu. template_dir Name directory template live within inst/rmarkdown/templates. none provided user, created template_name. template_description Sets value description template.yml. template_create_dir Sets value create_dir template.yml.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rmarkdown_template.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add an RMarkdown Template — use_rmarkdown_template","text":"","code":"if (FALSE) { # \\dontrun{ use_rmarkdown_template() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_roxygen_md.html","id":null,"dir":"Reference","previous_headings":"","what":"Use roxygen2 with markdown — use_roxygen_md","title":"Use roxygen2 with markdown — use_roxygen_md","text":"already using roxygen2, markdown, need use roxygen2md convert existing Rd expressions markdown. conversion perfect, make sure check results.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_roxygen_md.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use roxygen2 with markdown — use_roxygen_md","text":"","code":"use_roxygen_md(overwrite = FALSE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_roxygen_md.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use roxygen2 with markdown — use_roxygen_md","text":"overwrite Whether overwrite existing Roxygen field DESCRIPTION \"list(markdown = TRUE)\".","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rscloud_badge.html","id":null,"dir":"Reference","previous_headings":"","what":"Deprecated badge function — use_rscloud_badge","title":"Deprecated badge function — use_rscloud_badge","text":"use_rscloud_badge() replaced use_posit_cloud_badge().","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rscloud_badge.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Deprecated badge function — use_rscloud_badge","text":"","code":"use_rscloud_badge(url)"},{"path":"https://usethis.r-lib.org/dev/reference/use_rstudio.html","id":null,"dir":"Reference","previous_headings":"","what":"Add RStudio Project infrastructure — use_rstudio","title":"Add RStudio Project infrastructure — use_rstudio","text":"likely want use create_project() create_package() instead use_rstudio()! create_*() functions can add RStudio Project infrastructure pre-existing project package. use_rstudio() mostly internal use creating usethis-like package organization. following current project, often executing proj_set(..., force = TRUE): Creates .Rproj file Adds RStudio files .gitignore Adds RStudio files .Rbuildignore, project package","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rstudio.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add RStudio Project infrastructure — use_rstudio","text":"","code":"use_rstudio(line_ending = c(\"posix\", \"windows\"), reformat = TRUE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_rstudio.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add RStudio Project infrastructure — use_rstudio","text":"line_ending Line ending reformat TRUE, .Rproj setup common options reformat files save: adding trailing newline, trimming trailing whitespace, setting line-ending. best practice new projects. FALSE, options left unset, appropriate contributing someone else's project .Rproj file.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rstudio_preferences.html","id":null,"dir":"Reference","previous_headings":"","what":"Set global RStudio preferences — use_rstudio_preferences","title":"Set global RStudio preferences — use_rstudio_preferences","text":"function allows set global RStudio preferences, achieving effect programmatically clicking buttons RStudio's Global Options. can find list configurable properties https://docs.posit.co/ide/server-pro/reference/session_user_settings.html.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rstudio_preferences.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Set global RStudio preferences — use_rstudio_preferences","text":"","code":"use_rstudio_preferences(...)"},{"path":"https://usethis.r-lib.org/dev/reference/use_rstudio_preferences.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Set global RStudio preferences — use_rstudio_preferences","text":"... Property-value pairs.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_rstudio_preferences.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Set global RStudio preferences — use_rstudio_preferences","text":"named list previous values, invisibly.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_spell_check.html","id":null,"dir":"Reference","previous_headings":"","what":"Use spell check — use_spell_check","title":"Use spell check — use_spell_check","text":"Adds unit test automatically run spell check documentation , optionally, vignettes R CMD check, using spelling package. Also adds WORDLIST file package, dictionary whitelisted words. See spelling::wordlist details.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_spell_check.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use spell check — use_spell_check","text":"","code":"use_spell_check(vignettes = TRUE, lang = \"en-US\", error = FALSE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_spell_check.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use spell check — use_spell_check","text":"vignettes Logical, TRUE spell check rmd rnw files vignettes/ folder. lang Preferred spelling language. Usually either \"en-US\" \"en-GB\". error Logical, indicating whether unit test fail spelling errors found. Defaults FALSE, error, prints potential spelling errors","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_standalone.html","id":null,"dir":"Reference","previous_headings":"","what":"Use a standalone file from another repo — use_standalone","title":"Use a standalone file from another repo — use_standalone","text":"\"standalone\" file implements minimum set functionality way can copied another package. use_standalone() makes easy get file repo. always overwrites existing standalone file name, making easy update previously imported code.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_standalone.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use a standalone file from another repo — use_standalone","text":"","code":"use_standalone(repo_spec, file = NULL, ref = NULL, host = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_standalone.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use a standalone file from another repo — use_standalone","text":"repo_spec string identifying GitHub repo one forms: Plain OWNER/REPO spec Browser URL, \"https://github.com/OWNER/REPO\" HTTPS Git URL, \"https://github.com/OWNER/REPO.git\" SSH Git URL, \"git@github.com:OWNER/REPO.git\" file Name standalone file. standalone- prefix file extension optional. omitted, allow choose standalone files offered repo. ref name branch, tag, commit. default, file path copied current state repo's default branch. extracted repo_spec user provides URL. host GitHub host target, passed .api_url argument gh::gh(). repo_spec URL, host extracted . unspecified, gh defaults \"https://api.github.com\", although gh's default can customised setting GITHUB_API_URL environment variable. hypothetical GitHub Enterprise instance, either \"https://github.acme.com/api/v3\" \"https://github.acme.com\" acceptable.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_standalone.html","id":"supported-fields","dir":"Reference","previous_headings":"","what":"Supported fields","title":"Use a standalone file from another repo — use_standalone","text":"standalone file YAML frontmatter provides additional information, file originates last updated. example: Two fields consulted use_standalone(): dependencies: file list files repo standalone file depends . files retrieved automatically use_standalone(). imports: package list packages standalone file depends . minimal version may specified parentheses, e.g. rlang (>= 1.0.0). dependencies passed use_package() ensure included Imports: field DESCRIPTION file. Note lists specified standard YAML syntax, using square brackets, example: imports: [rlang (>= 1.0.0), purrr].","code":"--- repo: r-lib/rlang file: standalone-types-check.R last-updated: 2023-03-07 license: https://unlicense.org dependencies: standalone-obj-type.R imports: rlang (>= 1.1.0) ---"},{"path":"https://usethis.r-lib.org/dev/reference/use_standalone.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Use a standalone file from another repo — use_standalone","text":"","code":"if (FALSE) { # \\dontrun{ use_standalone(\"r-lib/rlang\", file = \"types-check\") use_standalone(\"r-lib/rlang\", file = \"types-check\", ref = \"standalone-dep\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_template.html","id":null,"dir":"Reference","previous_headings":"","what":"Use a usethis-style template — use_template","title":"Use a usethis-style template — use_template","text":"Creates file data template found package. Provides control file name, addition .Rbuildignore, opening file inspection.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_template.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Use a usethis-style template — use_template","text":"","code":"use_template( template, save_as = template, data = list(), ignore = FALSE, open = FALSE, package = \"usethis\" )"},{"path":"https://usethis.r-lib.org/dev/reference/use_template.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Use a usethis-style template — use_template","text":"template Path template file relative templates/ directory within package; see details. save_as Path file create, relative root active project. Defaults template data list data passed template. ignore newly created file added .Rbuildignore? open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise. package Name package template found.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_template.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Use a usethis-style template — use_template","text":"logical vector indicating file modified.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_template.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Use a usethis-style template — use_template","text":"function can used engine templating function packages. template argument used along package argument derive path template file; expected fs::path_package(package = package, \"templates\", template). use fs::path_package() instead base::system.file() path construction works even development workflow, e.g., works devtools::load_all() pkgload::load_all(). Note describes behaviour fs::path_package() fs v1.2.7.9001 higher. interpolate data template, supply list using data argument. Internally, function uses whisker::whisker.render() combine template file data.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_template.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Use a usethis-style template — use_template","text":"","code":"if (FALSE) { # \\dontrun{ # Note: running this will write `NEWS.md` to your working directory use_template( template = \"NEWS.md\", data = list(Package = \"acme\", Version = \"1.2.3\"), package = \"usethis\" ) } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_test_helper.html","id":null,"dir":"Reference","previous_headings":"","what":"Create or edit a test helper file — use_test_helper","title":"Create or edit a test helper file — use_test_helper","text":"function creates (opens) test helper file, typically tests/testthat/helper.R. Test helper files executed beginning every automated test run also executed load_all(). helper file great place define test helper functions use throughout test suite, custom expectation.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_test_helper.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create or edit a test helper file — use_test_helper","text":"","code":"use_test_helper(name = NULL, open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_test_helper.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create or edit a test helper file — use_test_helper","text":"name Can used specify optional \"SLUG\" tests/testthat/helper-SLUG.R. open Whether open file interactive editing.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_test_helper.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create or edit a test helper file — use_test_helper","text":"","code":"if (FALSE) { # \\dontrun{ use_test_helper() use_test_helper(\"mocks\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_testthat.html","id":null,"dir":"Reference","previous_headings":"","what":"Sets up overall testing infrastructure — use_testthat","title":"Sets up overall testing infrastructure — use_testthat","text":"Creates tests/testthat/, tests/testthat.R, adds testthat package Suggests field. Learn https://r-pkgs.org/testing-basics.html","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_testthat.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Sets up overall testing infrastructure — use_testthat","text":"","code":"use_testthat(edition = NULL, parallel = FALSE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_testthat.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Sets up overall testing infrastructure — use_testthat","text":"edition testthat edition use. Defaults latest edition, .e. major version number currently installed testthat. parallel tests run parallel? feature appeared testthat 3.0.0; see https://testthat.r-lib.org/articles/parallel.html details caveats.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_testthat.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Sets up overall testing infrastructure — use_testthat","text":"","code":"if (FALSE) { # \\dontrun{ use_testthat() use_test() use_test(\"something-management\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_tibble.html","id":null,"dir":"Reference","previous_headings":"","what":"Prepare to return a tibble — use_tibble","title":"Prepare to return a tibble — use_tibble","text":"minimum setup tibble returned package handled using tibble method generics like print() [. Presumably care chosen store expose object class tbl_df. Specifically: Check active package uses roxygen2 Add tibble package \"Imports\" DESCRIPTION Prepare roxygen directive necessary import least one function tibble: possible, directive inserted existing package-level documentation, .e. roxygen snippet created use_package_doc() Otherwise, issue advice user add directive necessary package returns stored data object class tbl_df, package code make direct use functions tibble package. nothing, tibble namespace necessarily loaded tibble may therefore printed subsetted like base data.frame.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_tibble.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Prepare to return a tibble — use_tibble","text":"","code":"use_tibble()"},{"path":"https://usethis.r-lib.org/dev/reference/use_tibble.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Prepare to return a tibble — use_tibble","text":"","code":"if (FALSE) { # \\dontrun{ use_tibble() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_tidy_eval.html","id":null,"dir":"Reference","previous_headings":"","what":"Deprecated tidyverse functions — use_tidy_eval","title":"Deprecated tidyverse functions — use_tidy_eval","text":"use_tidy_eval() deprecated longer need systematically import re-export large number functions order use tidy evaluation. Instead, use use_import_from() tactically import functions need .","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_tidy_eval.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Deprecated tidyverse functions — use_tidy_eval","text":"","code":"use_tidy_eval()"},{"path":"https://usethis.r-lib.org/dev/reference/use_tidy_thanks.html","id":null,"dir":"Reference","previous_headings":"","what":"Identify contributors via GitHub activity — use_tidy_thanks","title":"Identify contributors via GitHub activity — use_tidy_thanks","text":"Derives list GitHub usernames, based opened issues pull requests. Used populate acknowledgment section package release blog posts https://www.tidyverse.org/blog/. arguments given, retrieve contributors active project since last (GitHub) release. Unexported helper functions, releases() ref_df() can useful interactively get quick look release tag names data frame refs (defaulting releases), respectively.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_tidy_thanks.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Identify contributors via GitHub activity — use_tidy_thanks","text":"","code":"use_tidy_thanks(repo_spec = NULL, from = NULL, to = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_tidy_thanks.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Identify contributors via GitHub activity — use_tidy_thanks","text":"repo_spec Optional GitHub repo specification form accepted repo_spec argument create_from_github() (plain spec browser Git URL). URL specification way target GitHub host \"github.com\", default. , GitHub ref (.e., SHA, tag, release) timestamp ISO 8601 format, specifying start end interval interest, sense [, ]. Examples: \"08a560d\", \"v1.3.0\", \"2018-02-24T00:13:45Z\", \"2018-05-01\". = NULL, = NULL, set timestamp recent (GitHub) release. Otherwise, NULL means \"bound\".","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_tidy_thanks.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Identify contributors via GitHub activity — use_tidy_thanks","text":"character vector GitHub usernames, invisibly.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_tidy_thanks.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Identify contributors via GitHub activity — use_tidy_thanks","text":"","code":"if (FALSE) { # \\dontrun{ # active project, interval = since the last release use_tidy_thanks() # active project, interval = since a specific datetime use_tidy_thanks(from = \"2020-07-24T00:13:45Z\") # r-lib/usethis, interval = since a certain date use_tidy_thanks(\"r-lib/usethis\", from = \"2020-08-01\") # r-lib/usethis, up to a specific release use_tidy_thanks(\"r-lib/usethis\", from = NULL, to = \"v1.1.0\") # r-lib/usethis, since a specific commit, up to a specific date use_tidy_thanks(\"r-lib/usethis\", from = \"08a560d\", to = \"2018-05-14\") # r-lib/usethis, but with copy/paste of a browser URL use_tidy_thanks(\"https://github.com/r-lib/usethis\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_tutorial.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a learnr tutorial — use_tutorial","title":"Create a learnr tutorial — use_tutorial","text":"Creates new tutorial inst/tutorials/. Tutorials interactive R Markdown documents built learnr package. use_tutorial() setup: Adds learnr Suggests DESCRIPTION. Gitignores inst/tutorials/*.html accidentally track rendered tutorials. Creates new .Rmd tutorial template , optionally, opens editing. Adds new .Rmd .Rbuildignore.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_tutorial.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a learnr tutorial — use_tutorial","text":"","code":"use_tutorial(name, title, open = rlang::is_interactive())"},{"path":"https://usethis.r-lib.org/dev/reference/use_tutorial.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a learnr tutorial — use_tutorial","text":"name Base file name use new .Rmd tutorial. consist numbers, letters, _ -. recommend using lower case. title human-facing title tutorial. open Open newly created file editing? Happens RStudio, applicable, via utils::file.edit() otherwise.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_tutorial.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create a learnr tutorial — use_tutorial","text":"","code":"if (FALSE) { # \\dontrun{ use_tutorial(\"learn-to-do-stuff\", \"Learn to do stuff\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_upkeep_issue.html","id":null,"dir":"Reference","previous_headings":"","what":"Create an upkeep checklist in a GitHub issue — use_upkeep_issue","title":"Create an upkeep checklist in a GitHub issue — use_upkeep_issue","text":"opens issue package repository checklist tasks regular maintenance package. fairly opinionated list tasks believe taking care generally make package better, easier maintain, enjoyable users. tasks meant performed (completed show subsequent lists), reviewed periodically. tidyverse team uses similar function use_tidy_upkeep_issue() annual package Spring Cleaning.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_upkeep_issue.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create an upkeep checklist in a GitHub issue — use_upkeep_issue","text":"","code":"use_upkeep_issue(year = NULL)"},{"path":"https://usethis.r-lib.org/dev/reference/use_upkeep_issue.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create an upkeep checklist in a GitHub issue — use_upkeep_issue","text":"year Year performing upkeep, used issue title. Defaults current year","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_upkeep_issue.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create an upkeep checklist in a GitHub issue — use_upkeep_issue","text":"","code":"if (FALSE) { # \\dontrun{ use_upkeep_issue() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_version.html","id":null,"dir":"Reference","previous_headings":"","what":"Increment package version — use_version","title":"Increment package version — use_version","text":"usethis supports semantic versioning, described detail version section R Packages. version number breaks like : use_version() increments \"Version\" field DESCRIPTION, adds new heading NEWS.md (exists), commits changes (package uses Git), optionally pushes (safe ). makes update line like PKG_version = \"x.y.z\"; src/version.c (exists). use_dev_version() increments development version, e.g. 1.0.0 1.0.0.9000. existing version already development version four components, nothing. Thin wrapper around use_version().","code":".. (released version) ... (dev version)"},{"path":"https://usethis.r-lib.org/dev/reference/use_version.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Increment package version — use_version","text":"","code":"use_version(which = NULL, push = FALSE) use_dev_version(push = FALSE)"},{"path":"https://usethis.r-lib.org/dev/reference/use_version.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Increment package version — use_version","text":"string specifying level increment, one : \"major\", \"minor\", \"patch\", \"dev\". NULL, user can choose interactively. push TRUE, also attempts push commits remote branch.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_version.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Increment package version — use_version","text":"","code":"if (FALSE) { # \\dontrun{ ## for interactive selection, do this: use_version() ## request a specific type of increment use_version(\"minor\") use_dev_version() } # }"},{"path":"https://usethis.r-lib.org/dev/reference/use_vignette.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a vignette or article — use_vignette","title":"Create a vignette or article — use_vignette","text":"Creates new vignette article vignettes/. Articles special type vignette appear pkgdown websites, included package (added .Rbuildignore automatically).","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_vignette.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a vignette or article — use_vignette","text":"","code":"use_vignette(name, title = name) use_article(name, title = name)"},{"path":"https://usethis.r-lib.org/dev/reference/use_vignette.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a vignette or article — use_vignette","text":"name Base file name use new vignette. consist numbers, letters, _ -. Lower case recommended. title title vignette.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/use_vignette.html","id":"general-setup","dir":"Reference","previous_headings":"","what":"General setup","title":"Create a vignette or article — use_vignette","text":"Adds needed packages DESCRIPTION. Adds inst/doc .gitignore built vignettes tracked. Adds vignettes/*.html vignettes/*.R .gitignore never accidentally track rendered vignettes.","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/use_vignette.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create a vignette or article — use_vignette","text":"","code":"if (FALSE) { # \\dontrun{ use_vignette(\"how-to-do-stuff\", \"How to do stuff\") } # }"},{"path":"https://usethis.r-lib.org/dev/reference/usethis-package.html","id":null,"dir":"Reference","previous_headings":"","what":"usethis: Automate Package and Project Setup — usethis-package","title":"usethis: Automate Package and Project Setup — usethis-package","text":"Automate package project setup tasks otherwise performed manually. includes setting unit testing, test coverage, continuous integration, Git, 'GitHub', licenses, 'Rcpp', 'RStudio' projects, .","code":""},{"path":[]},{"path":"https://usethis.r-lib.org/dev/reference/usethis-package.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"usethis: Automate Package and Project Setup — usethis-package","text":"Maintainer: Jennifer Bryan jenny@posit.co (ORCID) Authors: Hadley Wickham hadley@posit.co (ORCID) Malcolm Barrett malcolmbarrett@gmail.com (ORCID) Andy Teucher andy.teucher@posit.co (ORCID) contributors: Posit Software, PBC [copyright holder, funder]","code":""},{"path":"https://usethis.r-lib.org/dev/reference/usethis_options.html","id":null,"dir":"Reference","previous_headings":"","what":"Options consulted by usethis — usethis_options","title":"Options consulted by usethis — usethis_options","text":"User-configurable options consulted usethis, provide mechanism setting default behaviors various functions. built-defaults suit , set one options. Typically, done .Rprofile startup file, can open editing edit_r_profile() - set specified options future R sessions. code look something like:","code":"options( usethis.description = list( \"Authors@R\" = utils::person( \"Jane\", \"Doe\", email = \"jane@example.com\", role = c(\"aut\", \"cre\"), comment = c(ORCID = \"YOUR-ORCID-ID\") ), License = \"MIT + file LICENSE\" ), usethis.destdir = \"/path/to/folder/\", # for use_course(), create_from_github() usethis.protocol = \"ssh\", # Use ssh git protocol usethis.overwrite = TRUE # overwrite files in Git repos without confirmation )"},{"path":"https://usethis.r-lib.org/dev/reference/usethis_options.html","id":"options-for-the-usethis-package","dir":"Reference","previous_headings":"","what":"Options for the usethis package","title":"Options consulted by usethis — usethis_options","text":"usethis.description: customize default content new DESCRIPTION files setting option named list. frequent package developer, worthwhile pre-configure preferred name, email, license, etc. See example article usethis setup details. usethis.destdir: Default directory place new projects downloaded use_course() create_from_github(). option unset, user's Desktop similarly conspicuous place used. usethis.protocol: specifies preferred transport protocol Git. Either \"https\" (default) \"ssh\": usethis.protocol = \"https\" implies https://github.com//.git usethis.protocol = \"ssh\" implies git@github.com:/.git can also change duration R session use_git_protocol(). usethis.overwrite: TRUE, usethis overwrites existing file without asking user confirmation file inside Git repo. rationale normal Git workflow makes easy see selectively accept/discard proposed changes. usethis.quiet: Set TRUE suppress user-facing messages. Default FALSE. usethis.allow_nested_project: Whether allow create project inside another project. rarely good idea, option defaults FALSE.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/write-this.html","id":null,"dir":"Reference","previous_headings":"","what":"Write into or over a file — write-this","title":"Write into or over a file — write-this","text":"Helpers write new pre-existing file. Designed mostly internal use. File written UTF-8 encoding.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/write-this.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Write into or over a file — write-this","text":"","code":"write_union(path, lines, quiet = FALSE) write_over(path, lines, quiet = FALSE, overwrite = FALSE)"},{"path":"https://usethis.r-lib.org/dev/reference/write-this.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Write into or over a file — write-this","text":"path Path target file. created exist, parent directory must exist. lines Character vector lines. write_union(), lines add target file, already present. write_over(), exact lines desired target file. quiet Logical. Whether message happening. overwrite Force overwrite existing file?","code":""},{"path":"https://usethis.r-lib.org/dev/reference/write-this.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Write into or over a file — write-this","text":"Logical indicating whether write occurred, invisibly.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/write-this.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Write into or over a file — write-this","text":"write_union(): writes lines file, taking union already , anything, new lines. Note, explicit promise line order. Designed modify simple config files like .Rbuildignore .gitignore. write_over(): writes file specific lines, creating necessary overwriting existing, proposed contents identical user available give permission.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/write-this.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Write into or over a file — write-this","text":"","code":"write_union(\"a_file\", letters[1:3]) #> ✔ Adding \"a\", \"b\", and \"c\" to a_file. readLines(\"a_file\") #> [1] \"a\" \"b\" \"c\" write_union(\"a_file\", letters[1:5]) #> ✔ Adding \"d\" and \"e\" to a_file. readLines(\"a_file\") #> [1] \"a\" \"b\" \"c\" \"d\" \"e\" write_over(\"another_file\", letters[1:3]) #> ✔ Writing another_file. readLines(\"another_file\") #> [1] \"a\" \"b\" \"c\" write_over(\"another_file\", letters[1:3]) if (FALSE) { # \\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\") #> [1] TRUE TRUE"},{"path":"https://usethis.r-lib.org/dev/reference/zip-utils.html","id":null,"dir":"Reference","previous_headings":"","what":"Download and unpack a ZIP file — zip-utils","title":"Download and unpack a ZIP file — zip-utils","text":"Functions download unpack ZIP file local folder files, intentional default behaviour. Useful pedagogical settings anytime need large audience download set files quickly actually able find . underlying helpers documented use_course_details.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/zip-utils.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Download and unpack a ZIP file — zip-utils","text":"","code":"use_course(url, destdir = getOption(\"usethis.destdir\")) use_zip( url, destdir = getwd(), cleanup = if (rlang::is_interactive()) NA else FALSE )"},{"path":"https://usethis.r-lib.org/dev/reference/zip-utils.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Download and unpack a ZIP file — zip-utils","text":"url Link ZIP file containing materials. reduce chance typos live settings, shorter forms accepted: GitHub repo spec: \"OWNER/REPO\". Equivalent https://github.com/OWNER/REPO/DEFAULT_BRANCH.zip. bit.ly, pos., rstd.io shortlinks: \"bit.ly/xxx-yyy-zzz\", \"pos./foofy\" \"rstd.io/foofy\". instructor must arrange shortlink point valid download URL target ZIP file. helper create_download_url() helps create URLs GitHub, DropBox, Google Drive. destdir Destination new folder. Defaults location stored global option usethis.destdir, defined, user's Desktop similarly conspicuous place otherwise. cleanup Whether delete original ZIP file unpacking contents. interactive setting, NA leads menu user can approve deletion (decline).","code":""},{"path":"https://usethis.r-lib.org/dev/reference/zip-utils.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Download and unpack a ZIP file — zip-utils","text":"Path new directory holding unpacked ZIP file, invisibly.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/zip-utils.html","id":"functions","dir":"Reference","previous_headings":"","what":"Functions","title":"Download and unpack a ZIP file — zip-utils","text":"use_course(): Designed live workshops mind. Includes intentional friction highlight download destination. Workflow: User executes, e.g., use_course(\"bit.ly/xxx-yyy-zzz\"). User asked notice confirm location new folder. Specify destdir configure \"usethis.destdir\" option prevent . User asked like delete ZIP file. new folder contains .Rproj file, new instance RStudio launched. Otherwise, folder opened file manager, e.g. Finder File Explorer. use_zip(): useful day--day work. Downloads current working directory, default, allows cleanup behaviour specified.","code":""},{"path":"https://usethis.r-lib.org/dev/reference/zip-utils.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Download and unpack a ZIP file — zip-utils","text":"","code":"if (FALSE) { # \\dontrun{ # download the source of usethis from GitHub, behind a bit.ly shortlink use_course(\"bit.ly/usethis-shortlink-example\") use_course(\"http://bit.ly/usethis-shortlink-example\") # download the source of rematch2 package from CRAN use_course(\"https://cran.r-project.org/bin/windows/contrib/3.4/rematch2_2.0.1.zip\") # download the source of rematch2 package from GitHub, 4 ways use_course(\"r-lib/rematch2\") use_course(\"https://api.github.com/repos/r-lib/rematch2/zipball/HEAD\") use_course(\"https://api.github.com/repos/r-lib/rematch2/zipball/main\") use_course(\"https://github.com/r-lib/rematch2/archive/main.zip\") } # }"},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-development-version","dir":"Changelog","previous_headings":"","what":"usethis (development version)","title":"usethis (development version)","text":"use_tidy_upkeep_issue() now records year run Config/usethis/upkeep field DESCRIPTION. value exists furthermore used filter checklist making issue.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"bug-fixes-and-minor-improvements-development-version","dir":"Changelog","previous_headings":"","what":"Bug fixes and minor improvements","title":"usethis (development version)","text":"use_package() now decreases package minimum version required min_version lower currently specified DESCRIPTION file (@jplecavalier, #1957). use_data() now uses serialization version 3 default. (@laurabrianna, #2044) Reverse dependency checks suggested exist (#1817, @seankross).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-300","dir":"Changelog","previous_headings":"","what":"usethis 3.0.0","title":"usethis 3.0.0","text":"CRAN release: 2024-07-29","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"transition-to-cli-package-for-ui-3-0-0","dir":"Changelog","previous_headings":"","what":"Transition to cli package for UI","title":"usethis 3.0.0","text":"ui_*() functions marked superseded. External users functions encouraged use cli package instead. cli package required functionality usethis::ui_*() functions first created, now ’s superior option. cli vignette make transition: vignette(\"usethis-ui\", package = \"cli\"). usethis longer uses ui_*() functions internally, favor new cli-based helpers exported.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"deprecated-function-and-argument-removal-3-0-0","dir":"Changelog","previous_headings":"","what":"Deprecated function and argument removal","title":"usethis 3.0.0","text":"removing functions arguments deprecated usethis v2.0.0, released December 2020. changes place long time now: Switch git2r gert (+ credentials). Use git config gh package infer, e.g., target repo spec. Pivot towards GitHub Actions away Travis AppVeyor. Functions removed , applicable, use instead: git_credentials() use_git_credentials() browse_github_token() (create_github_token()) browse_github_pat() (create_github_token()) github_token() (gh_token_help() gh::gh_token()) pr_pull_upstream() (pr_merge_main()) pr_sync() (pr_merge_main(); pr_push()) use_appveyor() use_appveyor_badge() use_travis() use_travis_badge() browse_travis() use_pkgdown_travis() use_tidy_ci() deprecated v2.1.0 (use_tidy_github_actions()) use_tidy_labels() deprecated v2.1.0 (use_tidy_github_labels()) Function arguments removed: create_from_github(auth_token =, credentials =) use_github(auth_token =, credentials =) use_github_labels(repo_spec =, host =, auth_token =) use_github_links(auth_token =, host =) use_github_release(host =, auth_token =)","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-changes-3-0-0","dir":"Changelog","previous_headings":"","what":"Other changes","title":"usethis 3.0.0","text":"use_zip() use_course() equipped handle ZIP parent folder implicit (@burnsal, #1961). use_test_helper() new function create test helper file (@olivroy, #1822). use_cpp11() makes easier update NAMESPACE (@pachadotdev, #1921). pr_merge_main() now offers choice open files merge conflicts (@olivroy, #1720). edit_rstudio_snippets() now accepts yaml snippets (@olivroy, #1941). use_standalone() inserts improved header includes code needed update standalone file (@krlmlr, #1903). use_release_issue() use_upkeep_issue() behave better user fork. user asked just choose origin upstream target repo (#2023). README templates now recommend pak instead devtools package installation (@olivroy, #1723). use_github() now knows can reuse name earlier repo since renamed (@ateucher, #1893). use_git() longer asks want restart RStudio using Positron. use_test() use_r() now work tests/testthat/_snaps/{foo}.md (@olivroy, #1988). URLs baked badge generated use_coverage(type = \"codecov\") updated longer specify branch(#2008). usethis::use_version() now tolerates empty lines preceding first section title package NEWS file. (#1976)","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-223","dir":"Changelog","previous_headings":"","what":"usethis 2.2.3","title":"usethis 2.2.3","text":"CRAN release: 2024-02-19 Patch release changes .Rd files requested CRAN.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-222","dir":"Changelog","previous_headings":"","what":"usethis 2.2.2","title":"usethis 2.2.2","text":"CRAN release: 2023-07-05 Implicit usage numeric_version() via comparison now always provides character input. response request CRAN anticipate future solutions https://bugs.r-project.org/show_bug.cgi?id=18548.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-221","dir":"Changelog","previous_headings":"","what":"usethis 2.2.1","title":"usethis 2.2.1","text":"CRAN release: 2023-06-23 Internal helper cran_version(), used functions use_release_checklist() use_news_md(), resilient situations CRAN mirror set (#1857). Internal usage numeric_version() now always provides character input, rather relying implicit .character() coercion. response request CRAN anticipate future solutions https://bugs.r-project.org/show_bug.cgi?id=18548 (#1869).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-220","dir":"Changelog","previous_headings":"","what":"usethis 2.2.0","title":"usethis 2.2.0","text":"CRAN release: 2023-06-06","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-functions-2-2-0","dir":"Changelog","previous_headings":"","what":"New functions","title":"usethis 2.2.0","text":"use_author() new function introduce new person Authors@R field DESCRIPTION (@avalcarcel9, #833). use_rstudio_preferences() lets set RStudio preferences programmatically (#1518) use_standalone() new function makes easier use standalone files provided various low-level tidyverse packages, like rlang (#1654). use_upkeep_issue() new function facilitate regular maintenance package. Similar use_release_issue(), opens issue repo checklist maintenance tasks. include additional bullets package includes upkeep_bullets() function returns character vector (#1794).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"package-development-2-2-0","dir":"Changelog","previous_headings":"","what":"Package development","title":"usethis 2.2.0","text":"Although nested projects discouraged, can useful development contexts. create_package() now sets correct package name returns correct package path package nested inside project (#1647). use_article() longer adds rmarkdown package Suggests. Instead, rmarkdown already dependency, ’s added Config/Needs/website. means package uses articles (vs. vignettes) won’t gain unnecessary dependency rmarkdown (#1700). use_data() now sets appropriate minimal R version DESCRIPTION, depending serialization format version choose (@dpprdan, #1672). use_github_links() default now appends GitHub url existing urls URL field DESCRIPTION, rather replacing existing urls (#1805). use_latest_dependencies() longer affects Suggests since dependencies enforced (#1749). use_news_md() now places “(development version)” header NEWS.md development version number DESCRIPTION. also sets first bullet “Initial CRAN submission” looks like “new” package (#1708). use_coverage() longer adds covr Suggests, since test-coverage GitHub Actions workflow takes care installing covr (@Bisaloo, #1851).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"package-release-2-2-0","dir":"Changelog","previous_headings":"","what":"Package release","title":"usethis 2.2.0","text":"use_release_issue() now remind run use_github_links() necessary (@Bisaloo, #1754) use_release_issue() now encourages creation NEWS.md prior submission, instead (#1755). use_github_release() now automatically pushes GitHub (safe) automatically publishes release, rather requiring edit publish draft (#1385). use_github_release() longer fails absence NEWS.md (#1755). use_release_issue() now remind check/close milestone corresponding release, exists (#1642). use_version() use_dev_version() gain push argument optionally push result committing. used eliminate manual step use_release_issue() checklist (#1385). use_revdep() longer places email template, days likely communicate maintainers breaking changes via GitHub issues pull requests (#1769).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"package-file-management-2-2-0","dir":"Changelog","previous_headings":"","what":"Package file management","title":"usethis 2.2.0","text":"rename_files() now also affects files src/ (#1585). use_r() use_test() now work active files R/, src/, tests/testthat/ (#1566). use_r() use_test() now work files containing . (#1690). use_rcpp(), use_c() friends now work way use_r() use_test(): ’ll take default file name file currently open RStudio (#1730).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"git-and-github-2-2-0","dir":"Changelog","previous_headings":"","what":"Git and GitHub","title":"usethis 2.2.0","text":"create_from_github() now use existing .Rproj file exists anywhere repo, just root directory. useful ’re working repos contain tools multiple languages (#1680). git_sitrep() gains two arguments: tool scope, enables limit report , example, tool = \"git\" scope = \"user\". default remains provide full report. Also, provides feedback git user’s information set, checks global git-email user-level GitHub PAT (@ijlyttle, #1732, #1714, #1706). git_vaccinated() now treats path configured core.excludesFile like user-supplied paths; particular, use ~/ home directory shortcut expanded via fs::path_expand() (@dpprdan, #1560). use_github_action() now suggests possible actions called without arguments (#1724). use_github_actions(), use_github_action_check_standard(), use_github_action_check_release(), use_github_action_pr_commands() deprecated favour new interactive powers use_github_action() (#1724).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"minor-improvements-and-fixes-2-2-0","dir":"Changelog","previous_headings":"","what":"Minor improvements and fixes","title":"usethis 2.2.0","text":"Links R Packages book updated second edition book (#1689). SVG badges placed use_lifecycle() improved accessibility features, .e. advertise lifecycle stage via aria-label attribute (#1554, https://github.com/r-lib/lifecycle/issues/117). use_rscloud_badge() deprecated favour use_posit_cloud_badge(), functions now accept updated url format Posit Cloud projects (#1670). use_rstudio() gains reformat argument omits .Rproj settings enforce file formatting conventions, e.g. around whitespace. create_from_github() uses option introduces .Rproj project lacks one, making easier follow project’s existing conventions (#1679). write_over() use_github_file() gain overwrite argument (#1748).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"tidyverse-related-2-2-0","dir":"Changelog","previous_headings":"","what":"Tidyverse-related","title":"usethis 2.2.0","text":"use_release_issue() now uses internal release_extra_revdeps() add extra revdep sources. Currently use internal Posit tooling, hope extend users future (#1610). use_tidy_logo() new function calls use_logo() appropriate hex sticker PNG file https://github.com/rstudio/hex-stickers (#1871).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"deprecated-functions-2-2-0","dir":"Changelog","previous_headings":"","what":"Deprecated functions","title":"usethis 2.2.0","text":"use_tidy_eval() now deprecated imports re-exports large number functions longer needed order tidy evaluation (#1656). use_travis(), use_pkgdown_travis(), browse_travis(), use_appveyor() now deprecated longer recommend Travis Appveyor. recommend GitHub actions instead (#1517).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-216","dir":"Changelog","previous_headings":"","what":"usethis 2.1.6","title":"usethis 2.1.6","text":"CRAN release: 2022-05-25","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"github-related-2-1-6","dir":"Changelog","previous_headings":"","what":"GitHub-related","title":"usethis 2.1.6","text":"use_github_action() friends gain ref argument, defaults tag latest release https://github.com/r-lib/actions (#1541). use_github_actions_badge() now uses URLs GitHub via “Create status badge” helper browser (#1525). changes significance name argument; now really must name workflow configuration file. functions error clearly requested operation supported “” remote configuration (#1588).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-changes-2-1-6","dir":"Changelog","previous_headings":"","what":"Other changes","title":"usethis 2.1.6","text":"use_roxygen_md() gains overwrite argument (#1599). use_rscloud_badge() new function creates README badge indicating repository can launched RStudio Cloud project (@gvelasq, #1584). use_data() gains ascii argument, passed along save() (@JosiahParry, #1625). use_code_of_conduct() updated version 2.1 Contributor Covenant (@batpigandme, #1591).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-215","dir":"Changelog","previous_headings":"","what":"usethis 2.1.5","title":"usethis 2.1.5","text":"CRAN release: 2021-12-09 pkgdown-related functions longer automatically strip trailing slash pkgdown site URL, order play nicely CRAN’s URL checks (#1526). edit_pkgdown_config() new function opens pkgdown YAML configuration file current Project, file exists. error thrown reporting unsupported GitHub configuration fixed forward compatibility future version rlang, .e. anticipated rlang v1.0.0. Version 2.1.4 never released. Version advanced 2.1.4 2.1.5 strictly CRAN (re-)submission purposes.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-213","dir":"Changelog","previous_headings":"","what":"usethis 2.1.3","title":"usethis 2.1.3","text":"CRAN release: 2021-10-27 Modified test ensure intermittent GitHub rate limiting lead ungraceful failure CRAN.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-212","dir":"Changelog","previous_headings":"","what":"usethis 2.1.2","title":"usethis 2.1.2","text":"CRAN release: 2021-10-25 git_default_branch_rename() longer errors repos README exists, badge block. git_default_branch_rediscover() prunes defunct remote ref old default branch, e.g. origin/master. Version 2.1.1 never released. Version advanced 2.1.1 2.1.2 strictly CRAN (re-)submission purposes.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-210","dir":"Changelog","previous_headings":"","what":"usethis 2.1.0","title":"usethis 2.1.0","text":"CRAN release: 2021-10-16","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"git-default-branch-support-2-1-0","dir":"Changelog","previous_headings":"","what":"Git default branch support","title":"usethis 2.1.0","text":"usethis sophisticated understanding default branch gains several functions support default branch renaming. git_branch_default() renamed git_default_branch(), place logically new family functions. old name still works, won’t true forever. intended surface case project renamed default branch local repo needs sync . git_default_branch_rediscover() new function helps contributors update local repo (personal fork, applicable) project/repo renames default branch. git_default_branch_rename() new function helps repo owner rename default branch (GitHub locally). git_default_branch_configure() new function set new Git configuration option init.defaultBranch, controls name initial branch new local repos. git_sitrep() exposes init.defaultBranch surfaces sophisticated analysis git_default_branch().","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-github-related-changes-2-1-0","dir":"Changelog","previous_headings":"","what":"Other GitHub-related changes","title":"usethis 2.1.0","text":"git_sitrep() gh_token_help() try even harder help people get happy path respect GitHub PAT (#1400, #1413, #1488, #1489, #1497). minimum version gh bumped help / force people upgrade gh version supports current GitHub PAT formats (@ijlyttle, #1454). use_github_file() new function related use_template(). Instead starting local file, use_github_file() grabs contents arbitrary file GitHub user permission read. supports targeting specific branch, tag, commit can follow symlink (#1407). use_github_file() now powers use_github_action() friends. use_github_release() much diligent using information left behind devtools::submit_cran() devtools::release(). Specifically, applies determining SHA tagged release. SHA, turn, determines consulted versions DESCRIPTION (package version) NEWS.md (release notes) (#1380). use_release_issue() also takes bullets release_questions(), compatibility devtools::release(). git_vaccinate(), edit_git_ignore(), git_sitrep() careful consult, reveal, set core.excludesFile setting user’s Git configuration (#1461). use_github_action_check_full() removed. ’s overkill majority R packages, better use_github_actions() use_github_action_check_standard() (#1490). use_github_pages() use_pkgdown_github_pages() use new method creating empty, orphan gh-pages branch. necessary due new GitHub behaviour, become essentially impossible refer empty tree (#1472). use_github() can create repositories \"internal\" visibility, feature exists within GitHub Enterprise products (#1505).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"package-development-2-1-0","dir":"Changelog","previous_headings":"","what":"Package development","title":"usethis 2.1.0","text":"use_readme_rmd() use_readme_md() longer include CRAN installation instructions initial template; instead, include GitHub-based install instructions otherwise prompt user update instructions (#1507). use_import_from() new function puts @importFrom pkg fun directives package consistent location (@malcolmbarrett, #1377). DESCRIPTION files generated usethis longer include LazyData default, per new CRAN checks; instead, LazyData now added first time use use_data() (@malcolmbarrett, #1404). use_tidy_eval() updated reflect current recommendations using (therefore exposing) tidy eval packages (@lionel-, #1445). use_pkgdown() automatically uses Bootstrap 5 pkgdown version supports (anticipated pkgdown 2.0.0). use_lifecycle() now imports lifecycle::deprecated() (#1419). use_code_of_conduct() now requires contact argument supply contact details reporting CoC violations (#1269). use_package() longer guides user use dependency change made (@malcolmbarrett, #1384).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"aimed-at-the-tidyverse-team-2-1-0","dir":"Changelog","previous_headings":"Package development","what":"Aimed at the tidyverse team","title":"usethis 2.1.0","text":"functions exported anyone use, aimed primarily maintainers tidyverse, r-lib, tidymodels packages. use_tidy_dependencies() new function sets standard dependencies used tidyverse packages, except designed dependency free (#1423). use_tidy_upkeep_issue() new function similar use_release_issue() creates checklist-style issue prompt various updates (#1416). use_tidy_release_test_env() deleted since longer recommend including test environments cran-comments.md. ’s evidence CRAN finds useful, ’s annoying keep --date (#1365). use_tidy_github_labels() new name use_tidy_labels() (#1430). use_tidy_github_actions() takes use_tidy_ci(), now deprecated.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"user-level-configuration-2-1-0","dir":"Changelog","previous_headings":"","what":"User-level configuration","title":"usethis 2.1.0","text":"\"usethis.overwrite\" new option. set TRUE, usethis overwrites existing file without asking user confirmation file inside Git repo. normal Git workflow makes easy see selectively accept/discard proposed changes. behaviour strictly opt-(#1424). Functions provide code load packages .Rprofile now use rlang::check_installed() make sure package installed locally (@malcolmbarrett, #1398). edit_rstudio_prefs() edit_rstudio_snippets() work now case-sensitive OSes, due path fix re: location RStudio’s config files (@charliejhadley, #1420).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-201","dir":"Changelog","previous_headings":"","what":"usethis 2.0.1","title":"usethis 2.0.1","text":"CRAN release: 2021-02-10 functions require package now ask ’d like install . Added edit_template() opening creating files inst/templates (use use_template()) (@malcolmbarrett, #1319). use_article() now creates file vignettes/articles/ (#548). use_lifecycle() updated changes lifecycle workflow (#1323). use_tidy_pkgdown() renamed use_pkgdown_github_pages() since function useful anyone wants automatically publish GitHub pages, just tidyverse team (#1308). use_release_issue() includes bunch minor improvements. importantly, initial CRAN release now include number common things CRAN checks aren’t R CMD check. use_readme_rmd(), use_readme_md(), use_tidy_contributing(), use_tidy_support() use updated logic determining OWNER/REPO spec target repo (#1312).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-200","dir":"Changelog","previous_headings":"","what":"usethis 2.0.0","title":"usethis 2.0.0","text":"CRAN release: 2020-12-10","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"adoption-of-gert-and-changes-to-gitgithub-credential-handling-2-0-0","dir":"Changelog","previous_headings":"","what":"Adoption of gert and changes to Git/GitHub credential handling","title":"usethis 2.0.0","text":"Usethis various functions help Git-related tasks, break two categories: Git tasks, clone, push, pull. things command line Git. GitHub tasks, fork, release, open issue pull request. things browser GitHub API. ’ve switched git2r gert package Git operations (https://docs.ropensci.org/gert/). continue use gh package GitHub API work (https://gh.r-lib.org). big news area lower-level dependencies getting better finding Git credentials, finding credentials command line Git (, therefore, RStudio), finding credentials . allows usethis shed workarounds needed past, serve remedial “credential valet”. hood, gert gh now consulting local Git credential store, need credentials. time writing, using two different even-lower-level packages : gert uses credentials package (https://docs.ropensci.org/credentials/) gh uses gitcreds package (https://gitcreds.r-lib.org/) Even now, gert gh discover credentials, least github.com. future, two packages may merge one. Git/GitHub credential management covered new article: Managing Git(Hub) Credentials main user-facing changes usethis : usethis discover use credentials command line Git. usethis able work GitHub deployment. github.com default, GitHub Enterprise deployments fully supported. target GitHub host determined current project’s configured GitHub remotes, whenever possible. result, several functions deprecated several functions deprecated arguments. use_git_credentials() git_credentials() github_token() create_from_github() (auth_token, credentials) use_github() (auth_token, credentials) use_github_links() (host, auth_token) use_github_labels() (repo_spec, host, auth_token) use_tidy_labels() (repo_spec, host, auth_token) use_github_release() (host, auth_token) switch gert + credentials eliminate credential-finding fiascos. Gert also takes different approach wrapping libgit2, underlying C library Git operations. result consistent support SSH TLS, across operating systems, without requiring special effort install time. users enjoy Git remote operations “just work”, SSH HTTPS remotes. fewer “unsupported protocol” errors.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"github-remote-configuration-2-0-0","dir":"Changelog","previous_headings":"","what":"GitHub remote configuration","title":"usethis 2.0.0","text":"Usethis gains formal framework characterizing GitHub remote configuration. look : GitHub repositories origin upstream point Whether can push relate , e.g. fork-parent relationship internal matter, users notice usethis clear configurations supported various functions . common configurations reviewed section Happy Git. working fork, sometimes question whether target fork parent repository. example, use_github_links() adds GitHub links URL BugReports fields DESCRIPTION. someone calls use_github_links() working fork, probably want links refer parent source repo, fork, user probably preparing pull request. Usethis now better default behaviour situations , cases, present interactive choice.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"default-branch-2-0-0","dir":"Changelog","previous_headings":"","what":"Default branch","title":"usethis 2.0.0","text":"increasing interest making name repo’s default branch configurable. Specifically, main emerging popular alternative master. Usethis now discovers current repo’s default branch uses everywhere , previously, hard-wired master. git_branch_default() newly exported function also ’s used internally. use_course(), use_zip(), create_download_url() support forming URL download .zip archive repo, based repo specification (e.g. OWNER/REPO) browser URL. helpers now form URL targets HEAD repo, .e. default branch.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"changes-to-gitgithub-functionality-2-0-0","dir":"Changelog","previous_headings":"","what":"Changes to Git/GitHub functionality","title":"usethis 2.0.0","text":"default Git protocol now “https” longer provide interactive choice, default, interactive sessions. always, user can express preference “ssh” individual function calls, R session via use_git_protocol(), R sessions via usethis.protocol option (#1262). pr_resume() new function resuming work existing local PR branch. can called argument-less, select branch interactively. pr_fetch() can also called arguments, select PR interactively. owner argument replaced target, choice source (default) primary repo. pr_forget() new function abandoning PR initiated locally fetched GitHub. local clean , example, doesn’t delete remote branch close PR (#1263). pr_view() can now called arguments. current branch associated open PR, target , otherwise, offer interactive selection. pr_finish() deletes remote PR branch PR merged current user power , .e. external contributor deleting branch maintainer deleting branch associated internal PR (#1150). longer errors PR branch already deleted (#1196). pr_pull_upstream() renamed pr_merge_main() emphasize merges main line development current branch, main line development taken mean default branch, reported git_branch_default(), source repo, either upstream origin, depending situation. create_from_github() create read-clone, due lack GitHub personal access token, explicitly directed via fork = FALSE. create_from_github() use_tidy_thanks() accept browser Git URLs repo_spec argument, friendlier copy/paste. URL passed, host also extracted . create_github_token() new name function previously known browse_github_token() browse_github_pat(). issue_close_community() issue_reprex_needed() two new functions maintainers process lots GitHub issues. automate canned replies actions, e.g. labelling closing (#940). GitHub Actions preferred platform continuous integration, tidyverse team currently uses maintains. Functions related Travis-CI AppVeyor soft-deprecated raise awareness change make clear , substantial maintenance becomes necessary, may elect retire function (#1169). browse_github_actions() new function open Actions page respective repo GitHub, similar existing browse_*() functions (@pat-s, #1102). use_github_pages() new function activate reconfigure GitHub Pages site associated repository (#224). use_tidy_pkgdown() implements complete pkgdown configuration used tidyverse team (#224). pr_sync() deprecated can replicated calling pr_pull(), pr_merge_main(), pr_push().","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"licensing-improvements-2-0-0","dir":"Changelog","previous_headings":"","what":"Licensing improvements","title":"usethis 2.0.0","text":"use_*_license() functions now work projects, just packages. use_apl2_license() (use_apache_license()) use_gpl3_license() longer modify license text (#1198). use_mit_license() now sets default copyright holder “{package} authors”. makes clear copyright holders contributors package; unless using CLA one copyright holder package (#1207). New use_gpl_license() use_agpl_license() make easier pick specific versions GPL AGPL licenses, choose whether include future versions license. default version 3 (). New use_proprietary_license() allows package pass R CMD check making clear code open source (#1163). Thanks @atheriel blog post suggesting wording: https://unconj.ca/blog/copyright--closed-source-r-packages--right-way.html use_lgpl_license() now uses version 3 (), gains new version include_future argument control version used. use_gpl3_license(), use_agpl3_license() use_apl2_license() deprecated favour new version argument use_gpl_license(), use_agpl_license() use_apache_license(). name argument use_mit_license() changed copyright_holder make purpose clear. name argument removed license functions needed; license makes assertion copyright holder .","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"rstudio-preferences-2-0-0","dir":"Changelog","previous_headings":"","what":"RStudio preferences","title":"usethis 2.0.0","text":"usethis now fully cognizant changes RStudio preferences RStudio 1.3: edit_rstudio_snippets() looks new location, snippets old location, automatically copy new location (#1204) New edit_rstudio_prefs() opens RStudio preferences file editing (#1148). use_blank_slate() can now configure global, .e. user-level, RStudio preference, addition project-level (#1018).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-changes-2-0-0","dir":"Changelog","previous_headings":"","what":"Other changes","title":"usethis 2.0.0","text":"browse_package() browse_project() new functions let user choose list URLs derived local Git remotes DESCRIPTION (local possibly CRAN) (#1113). legacy \"devtools.desc\" option longer consulted populating new DESCRIPTION file. must use \"usethis.description\" now (#1069). use_dev_package() gains remote parameter allow specify remote. existing behaviour, adds OWNER/REPO GitHub remote, remains default (#918, @ijlyttle). use_cpp11() new function set R package use cpp11. create_package(roxygen = FALSE) writes valid NAMESPACE file (also Roxygen* fields DESCRIPTION) (#1120). create_package(), create_project(), create_from_github(), proj_activate() work better relative paths, inside outside RStudio (#1122, #954). use_testthat() gains edition argument support testthat v3.0.0 (#1185) use_version() now updates src/version.c exists contains line matching PKG_version = \"x.y.z\";. usethis re-licensed MIT (#1252, #1253).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"dependency-changes-2-0-0","dir":"Changelog","previous_headings":"","what":"Dependency changes","title":"usethis 2.0.0","text":"New Imports: gert, jsonlite (already indirect dependency), lifecycle, rappdirs longer Imports: git2r, rematch2","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-163","dir":"Changelog","previous_headings":"","what":"usethis 1.6.3","title":"usethis 1.6.3","text":"CRAN release: 2020-09-17 Patch release refactor usage withr tests forward compatibility upcoming withr release. changes within usethis tests.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-161","dir":"Changelog","previous_headings":"","what":"usethis 1.6.1","title":"usethis 1.6.1","text":"CRAN release: 2020-04-29 Patch release align path handling internals update coming fs package. use_github_links() bit clever remotes (e.g. origin vs. upstream), makes easier make PR adds GitHub links package ’ve forked. use_pkgdown() now .gitignores destination directory adds destination directory config file departs default (docs/). use_tidy_ci() now deprecated favour use_tidy_github_actions() (#1098). use_github_action_check_standard() new intermediate workflow checks platforms _release, less exhaustive _full (@jimhester). create_tidy_package() now uses MIT license (@topepo, #1096).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-160","dir":"Changelog","previous_headings":"","what":"usethis 1.6.0","title":"usethis 1.6.0","text":"CRAN release: 2020-04-09","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"github-actions-1-6-0","dir":"Changelog","previous_headings":"","what":"GitHub actions","title":"usethis 1.6.0","text":"New use_github_actions(), use_github_action_check_release(), use_github_action_check_full(), use_github_action_pr_commands(), set GitHub Actions package (@jimhester). now recommend GitHub Actions instead Travis-CI AppVeyor, strongly recommend upgrading packages. Fix use_github_action() URL parameter ensure custom URLs allowed. (@coatless, #1065).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"package-creation-1-6-0","dir":"Changelog","previous_headings":"","what":"Package creation","title":"usethis 1.6.0","text":"create_package() gains roxygen argument. TRUE (default), adds RoxygenNote field DESCRIPTION (means first run devtools::check() re-document package, #963), creates empty NAMESPACE (means ’ll always need explicit @export want export functions, #927). also turns markdown processing default (#911). use_rstudio() now sets LineEndingConversion Posix packages created using usethis always use LF line endings, regardless contributes (#1002). usethis.description option, can now set Authors@R = person() directly, without wrap additional layer quotes. setting .Rprofile, ’ll need use utils::person() since utils package isn’t loaded profile executed.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"pr-helpers-1-6-0","dir":"Changelog","previous_headings":"","what":"PR helpers","title":"usethis 1.6.0","text":"new article Pull request helpers demonstrates use pr_*() functions (@mine-cetinkaya-rundel, #802). pr_finish() checks don’t local changes (#805), can optionally finish PR, just current (#1040). pr_pause() pr_fetch() now automatically pull get latest changes (#959, #960) refresh RStudio’s git pane (#706). pr_push() now works repository open pull requests (@maurolepore, #990). pr_pull() gives information files merge conflicts automatically opens conflicted files editing (#1056).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-new-features-1-6-0","dir":"Changelog","previous_headings":"","what":"Other new features","title":"usethis 1.6.0","text":"New rename_files() makes easy rename paired R/ test/ files (#784). New ui_silence() makes easier selectively silence UI output. New use_agpl3_license() (@pachamaltese, #870). New use_data_table() set package Import-ing data.table (@michaelchirico, #897). use_latest_dependencies() replaces use_tidy_version() new name better reflect usage (#771). New use_lifecycle() helper import lifecycle badges functions arguments package. Learn https://lifecycle.r-lib.org/. use_release_issue() include additional bullets package includes release_bullets() function returns character vector (package loaded load_all()) (#941).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"minor-improvements-and-bug-fixes-1-6-0","dir":"Changelog","previous_headings":"","what":"Minor improvements and bug fixes","title":"usethis 1.6.0","text":"writing files, usethis now respects line endings. Default line endings taken .Rproj file (available), otherwise DESCRIPTION, otherwise first file found R/, else failing platform default (#767). better job preserving UTF-8 files windows (#969). browse_github() now always goes canonical GitHub site: https://github.com/user/repo. slightly worse current behaviour makes function consistent across packages, considerably simplifies implementation. browse_circle() opens project dashboard Circle CI. create_download_url() new helper making “ZIP file download” URLs suitable use use_course() use_zip(), starting URLs mere mortals can usually get hands browser (@fmichonneau, #406). create_package() longer fails partway malformed usethis.description option (#961). create_package() now create package symlink directory (#794). create_package() use_description() gain check_name argument control whether check package names invalid CRAN (@noamross, #883). edit_file() use_test() gain open parameter allows control whether function opened editing user (#817). edit_rstudio_snippets() makes clear snippet types allowed user’s snippets mask built-snippets (@GegznaV, #885). git_sitrep() now reports project-specific user name email, set (#837), email(s) associated GitHub account (@dragosmg, #724). ui_yeah() ui_nope() allow override default “yes” “” strings opt-shuffling (@rundel, #796). use_circleci() uses correct delimiters template (@jdblischak, #835). use_circleci_badge() now exported (@pat-s, #920). use_code_of_conduct() now generates absolute link code conduct pkgdown website original source avoid R CMD check issues (#772). use_course() use_zip() now equipped retry capability, cope intermittent failure need longer connect timeout (#988). use_data() automatically bumps R dependency 2.10 (#962). use_data_raw() template quotes dataset name correctly (#736, @mitchelloharawild). use_description_defaults() now shows default fields combined options set. use_dev_package() now supports packages installed remote type, just GitHub (@antoine-sachet, #1071). use_git() now create initial commit needed (#852). use_github_release() longer fails news bullets (#1048). use_github_release() now tags latest local commit instead latest remote commit default branch (@davidchall, #1029). use_gpl3_license() now completes license providing additional information file named LICENSE, just like use_mit_license() friends (@Cervangirard, #683). use_logo() now generates correct href pkgdown url set (@mitchelloharawild, #986). use_make() gains missing closing parenthesis (@ryapric, #804). use_markdown_template() longer uses unexported function default arguments (@fmichonneau, #761). use_testthat() use_test() now work projects, just packages (#1017). use_test() works Windows called without arguments (#901). use_tidy_issue_template() uses current github format (@Maschette, #756). use_travis(), use_travis_badge(), browse_travis(), now default ext = \"com\" since travis-ci.com now recommended travis-ci.org (@riccardoporreca, #1038). use_release_issue() reminds re-generate README.md, needed (#767). use_r() use_test() throw clear error multiple names provided (@strboul, #862). use_rcpp() use_c() now ensure src/ contains least one .cpp .c placeholder file, package can built (@coatless, #720). usethis.destdir new option consulted deciding put new folder created use_course() create_from_github() (@malcolmbarrett, #1015). use_lifecycle() longer adds lifecycle package DESCRIPTION file. new roxygen markdown syntax including badges, lifecycle become build-time dependency.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"dependency-changes-1-6-0","dir":"Changelog","previous_headings":"","what":"Dependency changes","title":"usethis 1.6.0","text":"New Imports: cli, rematch2, rlang. gh minimum version bumped v.1.1.0, due changed behaviour around requests return nothing. clisymbols removed Imports.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-151","dir":"Changelog","previous_headings":"","what":"usethis 1.5.1","title":"usethis 1.5.1","text":"CRAN release: 2019-07-04 patch release various small features bug fixes.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"using-the-pipe--or-the-tidy-eval-toolkit-in-your-package-1-5-1","dir":"Changelog","previous_headings":"","what":"Using the pipe %>% or the tidy eval toolkit in your package","title":"usethis 1.5.1","text":"templates used use_pipe() use_tidy_eval() use robust form cross-reference links, linking files rather topics. silence warnings seen Windows install time (#730, #731 @jmgirard). use_pipe() gains logical export argument, can setup necessary use pipe operator re-exported (export = TRUE, default preserves previous behaviour) (export = FALSE) (#783).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"git-github-and-pull-requests-1-5-1","dir":"Changelog","previous_headings":"","what":"Git, GitHub, and pull requests","title":"usethis 1.5.1","text":"use_github() removes newline \\n characters description can cause initial push fail (#493, @muschellij2). git_sitrep() gives better feedback can’t validate GitHub PAT (#725, @ijlyttle). create_from_github() sets remote tracking branch master upstream/master, creates (clones) fork (#792). pr_pause() can switch back master even remote tracking branch (#715, @cderv).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"build-tools-and-continuous-integration-1-5-1","dir":"Changelog","previous_headings":"","what":"Build tools and continuous integration","title":"usethis 1.5.1","text":"use_tidy_ci() updated R 3.6, meaning R 3.2 oldest version R supported proactive testing. use_make() use_jenkins() add Makefile Jenkinsfile, respectively (#501, @ryapric). use_circleci() creates .circleci/config.yaml config file CircleCI (#703, @jdblischak).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-1-5-1","dir":"Changelog","previous_headings":"","what":"Other","title":"usethis 1.5.1","text":"use_zip() new variant use_course() downloads unpacks ZIP file, less pedantic behaviour re: destination directory. functions now also work ZIP files MIME type \"application/x-zip-compressed\" (#573). use_version() can detect \"(development version)\" NEWS header update actual version (#768, @DavisVaughan).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"dependency-changes-1-5-1","dir":"Changelog","previous_headings":"","what":"Dependency changes","title":"usethis 1.5.1","text":"R 3.1 longer explicitly supported tested. general practice support current release (3.6, time writing), devel, 4 previous versions R (3.5, 3.4, 3.3, 3.2). fs minimum version stated v1.3.0. glue minimum version stated v1.3.0.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-150","dir":"Changelog","previous_headings":"","what":"usethis 1.5.0","title":"usethis 1.5.0","text":"CRAN release: 2019-04-07","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"git-github-and-gitlab-1-5-0","dir":"Changelog","previous_headings":"","what":"Git, GitHub (and GitLab)","title":"usethis 1.5.0","text":"usethis gains several functions inspect manipulate Git situation current project = repository. also provide control visibility git2r’s workings, especially around credentials (usethis uses git2r Git operations). git_sitrep() lets know ’s Git, git2r GitHub config (#328). git_vaccinate() vaccinates global (.e. user-level) git ignore file. adds standard entries R users, .Rhistory .Rdata. decreases chance commit push files containing confidential information (#469). git_remotes() use_git_remote() new helpers inspect modify Git remote URLs repo associated active project (#649). git_protocol() + use_git_protocol() git_credentials() + use_git_credentials() new helpers summon set Git transport protocol (SSH HTTPS) git2r credentials, respectively. functions primarily internal use. users can rely default behaviour. Use helpers intervene git2r isn’t discovering right credentials (#653). usethis honors usethis.protocol option, allows express general preference SSH vs. HTTPS. improvements bug fixes: use_github() tries harder also fails earlier, informative messages, making less likely leave repo partially configured (#221). use_github() create_from_github() gain protocol argument (#494, @cderv). create_from_github() pulls upstream master fork (#695, @ijlyttle). use_release_issue() creates GitHub issue containing release checklist, reflecting standard practices tidyverse team (#338). use_github_release() creates draft GitHub release using entries NEWS.md (#137). use_gitlab_ci() creates gitlab-ci.yaml config file GitLab CI (#565, @overmar). use_git_config() now invisibly returns previous values settings. use_github_labels() rewritten flexible. can now supply repo name, descriptions, can set colours/descriptions independently creating labels. can also rename existing labels (#290).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"github-pull-requests-1-5-0","dir":"Changelog","previous_headings":"","what":"GitHub pull requests","title":"usethis 1.5.0","text":"’ve added experimental functions work GitHub pull requests. aimed maintainer (may make, review, modify pull requests) contributor (may make explore pull requests). git_sitrep() includes section end aimed describing “pull request readiness”. Expect develop expand. pr_init(), pr_fetch(), pr_push(), pr_pull(), pr_finish(), pr_view() constitute new family helpers. designed smart significance remotes standard names origin upstream facilitate internal external pull requests.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"partial-file-management-1-5-0","dir":"Changelog","previous_headings":"","what":"Partial file management","title":"usethis 1.5.0","text":"usethis gains tooling manage part file. currently used managing badges README roxygen import tags: use_badge() friends now automatically add badges README contains specially formatted badge block (#497): use_tibble() use_rcpp() automatically add roxygen tags {package}-package.R contains specially formatted namespace block (#517): Unfortunately means use_rcpp() longer supports non-roxygen2 workflows, suspect set people use usethis Rcpp roxygen2 small.","code":"<-- badge:start --> <-- badge:end --> ## usethis namespace: start ## usethis namespace: end NULL"},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"extending-and-wrapping-usethis-1-5-0","dir":"Changelog","previous_headings":"","what":"Extending and wrapping usethis","title":"usethis 1.5.0","text":"New proj_activate() lets activate project, either opening new RStudio session (use RStudio) changing working directory (#511). proj_get() proj_set() longer quiet argument. user-facing message setting project now control messages, .e. getOption(\"usethis.quiet\", default = FALSE) (#441). new set ui_*() functions makes possible give code user interface usethis (#308). use glue crayon packages power easy interpolation formatting. four families functions: block styles: ui_line(), ui_done(), ui_todo(), ui_oops(), ui_info(). conditions: ui_stop(), ui_warn(). questions: ui_yeah(), ui_nope(). inline styles: ui_field(), ui_value(), ui_path(), ui_code(). with_project() local_project() new withr-style functions temporarily set active usethis project. make usethis functions easier use ad hoc fashion another package (#441).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"tidyverse-standards-1-5-0","dir":"Changelog","previous_headings":"","what":"Tidyverse standards","title":"usethis 1.5.0","text":"standards (aspirationally) used tidyverse packages; welcome use find helpful. Call use_tidy_labels() update GitHub labels. Colours less saturated, docs now documentation, use emoji, performance longer automatically added repos (#519). Repo specific issues given colour #eeeeee emoji. Call use_logo() update package logo latest specifications: man/figure/logo.png 240 x 278, README contain . gives nicer display retina displays. logo also linked pkgdown site available (#536). creating new package, use create_tidy_package() start package following tidyverse standards (#461). NEWS.md development version use “(development version)” rather specific version (#440). pkgdown sites now built travis deployed automatically GitHub pages. use_pkgdown_travis() help set . starting release process, call use_release_issue() create release checklist issue (#338). Prior CRAN submission call use_tidy_release_test_env() update test environment section cran-comments() (#496). acceptance, try use_github_release() automatically create release. ’s created draft chance look publishing. use_vignette() includes standard initialisation chunk knitr::opts_chunk$set(comment = \"#>\", collapse = TRUE) used Rmds.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-functions-not-already-mentioned-1-5-0","dir":"Changelog","previous_headings":"","what":"New functions not already mentioned","title":"usethis 1.5.0","text":"use_devtools() (#624), use_conflicted() (#362), use_reprex() (#465) help add useful packages .Rprofile. use_partial_warnings() helps user add standard warning block .Rprofile (#64). edit_r_buildignore() opens .Rbuildignore manual editing (#462, @bfgray3). use_lgpl_license() automates set LGL license (#448, @krlmlr). use_ccby_license() adds CCBY 4.0 license (#547, @njtierney). use_rcpp_armadillo() use_rcpp_eigen() set package use RcppArmadillo RcppEigen, respectively (#421, @coatless, @duckmayr). use_c(\"foo\") sets src/ creates src/foo.c (#117). use_covr_ignore() makes easy ignore files test coverage (#434). use_pkgdown_travis() helps set pkgdown automatic build--deploy Travis-CI GitHub Pages (#524). use_addin() setup RStudio addins (#353, @haozhu233). use_tutorial() creates new interactive R Markdown tutorial, implemented learnr package (@angela-li, #645). use_article() creates articles, vignettes automatically added .Rbuildignore. appear pkgdown sites, included package (#281). use_citation() creates basic CITATION template puts right place (#100).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-minor-bug-fixes-and-improvements-1-5-0","dir":"Changelog","previous_headings":"","what":"Other minor bug fixes and improvements","title":"usethis 1.5.0","text":"write_union() appends novel lines, remove duplicates existing lines (#583, @khailper). use_rcpp(\"foo\") now creates src/foo.cpp (#117). use_data() gains version argument defaults serialization format version 2 (#675). use_data_raw() accepts name --prepared dataset opens templated R script (#646). browse_github() now falls back CRAN organisation (warning) package doesn’t GitHub repo (#186). create_*() restore active project error part way , use proj_activate() (#453, #511). edit_r_profile() edit_r_environ() now respect environment variables R_PROFILE_USER R_ENVIRON_USER, respectively (#480). use_description() prints generated description (#287). use_description_field() longer sensitive whitespace, allows use_vignette() work even VignetteBuilder field spread multiple lines (#439). use_logo() can override existing logo user gives permission (#454). also produces retina appropriate logos default, matches aspect ratio http://hexb./sticker.html specification (#499). use_news_md() optionally commit. use_package() gains min_version argument specify minimum version requirement (#498). Set TRUE use currently installed version (#386). used use_tidy_eval() order require version 0.1.2 greater rlang (#484). use_pkgdown() now configurable site options (@jayhesselberth, #467), longer creates docs/ directory (#495). use_test() longer forces filename lowercase (#613, @stufield). use_test() include context() generated file used testthat 2.1.0 (future release testthat) (#325). use_tidy_description() sets Encoding field DESCRIPTION (#502, @krlmlr). use_tidy_eval() re-exports := (#595, @jonthegeek). use_tidy_versions() source argument can choose use local CRAN versions (#309). use_travis() gains ext argument, defaulting \"org\". Use ext = \"com\" https://travis-ci.com (@cderv, #500). use_version() asks committing. use_vignette() now title argument used YAML header (two places needed). vignettes also lose default author date fields (@rorynolan, #445), R Markdown starter material. gain standard setup chunk. use_version(\"dev\") now creates standard “(development version)” heading NEWS.md (#440). use_vignette() now checks vignette name valid (starts letter consists letters, numbers, hyphen, underscore) throws error (@akgold, #555). restart_rstudio() now returns FALSE RStudio project open, fixing issue caused errors helpers suggest restarting RStudio (@gadenbuie, #571).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"dependency-changes-1-5-0","dir":"Changelog","previous_headings":"","what":"Dependency changes","title":"usethis 1.5.0","text":"withr moves Suggests Imports. purrr yaml new Imports.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-140","dir":"Changelog","previous_headings":"","what":"usethis 1.4.0","title":"usethis 1.4.0","text":"CRAN release: 2018-08-14","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"file-system-1-4-0","dir":"Changelog","previous_headings":"","what":"File system","title":"usethis 1.4.0","text":"usethis file system operations now use fs package (#177). change usethis functions, users may notice features fs-mediated paths: Paths “tidy”, meaning / path separator never multiple trailing /. Paths UTF-8 encoded. Windows user’s home directory interpreted C:\\Users\\username (typical Unix-oriented tools, like Git ssh; also matches Python), opposed C:\\Users\\username\\Documents (R’s default Windows). Read fs::path_expand().","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"extending-or-wrapping-usethis-1-4-0","dir":"Changelog","previous_headings":"","what":"Extending or wrapping usethis","title":"usethis 1.4.0","text":"changes make easier others extend usethis, .e. create workflow packages specific organization, use usethis packages. proj_path() newly exported. Use build paths within active project. Like proj_get() proj_set(), aimed end users, rather use extension packages. End users use rprojroot simpler companion, , programmatically detect project build paths within (#415, #425). edit_file(), write_over(), write_union() newly exported helpers. mostly internal use, can also useful packages extend customize usethis (#344, #366, #389). use_template() longer errors user chooses overwrite existing file simply exits confirmation file unchanged (#348, #350, @boshek). getOption(\"usethis.quiet\", default = FALSE) consulted printing user-facing messages. Set option TRUE suppress output, e.g., use usethis functions quietly another package. example, use withr::local_options(list(usethis.quiet = TRUE)) calling function (#416, #424).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-functions-1-4-0","dir":"Changelog","previous_headings":"","what":"New functions","title":"usethis 1.4.0","text":"proj_sitrep() reports current working directory, active usethis project, active RStudio Project. Call function things seem weird ’re sure ’s wrong fix . Designed interactive use debugging, programmatic use (#426). use_tibble() minimum setup necessary package returns exports tibble. example, guarantees tibble print tibble (#324 @martinjhnhadley). use_logo() resizes adds logo package (#358, @jimhester). use_spell_check() adds whitelist words unit test spell check package documentation R CMD check (#285 @jeroen).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"other-small-changes-and-bug-fixes-1-4-0","dir":"Changelog","previous_headings":"","what":"Other small changes and bug fixes","title":"usethis 1.4.0","text":"usethis new logo! (#429) use_course() reports progress download (#276, #380). use_git() makes initial commit files user gives explicit consent (#378). create_from_github(): repo argument renamed repo_spec, since takes input form “OWNER/REPO” (#376). use_depsy_badge() deprecated. Depsy project officially concluded longer maintained (#354). use_github() fails earlier, informative message, absence GitHub personal access token (PAT). Also looks PAT proactively usual environment variables (.e., GITHUB_PAT, GITHUB_TOKEN) (#320, #340, @cderv). logic setting DESCRIPTION fields create_package() use_description() got Spring Cleaning. Fields directly specified user take precedence, named list getOption(\"usethis.description\") consulted, finally defaults built usethis. use_description_defaults() new function reveals fields found options built usethis. Options specific one DESCRIPTION field, e.g. devtools.desc.license, longer supported. Instead, use single named list fields, preferably stored option named \"usethis.description\" (however,\"devtools.desc\" still consulted backwards compatibility). (#159, #233, #367)","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"dependency-changes-1-4-0","dir":"Changelog","previous_headings":"","what":"Dependency changes","title":"usethis 1.4.0","text":"New Imports: fs, glue, utils longer Imports: backports, httr, rematch2, rmarkdown (moved Suggests), styler (moved Suggests)","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-130","dir":"Changelog","previous_headings":"","what":"usethis 1.3.0","title":"usethis 1.3.0","text":"CRAN release: 2018-02-24 usethis website: https://usethis.r-lib.org (#217). includes article advice system setup, usethis R development generally. edit_*() functions now return target path, invisibly (#255). edit_git_ignore(scope = \"user\") prefers ~/.gitignore, detects existing ~/.gitignore_global, exists. new global gitignore file created, created ~/.gitignore recorded user’s git config core.excludesfile (#255). create_from_github() gains several arguments new functionality. protocol argument lets user convey whether remote URLs ssh https. case “fork clone”, original repo added upstream remote. now possible – although rarely necessary – directly specify GitHub PAT, credentials (git2r form), GitHub host (#214, #214, #253). use_github_labels() can create update colour arbitrary GitHub issue labels, defaulting set labels colours used tidyverse packages, now exposed via tidy_labels(). set now includes labels “good first issue” “help wanted” (#168, #249). appveyor_info() longer reverses repo’s URL image link. Corrects markdown produced use_appveyor_badge() (#240, @llrs). use_cran_badge() uses HTTPS URL CRAN badge image (#235, @jdblischak). create_package() create_project() return normalized path, even target directory pre-exist (#227, #228).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-functions-1-3-0","dir":"Changelog","previous_headings":"","what":"New functions","title":"usethis 1.3.0","text":"use_git_config() can set user’s Git name email, globally locally project/repo (#267). browse_github_pat() goes webpage GitHub user can create personal access token (PAT) GitHub API. user configures PAT, can use functions like create_from_github() use_github() easily create connect GitHub repos local projects. (#248, #257, @jeroen, via @jennybc). use_version() increments version active package, including interactive chooser. use_dev_version() now special case wrapper around . (#188, #223, @EmilHvitfeldt). use_tidy_github() creates standard set files make GitHub repository navigable users contributors: issue template, contributing guidelines, support documentation, code conduct. now placed .github/ subdirectory (#165, @batpigandme). use_bioc_badge creates Bioconductor badge links build report (#271, @LiNk-NY). use_binder_badge() creates badge indicating repository can launched executable environment via Binder (#242, @uribo).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-120","dir":"Changelog","previous_headings":"","what":"usethis 1.2.0","title":"usethis 1.2.0","text":"CRAN release: 2018-01-19","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-functions-1-2-0","dir":"Changelog","previous_headings":"","what":"New functions","title":"usethis 1.2.0","text":"use_course() downloads folder’s worth materials ZIP file, deliberate choices around default folder name location. Developed use start workshop. Helps participants obtain materials , e.g., DropBox folder GitHub repo (#196). use_blank_slate() provides way opt RStudio workflow user’s workspace neither saved reloaded R sessions. Automated scope = \"project\". Provides UI instructions scope = \"user\", now (#139). use_tidy_style() styles entire project according https://style.tidyverse.org (#72, #197 @lorenzwalthert). GitHub conventions common tidyverse packages enacted use_tidy_contributing(), use_tidy_issue_template(), use_tidy_support() (@batpigandme, #143, #166). changes New projects don’t exhibit obvious criteria “project” include sentinel, empty file named ., can recognized project. Project launching switching works RStudio server (#115, #129). use_template() newly exported, packages can provide templating functions using framework (@ijlyttle #120). use_readme_rmd() use_readme_md() work, similar fashion, projects package (#131, #135). use_readme_rmd() creates pre-commit git hook, help keep README.Rmd README.md sync (@PeteHaitch #41). Substantial increase unit test coverage.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-110","dir":"Changelog","previous_headings":"","what":"usethis 1.1.0","title":"usethis 1.1.0","text":"CRAN release: 2017-11-17","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-helpers-1-1-0","dir":"Changelog","previous_headings":"","what":"New helpers","title":"usethis 1.1.0","text":"browse_github(), browse_github_issues(), browse_github_pulls(), browse_cran() browse_travis() open useful websites related current project named package. (#96, #103). create_from_github() creates project existing GitHub repository, forking needed (#109). use_cc0_license() applies CC0 license, particularly appropriate data packages (#94) use_lifecycle_badge() creates badge describing current stage project lifecycle (#48). use_pkgdown() creates basics needed pkgdown website (#88). use_r(\"foo\") creates edit R/foo.R file. test file open, use_r() open corresponding .R file (#105). use_tidy_versions() sets minimum version requirement dependencies.","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"bug-fixes-and-improvements-1-1-0","dir":"Changelog","previous_headings":"","what":"Bug fixes and improvements","title":"usethis 1.1.0","text":"use_dev_version() now correctly updates Version field package description file. (@tjmahr, #104) use_revdep() now also git-ignores SQLite database (#107). use_tidy_eval() tweaked reflect current guidance (#106)","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"usethis-100","dir":"Changelog","previous_headings":"","what":"usethis 1.0.0","title":"usethis 1.0.0","text":"CRAN release: 2017-10-22 new package extracts many functions previously lived devtools, well providing building blocks can create helpers. well many new helpers listed , three main improvements package: support general R projects, packages. notion “active” project commands operate . Refined output. usethis gradually evolving towards supporting general R “projects”, just packages. still work progress, please let know use function think work projects doesn’t. can also try new create_project() creates basic RStudio project. concept working directory “base path” refined. Rather using argument specify active project, use_ functions now use global active project setting, returned proj_get(). cached throughout session, although updated create_package() create_project(). ’ll now get clear error attempt use_something() outside project, create_something() warn ’re trying create inside existing project. output usethis commands reviewed informative overwhelming. usethis takes advantage colour (using crayon RStudio 1.1) help chunk output clearly differentiate need vs. done .","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-functions-1-0-0","dir":"Changelog","previous_headings":"","what":"New functions","title":"usethis 1.0.0","text":"use_apl2_license() want use Apache 2.0 license. use_depsy_badge() allows including Depsy badge (@gvegayon, #68). use_dev_package() works like use_package() also adds repo Remotes field (#32). use_github_labels() automatically set standard set labels, optionally removing default labels (#1). use_pipe() creates template use magrittr’s %>% package (#15). use_tidy_ci() sets travis codecov using tidyverse conventions (#14) use_tidy_description() puts description fields standard order alphabetises dependencies. use_tidy_eval() imports re-exports recommend set tidy eval helpers package uses tidy eval (#46). use_usethis() opens .Rprofile gives code copy paste .","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"new-edit-functions-1-0-0","dir":"Changelog","previous_headings":"","what":"New edit functions","title":"usethis 1.0.0","text":"new class functions make easy edit common config files: edit_r_profile_user() opens .Rprofile edit_r_environ_user() opens .Renviron edit_r_makevars_user() opens .R/Makevars edit_git_config_user() opens .gitconfig edit_git_ignore_user() opens .gitignore edit_rstudio_snippets(type) opens ~/R/snippets/{type}.snippets","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"updates-1-0-0","dir":"Changelog","previous_headings":"","what":"Updates","title":"usethis 1.0.0","text":"use_coverage(\"codecov\") now sets default threshold 1% try reduce false positives (#8). use_description() now sets ByteCompile: true can benefit byte compiler (#29) license functions (use_mit_license(), use_apl2_license(), use_gpl3_license()) save copy standard license text LICENSE.md, added .Rbuildignore. allows follow standard licensing best practices adhering CRANs requirements (#10). use_package_doc() uses modern roxygen2 template requires less duplication. use_test() use name currently open file RStudio don’t supply explicit name (#89). use_readme_rmd() now puts images man/figures/ longer adds .Rbuildgnore. ensures rendered README.md also work CRAN (#16, #19). first chunk now uses include = FALSE named setup (#19). use_revdep() creates structure use revdepcheck package, preferred way run revdepchecks. (#33)","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"building-blocks-1-0-0","dir":"Changelog","previous_headings":"","what":"Building blocks","title":"usethis 1.0.0","text":"New use_badge() adding badge README. Now prints todo message badge already exist. use_directory() now exported (#27).","code":""},{"path":"https://usethis.r-lib.org/dev/news/index.html","id":"bug-fixes-and-minor-improvements-1-0-0","dir":"Changelog","previous_headings":"","what":"Bug fixes and minor improvements","title":"usethis 1.0.0","text":"Functions require code copied now automatically put code clipboard available (#52). create_package() longer creates dependency current version use_build_ignore() now strips trailing / use_git() restart RStudio needed (possible) (#42). use_github() now organisation parameter can create repos organisations (#4). use_template() use_test() now convert title slug contains lowercase letters, numbers, -. use_vignette() now adds *.html *.R .gitgnore don’t accidentally add compiled vignette products (#35). use_travis_badge() use_appveyor_badge() now exported functions, can used even ci separately set (#765, @smwindecker).","code":""}]