EVOLUTION-MANAGER
Edit File: use_github.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Connect a local repo with GitHub</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for use_github {usethis}"><tr><td>use_github {usethis}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Connect a local repo with GitHub</h2> <h3>Description</h3> <p><code>use_github()</code> takes a local project and: </p> <ul> <li><p> Checks that the initial state is good to go: </p> <ul> <li><p> Project is already a Git repo </p> </li> <li><p> Current branch is the default branch, e.g. <code>main</code> or <code>master</code> </p> </li> <li><p> No uncommitted changes </p> </li> <li><p> No pre-existing <code>origin</code> remote </p> </li></ul> </li> <li><p> Creates an associated repo on GitHub </p> </li> <li><p> Adds that GitHub repo to your local repo as the <code>origin</code> remote </p> </li> <li><p> Makes an initial push to GitHub </p> </li> <li><p> Calls <code><a href="use_github_links.html">use_github_links()</a></code>, if the project is an R package </p> </li> <li><p> Configures <code>origin/DEFAULT</code> to be the upstream branch of the local <code>DEFAULT</code> branch, e.g. <code>main</code> or <code>master</code> </p> </li></ul> <p>See below for the authentication setup that is necessary for all of this to work. </p> <h3>Usage</h3> <pre> use_github( organisation = NULL, private = FALSE, visibility = c("public", "private", "internal"), protocol = git_protocol(), host = NULL, auth_token = deprecated(), credentials = deprecated() ) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>organisation</code></td> <td> <p>If supplied, the repo will be created under this organisation, instead of the login associated with the GitHub token discovered for this <code>host</code>. The user's role and the token's scopes must be such that you have permission to create repositories in this <code>organisation</code>.</p> </td></tr> <tr valign="top"><td><code>private</code></td> <td> <p>If <code>TRUE</code>, creates a private repository.</p> </td></tr> <tr valign="top"><td><code>visibility</code></td> <td> <p>Only relevant for organisation-owned repos associated with certain GitHub Enterprise products. The special "internal" <code>visibility</code> grants read permission to all organisation members, i.e. it's intermediate between "private" and "public", within GHE. When specified, <code>visibility</code> takes precedence over <code>private = TRUE/FALSE</code>.</p> </td></tr> <tr valign="top"><td><code>protocol</code></td> <td> <p>One of "https" or "ssh"</p> </td></tr> <tr valign="top"><td><code>host</code></td> <td> <p>GitHub host to target, passed to the <code>.api_url</code> argument of <code><a href="../../gh/html/gh.html">gh::gh()</a></code>. If unspecified, gh defaults to "https://api.github.com", although gh's default can be customised by setting the GITHUB_API_URL environment variable. </p> <p>For a hypothetical GitHub Enterprise instance, either "https://github.acme.com/api/v3" or "https://github.acme.com" is acceptable.</p> </td></tr> <tr valign="top"><td><code>auth_token, credentials</code></td> <td> <p><a href="https://lifecycle.r-lib.org/articles/stages.html#deprecated"><img src="../help/figures/lifecycle-deprecated.svg" alt='[Deprecated]' /></a>: No longer consulted now that usethis uses the gert package for Git operations, instead of git2r; gert relies on the credentials package for auth. The API requests are now authorized with the token associated with the <code>host</code>, as retrieved by <code><a href="../../gh/html/gh_token.html">gh::gh_token()</a></code>.</p> </td></tr> </table> <h3>Git/GitHub Authentication</h3> <p>Many usethis functions, including those documented here, potentially interact with GitHub in two different ways: </p> <ul> <li><p> Via the GitHub REST API. Examples: create a repo, a fork, or a pull request. </p> </li> <li><p> As a conventional Git remote. Examples: clone, fetch, or push. </p> </li></ul> <p>Therefore two types of auth can happen and your credentials must be discoverable. Which credentials do we mean? </p> <ul> <li><p> A GitHub personal access token (PAT) must be discoverable by the gh package, which is used for GitHub operations via the REST API. See <code><a href="github-token.html">gh_token_help()</a></code> for more about getting and configuring a PAT. </p> </li> <li><p> If you use the HTTPS protocol for Git remotes, your PAT is also used for Git operations, such as <code style="white-space: pre;">git push</code>. Usethis uses the gert package for this, so the PAT must be discoverable by gert. Generally gert and gh will discover and use the same PAT. This ability to "kill two birds with one stone" is why HTTPS + PAT is our recommended auth strategy for those new to Git and GitHub and PRs. </p> </li> <li><p> If you use SSH remotes, your SSH keys must also be discoverable, in addition to your PAT. The public key must be added to your GitHub account. </p> </li></ul> <p>Git/GitHub credential management is covered in a dedicated article: <a href="https://usethis.r-lib.org/articles/articles/git-credentials.html">Managing Git(Hub) Credentials</a> </p> <h3>Examples</h3> <pre> ## Not run: 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() ## End(Not run) </pre> <hr /><div style="text-align: center;">[Package <em>usethis</em> version 2.1.6 <a href="00Index.html">Index</a>]</div> </body></html>