githug_init: Make a local directory into a Git repository that tracks a...
In jennybc/githug: Interface to local and remote Git operations

Description Usage Arguments Details Value Examples

Take a local project, put it under version control if necessary, optionally make it an RStudio Project, create a companion repository on GitHub, connect them, and, if in an interactive session, visit the new repo in the browser. Inspired by hub create from the hub command line tool.

1
2
3

githug_init(path = ".", name = NULL, description = NULL,
  remote_name = "origin", protocol = c("https", "ssh"), cred = NULL,
  pat = gh_pat(), rstudio = TRUE, ...)

`path`	Path to the directory where a Git repo should be initialized, if not done already, and connected to GitHub, optional. Defaults to working directory.
`name`	Name of the new repository, optional. Default behavior if unspecified: if an RStudio project file is found in `path`, `name` will be the filename, after removing the `.Rproj` extension. Otherwise, `name` will be the `basename()` of `path`.
`description`	Short description of the GitHub repository, optional.
`remote_name`	Name for the new GitHub remote, optional. Defaults to `origin`.
`protocol`	Transfer protocol, either "https" (the default) or "ssh".
`cred`	Credential object, in the sense of the `git2r` package, optional. If you are already able to push and pull from the command line, you can probably ignore this. See details for more.
`pat`	A GitHub personal access token (PAT) from https://github.com/settings/tokens. The "repo" scope is required which is one of the default scopes for a new PAT. By default, `pat` will be obtained via `gh_pat()`, which consults your environment variables (by default, `GITHUB_PAT` and `GITHUB_TOKEN`, in that order).
`rstudio`	Logical indicating whether to ensure repo directory is also an RStudio Project
`...`	Other parameters passed to the GitHub API when creating the new repository, optional. Read more at https://developer.github.com/v3/repos/#create. For example, by passing `private = TRUE`, you can create a new private repository, if your GitHub account is eligible.

This requires a free GitHub account, which can be registered at https://github.com. There is some additional setup that gives githug the ability to deal with GitHub on your behalf:

GitHub personal access token: The only way to create a GitHub repository is through the API, so you must obtain a personal access token (PAT). For advice on how to store your PAT, see gh_pat().
GitHub username: githug_init() uses your PAT to lookup your GitHub username. This information, and much more, is stored in custom Git variables for downstream use. The GitHub username is stored under githug.username and can be configured globally, i.e. at the user level, or locally, i.e. at the repo level (the default and automatic behavior of githug_init()). To set or modify githug.username manually, use git_config_global(githug.username = <YOUR-GITHUB-USERNAME>) or git_config_local(githug.username = <YOUR-GITHUB-USERNAME>).

At the moment, githug_init() is designed only to create a new GitHub repo, though that should change. Currently, the function just stops if it detects evidence of a pre-existing remote/GitHub setup. Temporary workarounds:

If the local repo is valuable and the GitHub remote is expendable, delete the GitHub repo. For now, do that in the browser. Also delete the origin remote from the local repository, via git2r::remote_remove(as_git_repository(), "origin") in R or git remote rm origin in the shell. And call githug_init() again.
If the GitHub repo is valuable and the local repo is expendable, delete local. And use 'git clone' or RStudio to clone the GitHub repo.
If both are valuable, githug can't help you yet.

Credentials. Most people (?) should not need to use cred unless they want to. For "https" users, githug_init uses your PAT to push. For "ssh" users, it is assumed that public and private keys are in the default locations, ~/.ssh/id_rsa.pub and ~/.ssh/id_rsa, respectively, and that ssh-agent is configured to manage any associated passphrase. If you want to specify credentials explicitly, see cred_ssh_key, cred_user_pass, cred_env, and cred_token.

Path to the local repository.

## Not run: 
## Example 1:
## create a directory and local repo and RStudio project and remote repo, all
at once
## TO DO: remove private = TRUE maybe

githug_init(path = tempfile("init-test-"), private = TRUE)

## End(Not run)

## Not run: 
## Example 2:
## connect a pre-existing Git repo to GitHub
repo <- git_init(tempfile("githug-init-example-"))

## switch working directory to the repo
owd <- setwd(repo)

## Config local git user and make a commit
git_config(user.name = "thelma", user.email = "thelma@example.org")
writeLines("I don't ever remember feeling this awake.", "thelma.txt")
git_COMMIT("thelma is awake")
git_log()

## Connect it to GitHub! Visit the new repo in the browser.
## TO DO: remove private = TRUE maybe
githug_init(private = TRUE)

## see that the 'origin' is now set to the GitHub remote
## TO DO: revise this when remote stuff done
git2r::remotes()
git2r::remote_url(as_git_repository())

## see that local master is tracking remote master
git2r::branch_get_upstream(git_HEAD()$git_branch)

setwd(owd)

## End(Not run)

## Not run: 
## Example 3:
## Turn an existing directory into a Git repo to and connect to GitHub
repo <- tempfile("githug-init-example-")
dir.create(repo)
owd <- setwd(repo)
## TO DO:remove private = TRUE maybe
githug_init(private = TRUE)
setwd(owd)

## End(Not run)