Freshen "Existing project, GitHub first"

usage-existing-project-github-first.Rmd

@@ -2,8 +2,11 @@
 
 This is a novice-friendly workflow for bringing an existing R project into the RStudio and Git/GitHub universe.
 
-We do this in a slightly awkward way, in order to avoid using Git at the command line.
+We do this in a slightly goofy way, in order to avoid using Git at the command line.
 You won't want to work this way forever, but it's perfectly fine as you're getting started!
+At first, the main goal is to accumulate some experience and momentum.
+There is nothing goofy about the GitHub repo that this creates, it is completely standard.
+Transition to a more elegant process when you're ready.
 
 We assume you've got your existing R project isolated in a directory on your computer.
 If that's not already true, make it so.
@@ -31,19 +34,27 @@ 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.
-  * 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
+* *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.
+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
+```
 
 ## Bring your existing project over
 
@@ -59,36 +70,42 @@ In RStudio, consult the Git pane and the file browser.
 Commit your files to this repo. How?
 
   * Click the "Git" tab in upper right pane
-  * Check "Staged" box for all files you want to commit.
+  * Check the "Staged" box for all files that you want to commit.
     - Default: stage it.
-    - When to reconsider: this will all go to GitHub. So do 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".
+  * Type a message in "Commit message", such as "Init project XYZ".
   * Click "Commit"
 
 ## Push your local changes to GitHub
 
-Click the green "Push" button to send your local changes to GitHub. You should see some message along these lines.
+Click the green "Push" button to send your local changes to GitHub.
+RStudio will display something like:
 
-``` bash
-[master dc671f0] blah
- 3 files changed, 22 insertions(+)
- create mode 100644 .gitignore
- create mode 100644 myrepo.Rproj
+```console
+>>> /usr/bin/git push origin HEAD:refs/heads/main
+To https://github.com/jennybc/myrepo.git
+   3a2171f..6d58539  HEAD -> main
 ```
 
 ## Confirm the local change propagated to the GitHub remote
 
-Go back to the browser. I assume we're still viewing your new GitHub repo.
+Go back to the browser.
+I assume we're still viewing your new GitHub repo.
 
 Refresh.
 
 You should see all the project files you committed there.
 
-If you click on "commits," you should see one with the message "init".
+If you click on "commits," you should see one with the message you used, e.g. "Init project XYZ".
 
 ## The end
 
-Now just ... repeat. Do work somewhere. Commit it. Push it or pull it\* depending on where you did it, but get local and remote "synced up". Repeat.
+Now just "lather, rinse, repeat".
+Do work somewhere: locally or on GitHub.
+Commit it.
+Push it or pull it, depending on where you did the work, but get local and remote "synced up".
+Repeat.
 
-\* Note that in general (and especially in future when collaborating with other developers) you will usually need to pull changes from the remote (GitHub) before pushing the local changes you have made. For this reason, it's a good idea to try and get into the habit of pulling before you attempt to push.
+Note that in general (and especially in future when collaborating with other developers) you will usually need to pull changes from the remote (GitHub) before pushing the local changes you have made.
+For this reason, it's a good idea to try and get into the habit of pulling before you attempt to push.