diff --git a/child-clone-a-github-repo.Rmd b/child-clone-a-github-repo.Rmd new file mode 100644 index 0000000..071ded2 --- /dev/null +++ b/child-clone-a-github-repo.Rmd @@ -0,0 +1,70 @@ +```{r } +#| echo = FALSE, fig.align = "center", out.width = "100%", +#| fig.alt = "Clone a remote repo." +knitr::include_graphics("img/new-project-github-first.jpeg") +``` + +I present two ways to do this: + +* `usethis::create_from_github()` +* Via the RStudio IDE + +*(Recall that we showed how to do this with command line Git in chapter \@ref(push-pull-github).)* + +When you are cloning your own GitHub repository, the two methods are equivalent. +In other scenarios, especially fork-and-clone (chapter \@ref(fork-and-clone)), I think `usethis::create_from_github()` is superior, because it does additional, recommended setup. + +Pick **one** of these methods below. + +### `usethis::create_from_github()` + +You can execute these commands in any R session. +If you use RStudio, then do this in the R console of any RStudio instance. + +```{r eval = FALSE} +usethis::create_from_github( + "https://github.com/YOU/YOUR_REPO.git", + destdir = "~/path/to/where/you/want/the/local/repo/" +) +``` + +The first argument is `repo_spec` and it accepts the GitHub repo specification in various forms. +In particular, you can paste the URL we just copied from GitHub. + +The `destdir` argument specifies the parent directory where you want the new folder (and local Git repo) to live. +If you don't specify `destdir`, usethis defaults to some very conspicuous place, like your desktop. +If you like to keep Git repos in a certain folder on your computer, you can personalize this default by setting the `usethis.destdir` option in your `.Rprofile`. + +We're accepting the default behaviour of two other arguments, `rstudio` and `open`, because that's what most people will want. +For example, for an RStudio user, `create_from_github()` does this: + + * Creates a new local directory in `destdir`, which is all of these things: + - a directory or folder on your computer + - a Git repository, linked to a remote GitHub repository + - an RStudio Project + * Opens a new RStudio instance in the new Project + * **In the absence of other constraints, I suggest that all of your R projects have exactly this set-up.** + +### RStudio IDE + +In RStudio, start a new Project: + + * *File > New Project > Version Control > Git*. In the "repository URL" paste + the URL of your new GitHub repository. It will be something like this + `https://github.com/jennybc/myrepo.git`. + * Be intentional about where you create this Project. + * I suggest you "Open in new session". + * Click "Create Project" to create a new directory, which will be all of these things: + - a directory or "folder" on your computer + - a Git repository, linked to a remote GitHub repository + - an RStudio Project + * **In the absence of other constraints, I suggest that all of your R projects have exactly this set-up.** + +This should download the `README.md` file that we created on GitHub in the previous step. +Look in RStudio's file browser pane for the `README.md` file. + +Behind the scenes, RStudio has done this for you: + +```console +git clone https://github.com/jennybc/myrepo.git +``` diff --git a/usage-existing-project-github-first.Rmd b/usage-existing-project-github-first.Rmd index ede4c36..31cc109 100644 --- a/usage-existing-project-github-first.Rmd +++ b/usage-existing-project-github-first.Rmd @@ -35,26 +35,11 @@ res <- knitr::knit_child(text = insert, quiet = TRUE) cat(res, sep = '\n') ``` -## New RStudio Project via `git clone` +## New RStudio Project via git clone -In RStudio, start a new Project: - -* *File > New Project > Version Control > Git*. In the "repository URL" paste the URL of your new GitHub repository. It will be something like this `https://github.com/jennybc/myrepo.git`. -* Be intentional about where you create this Project. -* I suggest you "Open in new session". -* Click "Create Project" to create a new directory, which will be all of these things: - - a directory or "folder" on your computer - - a Git repository, linked to a remote GitHub repository - - an RStudio Project -* **In the absence of other constraints, I suggest that all of your R projects have exactly this set-up.** - -This should download the `README.md` file that we created on GitHub in the previous step. -Look in RStudio's file browser pane for the `README.md` file. - -Behind the scenes, RStudio has done this for you: - -```console -git clone https://github.com/jennybc/myrepo.git +```{r echo = FALSE, results = "asis"} +text <- readr::read_file("child-create-a-github-repo.Rmd") +cat(res, sep = '\n') ``` ## Bring your existing project over @@ -73,7 +58,11 @@ Commit your files to this repo. How? * Click the "Git" tab in upper right pane * Check the "Staged" box for all files that you want to commit. - Default: stage it. - - When to reconsider: this will all go to GitHub. Consider if that is appropriate for each file. **You can absolutely keep a file locally, without committing it to the Git repo and sending to GitHub**. Just let it sit there in your Git pane, without being staged. No harm will be done. If this is a long-term situation, list the file in `.gitignore`. + - When to reconsider: this will all go to GitHub. Consider if that is + appropriate for each file. **You can absolutely keep a file locally, + without committing it to the Git repo and sending to GitHub**. Just let it + sit there in your Git pane, without being staged. No harm will be done. If + this is a long-term situation, list the file in `.gitignore`. * If you're not already in the Git pop-up, click "Commit" * Type a message in "Commit message", such as "Init project XYZ". * Click "Commit" diff --git a/usage-new-project-github-first.Rmd b/usage-new-project-github-first.Rmd index a244479..ef8c593 100644 --- a/usage-new-project-github-first.Rmd +++ b/usage-new-project-github-first.Rmd @@ -63,64 +63,11 @@ Make sure you remove the `git clone ...` that shows up at the beginning. ## New RStudio Project via git clone {#new-rstudio-project-via-git} -```{r new-project-github-first, echo = FALSE, out.width = "100%", fig.cap = "Clone a remote repo."} -knitr::include_graphics("img/new-project-github-first.jpeg") -``` - -I present two ways to do this: - -* `usethis::create_from_github()` -* Via the RStudio IDE - -*(Recall that we showed how to do this with command line Git in chapter \@ref(push-pull-github).)* - -When you are cloning your own GitHub repository, the two methods are equivalent. -In other scenarios, especially fork-and-clone (chapter \@ref(fork-and-clone)), I think `usethis::create_from_github()` is superior, because it does additional, recommended setup. - -Pick **one** of these methods below. - -### `usethis::create_from_github()` - -You can execute these commands in any R session. -If you use RStudio, then do this in the R console of any RStudio instance. - -```{r eval = FALSE} -usethis::create_from_github( - "https://github.com/YOU/YOUR_REPO.git", - destdir = "~/path/to/where/you/want/the/local/repo/" -) +```{r echo = FALSE, results = "asis"} +text <- readr::read_file("child-create-a-github-repo.Rmd") +cat(res, sep = '\n') ``` -The first argument is `repo_spec` and it accepts the GitHub repo specification in various forms. -In particular, you can paste the URL we just copied from GitHub. - -The `destdir` argument specifies the parent directory where you want the new folder (and local Git repo) to live. -If you don't specify `destdir`, usethis defaults to some very conspicuous place, like your desktop. -If you like to keep Git repos in a certain folder on your computer, you can personalize this default by setting the `usethis.destdir` option in your `.Rprofile`. - -We're accepting the default behaviour of two other arguments, `rstudio` and `open`, because that's what most people will want. -For example, for an RStudio user, `create_from_github()` does this: - - * Creates a new local directory in `destdir`, which is all of these things: - - a directory or folder on your computer - - a Git repository, linked to a remote GitHub repository - - an RStudio Project - * Opens a new RStudio instance in the new Project - * **In the absence of other constraints, I suggest that all of your R projects have exactly this set-up.** - -### RStudio IDE - -In RStudio, start a new Project: - - * *File > New Project > Version Control > Git*. In the "repository URL" paste the URL of your new GitHub repository. It will be something like this `https://github.com/jennybc/myrepo.git`. - * Be intentional about where you create this Project. - * Suggest you "Open in new session". - * Click "Create Project" to create a new directory, which will be all of these things: - - a directory or "folder" on your computer - - a Git repository, linked to a remote GitHub repository - - an RStudio Project - * **In the absence of other constraints, I suggest that all of your R projects have exactly this set-up.** - ### Have a look around Regardless of whether you used usethis or RStudio, you should now be working in the new Git repo.