From 12fc4821c35d2a4e52d3893e2f6ffb87412d65d9 Mon Sep 17 00:00:00 2001 From: carriewright11 Date: Fri, 28 Apr 2023 17:55:05 -0400 Subject: [PATCH] small edits to github ch --- 08-github-workflow.Rmd | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/08-github-workflow.Rmd b/08-github-workflow.Rmd index 299a093..b16aa52 100644 --- a/08-github-workflow.Rmd +++ b/08-github-workflow.Rmd @@ -11,18 +11,18 @@ ottrpal::include_slide("https://docs.google.com/presentation/d/1MNHf8JpolaEP_vQ_ ## What is version control -Version control is system that allows you to track your files as you work on them. -Whether you've wrote a lot of code or written other documents, you've likely encountered the need for version control. As this comic from Piled Higher and Deeper describes, files can go through a lot of edits and revisions (this is true of code too)! And it doesn't take long for it to be difficult or even impossible to track the various revisions of even one file let alone dozens or hundreds of files that may be a part of a data science project. +Version control is system that allows you to track your files over time as you work on them. +Whether you've written a lot of code or written other documents, you've likely encountered the need for version control. As this comic from Piled Higher and Deeper describes, files can go through a lot of edits and revisions (this is true of code too)! And it doesn't take long for it to be difficult or even impossible to track the various revisions of even one file, let alone the dozens or hundreds of files that may be a part of a data science project. ```{r, fig.align='center', out.width="100%", echo = FALSE, fig.alt= "The comic from Piled Higher and Deeper PhdComics.com is titled FINAL.doc. The student takes a paper to the professor who edits it and now calls it FINAL_rev2.doc. After another round of revisions, its now called FINAL_rev6.COMMENTS.doc, and then FINAL_rev.8.comments5.CORRECTIONS.doc, then FINAL_rev18.comments7.corrections9.MORE.30.doc, then FINAL_rev.22.comments49.corrections.10#%WHYDIDICOMETOGRADSCHOOL????.doc"} ottrpal::include_slide("https://docs.google.com/presentation/d/1MNHf8JpolaEP_vQ_kB-1xRBF9wo3haCArRu117hBoHA/edit#slide=id.g2282797b55b_0_0") ``` -This problem is what git, a version control system can address. It is a system that allows you to track your files, keep a history of them and otherwise handle changes through the history of your project. +This problem is what Git, a version control system, can address. It is a system that allows you to track your files, keep a history of them, and otherwise handle changes through the history of your project. ## What's GitHub? -The most common way git is used is in conjunction with an online platform called GitHub. +Git is most commonly used is in conjunction with an online platform called GitHub. [GitHub](https://github.com/) is an online platform for sharing code.
@@ -30,7 +30,7 @@ The most common way git is used is in conjunction with an online platform called - **GitHub** an online platform for sharing code in a version controlled manner.
-It aids reproducibility by being online in a way that is easily shareable to others in a version controlled way. GitHub allows anyone at anytime to take a look at and obtain your code. +GitHub aids reproducibility by being online in a way that easily makes code shareable to others in a version controlled way. GitHub allows anyone at anytime to take a look at and obtain your code. ```{r, fig.align='center', out.width="100%", echo = FALSE, fig.alt= "Reproducible parrot has shared their analysis on GitHub allowing their fellow parrot friend to observe and learn from the code and results! Reproducible parrot’s friend says ‘This analysis is great and really helps inform the field! Glad it was shared on GitHub!’"} ottrpal::include_slide("https://docs.google.com/presentation/d/1MNHf8JpolaEP_vQ_kB-1xRBF9wo3haCArRu117hBoHA/edit#slide=id.g201bd406763_37_415") @@ -42,13 +42,13 @@ Because code on GitHub is version controlled, it allows you to track your code a ottrpal::include_slide("https://docs.google.com/presentation/d/1MNHf8JpolaEP_vQ_kB-1xRBF9wo3haCArRu117hBoHA/edit#slide=id.g201bd406763_37_488") ``` -GitHub and its version control also allows you to be able to take the side journeys that often pop up with data science projects but in a way that allows you to ensure that the main files stay safe as you experiment. +GitHub and Git also allow you to take the side journeys that often pop up with data science projects, but in a way that allows you to ensure that the main files stay safe as you experiment. ```{r, fig.align='center', out.width="100%", echo = FALSE, fig.alt= "Reproducible parrot says ‘I’m interested in writing some code to experiment with something in the data, but I’m not sure if I’ll be keep this or not. Good thing version control allows me to track this in a way that doesn’t interfere with my main, polished analysis!’ On the side of the image shows a branching off of the main code base that says ‘test analysis’ This test analysis can be later merged with the main analysis if needed or it can be kept tracked but not added to the main analysis."} ottrpal::include_slide("https://docs.google.com/presentation/d/1MNHf8JpolaEP_vQ_kB-1xRBF9wo3haCArRu117hBoHA/edit#slide=id.g201bd406763_37_459") ``` -GitHub is also handy for collaborating with others on your code, not only because it is online, but the version controlled nature of it, allows you and any team members to work on the same files simultaneously without fear that the changes will be impossible to merge together. Git and GitHub have systems to do just this. +GitHub is also handy for collaborating with others on your code, not only because it is online, but the version controlled nature of it allows you and any team members to work on the same files simultaneously without fear that the changes will be impossible to merge together. Git and GitHub have systems to do just this. ```{r, fig.align='center', out.width="100%", echo = FALSE, fig.alt= "Github and git allow you to collaborate with others on the same files in a way that has a system for merging all the work together. In this diagram it shows how one set of changes labeled in yellow can be merged in with another set of changes labeled in blue. Reproducible parrot is happy and says ‘GitHub and git make it easy for us to collaborate with each other in a way that we can merge our work together!’ His parrot collaborator is also happy."} ottrpal::include_slide("https://docs.google.com/presentation/d/1MNHf8JpolaEP_vQ_kB-1xRBF9wo3haCArRu117hBoHA/edit#slide=id.g201bd406763_37_503") @@ -62,7 +62,7 @@ Git can feel overwhelming to a lot of folks and it has a really deep and complic ottrpal::include_slide("https://docs.google.com/presentation/d/1MNHf8JpolaEP_vQ_kB-1xRBF9wo3haCArRu117hBoHA/edit#slide=id.g2282797b55b_0_7") ``` -One reason that git and GitHub can feel overwhelming to folks is that there are a number of terms that are used to describe the different commands. We will walk through the typical workflow steps, and define these terms as we use them. +One reason that Git and GitHub can feel overwhelming to folks is that there are a number of terms that are used to describe the different commands. We will walk through the typical workflow steps, and define these terms as we use them. ```{r, fig.align='center', out.width="100%", echo = FALSE, fig.alt= "There are so many git terms it can be difficult to keep track of them all! A computer with the GitHub cat symbol has question marks above it with the terms: pull, add, clone, branch, remote, commit, and push around it. "} ottrpal::include_slide("https://docs.google.com/presentation/d/1MNHf8JpolaEP_vQ_kB-1xRBF9wo3haCArRu117hBoHA/edit#slide=id.g201bd406763_37_5") @@ -84,7 +84,7 @@ On this new repository page, you will want to create a description that summariz Also choose the "Add a README file" option because every project should have a README. -For the `Add .gitignore` option, it would be handy to choose the `R` gitignore template. [gitignore files are handy](https://git-scm.com/docs/gitignore#:~:text=A%20gitignore%20file%20specifies%20intentionally,gitignore%20file%20specifies%20a%20pattern.). They are a way to tell GitHub that you don't want a particular file tracked. It's just important for us to track the important files as it is for us to declutter our project by not adding unnecessary files. +For the `Add .gitignore` option, it would be handy to choose the `R` gitignore template. These [gitignore files are handy](https://git-scm.com/docs/gitignore#:~:text=A%20gitignore%20file%20specifies%20intentionally,gitignore%20file%20specifies%20a%20pattern.). They are a way to tell GitHub that you don't want a particular file tracked. It's just important for us to track the important files as it is for us to declutter our project by not adding unnecessary files. You may want to choose a license. We recommend choosing something that allows others to freely use your code but with attribution like a Creative Commons license. @@ -128,7 +128,7 @@ This will open up a page in GitHub for creating a `New personal access token`. Underneath the `Note` put something that reminds you what this PAT is for. Something like `RStudioCloud Access`. (Note that each PAT you make needs its own unique `Note` though). -Underneath the `Select scopes` section **you don't need to do anything**, `usethis` package already chose the permissions we need. +Underneath the `Select scopes` section **you don't need to do anything**. The `usethis` package already chose the permissions we need. Scroll all the way down on this page and click `Generate Token`. You've created your first PAT! **Do not close this window**, keep it handy for now. Note that in the image below we blocked out our PAT, but yours will show a jumble of letters and numbers @@ -160,7 +160,7 @@ After you enter your PAT here you should get a message like: You are now free to close that GitHub PAT window. Note that you will want to be very careful with your PAT. **Do not share it or put it anywhere that others could see it or access it!** 7. Now we also need to add your username and email to the RStudio GitHub credentials by running a command like below. -But replace the example **username** and **email** with what corresponds to your GitHub account. +Be sure to replace the example **username** and **email** with what corresponds to your GitHub account. ``` use_git_config(user.name = "Jane", user.email = "jane@example.org") @@ -220,7 +220,7 @@ Yay! Now you should be able to use GitHub from RStudio! ### Cloning your repository -In git, to `clone` something is to get a copy of your project to your computer to work from. +In Git, to `clone` something means to get a copy of your project onto your computer to work on.
- **clone** - making a copy of a code base on your computer. @@ -281,7 +281,7 @@ Now that you have created a branch, you are ready to make changes to your files. Now make any change to a file for the purposes of this tutorial. For example, you could add a sentence to your README file to explain what this project will be. Then save the file change. -In RStudio, if we go to the `Git` tab we should see that the file we changed has an `M` next to it to signify it has been modified. In order to officially add these changes that we've made to our branch, we need to `commit` them. +In RStudio, if we go to the `Git` tab (typically located in the lower right pane) we should see that the file we changed has an `M` next to it to signify it has been modified. In order to officially add these changes that we've made to our branch, we need to `commit` them.
- **commit** - the action of officially adding a file change to a branch. @@ -293,7 +293,7 @@ To do this, we first need to check the box(es) next to the files we'd like to co ottrpal::include_slide("https://docs.google.com/presentation/d/1MNHf8JpolaEP_vQ_kB-1xRBF9wo3haCArRu117hBoHA/edit#slide=id.g2288a8ec77f_0_150") ``` -After clicking the commit button, a new window will pop up that shows us the changes we are committing. In this window, we will need to add a commit message. Again, we should try to write something informative about what we were doing to these files we are committing. Then after we've written this commit message, we need to click `Commit` in this window. +After clicking the commit button, a new window will pop up that shows us the changes we are committing. Sections in green are new additions or modifications. Sections in red are the old sections that got changed or removed. In this window, we will need to add a commit message. Again, we should try to write something informative about what we were doing to these files we are committing. Then after we've written this commit message, we need to click `Commit` in this window. ```{r, fig.align='center', echo = FALSE, fig.alt= "After you click ‘Commit’ a new window should pop up. Green lines indicate added bits while red indicate things that were deleted. We’ll write an informative commit message about the changes we are adding and then click ‘Commit’ again. "}