Review git section

_episodes/07-github.md

@@ -3,15 +3,15 @@ title: "Version control with git and Github"
 teaching: 45
 exercises: 45
 questions:
-- "What is version control? How do I use it?"
-- "What is the difference between `git`and Github?"
 - "What benefits does a version control system brings in for my research?"
+- "What is version control?" "How do I use version control?"
+- "What is the difference between `git`and Github?"
 objectives:
 - "Understand the benefits of using a version control system such as `git`."
-- "Understand the basics of `git` and its usage in RStudio."    
+- "Understand the basics of `git` and its usage in RStudio."
 keypoints:
-- "`git` and Github allow you to version control files and go back in time if needed."
-- "In a version control system, file names do not reflect their versions."
+- "`git` and Github allow you to keep track of your files and go back in time if needed."
+- "In a version control system, file names do not reflect their versions. The history is managed by the version control system."
 - "An RStudio project folder can be fully version controlled and synchronized online with Github."
 - "Working locally in RStudio with a synchronised online folder will make your work more stable and understandable for you and others."
 ---
@@ -32,35 +32,37 @@ keypoints:
 * Ends (or, nearly ends) the horror of keeping track of versions.
   Basically, we get away from this:
 
-![](../img/MessySaves.png)
+  ![](../img/MessySaves.png)
 
-![](../img/phdcomics_version_control.png)
+  ![](../img/phdcomics_version_control.png)
 
-When you open your repository, you only see the most recent version.  But, it easy to compare versions, and you can easily revert to previous versions.
+  When you open your project folder, you only see the most recent version.  But you keep the ability to compare versions and you can revert to previous versions.
 
 * Improves collaborative efforts.  Different researchers can work on the same files at the same time!
 * It is easy to share and distribute files through the Github website.
-* Your files are available anywhere, you just need internet connection!  
+* Your files are available anywhere, you just need internet connection.
 
 ### git and Github
 
-We will learn about version control using `git` and [GitHub](https://en.wikipedia.org/wiki/GitHub), and we will interface with this through RStudio. This will change your scientific life (for the better!). Github was developed for social coding (i.e., sort of like an open source Wikipedia for programmers). Consequently, much of the functionality and terminology of Github (e.g., branches and pull requests) will not be relevant for most scientists. Therefore, we will skip over all this stuff!    
+We will learn about version control using `git` and [GitHub](https://en.wikipedia.org/wiki/GitHub), and we will interface with this through RStudio. This will change your scientific life (for the better!). Github was developed for social coding (i.e., sort of like an open source Wikipedia for programmers). Consequently, much of the functionality and terminology of Github (e.g., branches and pull requests) will not be relevant for most scientists. Therefore, we will skip over all this stuff!
 
-Github will facilitate your daily coding life when working with your most important collaborator: **you** ! A famous quote that we like to emphasize:
-> Your past self from 6 months ago is gone and won't answer emails from your present self!  
+Version control will facilitate your daily coding life when working with your most important collaborator: **you** ! A famous quote that we like to emphasize:
+> Your past self from 6 months ago is gone and won't answer emails from your present self!
 
-**git:**   
-The version control program `git` will track and version your files locally on your machine. `git` is locally executed and works on your local machine. It was named created and named by *Linus Torvalds*, the creator of Linux. Torvalds sarcastically quipped about the name _git_ (which means unpleasant person in British English slang): "I'm an egotistical bastard, and I name all my projects after myself. First 'Linux', now 'git'."
+**git:**
+The version control program `git` will track and version your files locally on your machine. `git` is locally executed and works on your local machine. It was created and named by *Linus Torvalds*, the creator of Linux. Torvalds sarcastically quipped about the name _git_ (which means unpleasant person in British English slang): "I'm an egotistical bastard, and I name all my projects after myself. First 'Linux', now 'git'."
 
 `git` is a version control system that lets you track changes to files over time. These files can be any kind of file (e.g. .doc, .pdf, .xls), but free text differences are visible and can be read by humans (eg txt, csv, md).
 
-**Github:**  
+**Github:**
 [GitHub](https://github.com/) is a website for storing your git versioned files remotely. It has many nice features to be able visualize differences between [images](https://help.github.com/articles/rendering-and-diffing-images/), [rendering](https://help.github.com/articles/mapping-geojson-files-on-github/) & [diffing](https://github.com/blog/1772-diffable-more-customizable-maps) map data files, [render text data files](https://help.github.com/articles/rendering-csv-and-tsv-data/), and [track changes in text](https://help.github.com/articles/rendering-differences-in-prose-documents/).
 
-> If you are a student you can get the micro account which includes 5 private repositories for free (normally a $7/month value).  You can sign up for the student account [here](https://education.github.com/pack).  Instructors can also request a free organization [account, "Request a discount"](https://education.github.com/). These concepts are more important for coders who want the entire coding community (and not just people working on the same project) to be able to suggest changes to their code.  This isn't how most scientists will use Github. To get the full functionality of Github, you will eventually want to learn other concepts. But, this can wait.  
+> If you are a student you can get the micro account which includes 5 private repositories for free (normally a $7/month value).  You can sign up for the student account [here](https://education.github.com/pack).  Instructors can also request a free organization [account, "Request a discount"](https://education.github.com/). These concepts are more important for coders who want the entire coding community (and not just people working on the same project) to be able to suggest changes to their code.  This isn't how most scientists will use Github. To get the full functionality of Github, you will eventually want to learn other concepts. But, this can wait.
+
+**git and Github**:
+Although `git` and GitHub are two different things, distinct from each other, think of them as a bundle since you typically use them together.
 
-**git and Github**:  
-Although `git` and GitHub are two different things, distinct from each other, I think of them as a bundle since I always use them together. It also helped me to think of GitHub like Dropbox: you make folders that are 'tracked' and can be synced to the cloud. GitHub does this too, but you have to be more deliberate about when syncs are made. This is because GitHub saves these as different versions, with information about who contributed when, line-by-line. This makes collaboration easier, and it allows you to roll-back to different versions or contribute to others' work.
+It helps to think of GitHub like Dropbox: you make folders that are 'tracked' and can be synced to the cloud. GitHub does this too, but you have to be more deliberate about when syncs are made. This is because GitHub saves these as different versions, with information about who contributed when, line-by-line. This makes collaboration easier, and it allows you to roll-back to different versions or contribute to others' work.
 
 <figure>
     <img src="../img/octocat_GitHub_mascot.png" alt='Github Mascot' width="250" />
@@ -78,32 +80,31 @@ These materials borrow from:
 - Melanie Frazier's [GitHub Quickstart](https://rawgit.com/nazrug/Quickstart/master/GithubQuickstart.html)
 - Ben Best's [Software Carpentry at UCSB](http://remi-daigle.github.io/2016-04-15-UCSB/git/)
 
-Today, we'll only introduce the features and terminology that scientists need to learn to begin managing their projects.
+Today, we'll focus on the features and terminology that scientists need to start managing their projects.
 
 ## Outline
 
-Today, we'll interface with GitHub from our local computers using RStudio. There are many other ways to interact with GitHub, including GitHub's Desktop App or the command line ([here is Jenny Bryan's list of git clients](http://stat545.com/git02_git-clients.html)), but today we are going to work from RStudio. You have the largest suite of options if you interface through the command line, but the most common things you'll do can be done through one of these other applications (i.e. RStudio and the GitHub Desktop App).
+Today, we'll interface with GitHub from our local computer using RStudio. There are many other ways to interact with GitHub, including GitHub's Desktop App or the command line ([here is Jenny Bryan's list of git clients](http://stat545.com/git02_git-clients.html)), but today we are going to work from RStudio. You have the largest suite of options if you interface through the command line, but the most common things you'll do can be done through one of these other applications (i.e. RStudio and the GitHub Desktop App).
 
-Here's what we'll do after we set up `git` on your computers:
+What we will do after we set up `git` on your computer:
 
-1. create a repository on Github.com
-2. clone locally using RStudio.
-3. learn the RStudio-GitHub workflow by syncing to Github.com: `pull`, `stage`, `commit`, `push`.
-4. explore github.com: files, commit history, file history.
+1. create a repository on [github.com](https://github.com/).
+2. clone locally using [RStudio](https://rstudio.com/).
+3. learn the RStudio-GitHub workflow by syncing to [github.com](https://github.com/) using the git verbs `pull`, `stage`, `commit`, `push`.
+4. explore [github.com](https://github.com/): files, commit history, file history.
 5. practice the RStudio-GitHub workflow by editing and adding files.
 6. practice R Markdown.
 
-
 ### Some Github terminology
 
 * **User**: A Github account for you (e.g., jules32).
 * **Organization**: The Github account for one or more user (e.g., datacarpentry).
 * **Repository**: A folder within the organization that includes files dedicated to a project.
 * **Local Github**: Copies of Github files located your computer.
-* **Remote Github**: Github files located on the https://github.com website.
+* **Remote Github**: Github files located on the [https://github.com/](https://github.com/) website.
 * **Clone**: Process of making a local copy of a remote Github repository.  This only needs to be done once (unless you mess up your local copy).
 * **Pull**: Copy changes on the remote Github repository to your local Github repository.  This is useful if multiple people are making changes to a repository.
-* **Push**: Save local changes to remote Github
+* **Push**: Save local changes to Github.
 <br />
 <br />
 
@@ -123,10 +124,10 @@ We're going to switch gears from R for a moment and set up Git and GitHub, which
         # display your version of git
         git --version
 
-        # replace USER with your Github user account
+        # replace YOUR_USER_NAME with your Github user account
         git config --global user.name YOUR_USER_NAME
 
-        # replace NAME@EMAIL.EDU with the email you used to register with Github
+        # replace YOUR_NAME@@EMAIL.UNIVERSITY with the email you used to register on Github
         git config --global user.email YOUR_NAME@@EMAIL.UNIVERSITY
 
         # list your config to confirm user.* variables set
@@ -165,7 +166,7 @@ which git
 
 Look at the filepath that is returned. Does it say anything to do with Apple?
 
--> If yes, then the [Git you downloaded](https://git-scm.com/downloads) isn't installed, please redownload if necessary, and follow instructions to install.  
+-> If yes, then the [Git you downloaded](https://git-scm.com/downloads) isn't installed, please redownload if necessary, and follow instructions to install.
 
 -> If no, (in the example image, the filepath does not say anything with Apple) then proceed below:
 
@@ -183,13 +184,13 @@ Does the **“Git executable”** filepath match what the url in Terminal says?
 <img src="../img/git_options_filepath.png" width="500px">
 
 
-If not, click the browse button and navigate there.   
+If not, click the browse button and navigate there.
 
->*Note*: on my laptop, even though I navigated to /usr/local/bin/git, it then automatically redirect because /usr/local/bin/git was an alias on my computer. That is fine. Click OK.
+>*Note*: on my laptop, even though I navigated to `/usr/local/bin/git`, it then automatically redirect because `/usr/local/bin/git` was an alias on my computer. That is fine. Click OK.
 
-Quit RStudio.   
+Quit RStudio.
 
-Then relaunch RStudio.  
+Then relaunch RStudio.
 
 Try syncing or cloning, and if that works and then you don’t need to worry about typing into the Terminal, you’re all done!
 
@@ -202,28 +203,27 @@ First, go to your account on github.com and click "New repository".
 <img src="../img/create_repository.png" width="900px">
 
 
-Name it `my-repo`, short for "my-repository" (any short self-describing name would be good).   
+Name it `my-repo`, short for "my-repository" (any short self-describing name would be good).
 
 Also, add a description, make it public, create a README file, and create your repo!
 
 <img src="../img/create_repository_2.png" width="900px">
 
 The *Add gitignore* option adds a document where you can identify files or file-types you want Github to ignore. These files will stay in on the local `git` folder (the one on your computer), but will not be uploaded onto the web version of Github.
 
-The *Add a license* option adds a license that describes how other people can use your Github files (e.g., open source, but no one can profit from them, etc.).  We won't worry about this today.
+The *Add a license* option adds a license that describes how other people can use your Github files (e.g., open source, but no one can profit from them, etc.). We won't worry about this today.
 
-Check out our new repository!  
+Check out your new repository!
 
-Notice how the README.md file we created is automatically displayed at the bottom. The .md means that it is Markdown (remember how .Rmd was RMarkdown?) so the formatting we learned in the last lesson apply here.
+Notice how the `README.md` file we created is automatically displayed at the bottom. The `.md` means that it is Markdown (remember how `.Rmd` was RMarkdown?) so the formatting we learned in the last lesson apply here as well.
 
 <img src="../img/New_repository.png" width="900px">
 
 **From here, you will work locally (on your computer).**
 
-
 ## Clone your repository using RStudio
 
-We'll start of by cloning to our local computer using RStudio. We are going to be cloning a copy of our remote repository on Github.com to our local computers. Unlike downloading, cloning keeps all the version control and user information bundled with the files.
+To get the project repository as a folder on your local computer, you need to `clone` it to your local computer. Using RStudio, you are going to `clone` the remote repository on [github.com/](https://github.com/) to your local computer. Unlike downloading, cloning keeps all the version control and user information bundled with the files.
 
 ### Step 0: Create your `github` folder
 
@@ -257,7 +257,7 @@ So really. Make sure that you have an all-lowercase folder called `github` in yo
 
 ### Step 5: Paste it in the Repository URL field
 
-Type **tab** to autofill the Project Directory name. Make sure you keep the Project Directory Name **THE SAME** as the repository name from the URL.  
+Type the **TAB** keystroke to autofill the Project Directory name. Make sure you keep the Project Directory Name **THE SAME** as the repository name from the URL.
 
 Save it in your github folder (click on Browse) to do this.
 
@@ -267,20 +267,20 @@ If everything went well, the repository will be added to the list located here:
 
 <img src="../img/select_project.png" width="700px">
 
-And the repository will be saved to the Github folder on your computer:
+And the repository will be saved to the `github` folder on your computer:
 
 <img src="../img/cloned_repository.png" width="900px">
 
-<font size="+2">Ta da!!!</font> The folder doesn't contain much of interest, but we are going to change that.
+<font size="+2">Ta da!!!</font> The folder doesn't contain much, but we are going to change that.
 
 ## Inspect your repository
 
-Notice a few things in our repo here:
+Notice a few things in our Rstudio environment here:
 
-1. Our working directory is set to `~/github/my-repo`. This means that I can start working with the files I have in here without setting the filepath. This is that when we cloned this from RStudio, it created an RStudio project, which you can tell because:
-    - `.RProj` file, which you can see in the Files pane.
+1. The working directory is set to `~/github/my-repo`. This means that I can start working with the files I have in here without setting the filepath explicitly. When we cloned the repository from Github using RStudio, Rstudio created an RStudio project, which you can tell because:
+    - `.RProj` file, which you can see in the 'Files' pane.
     - The project is named in the top right hand corner
-1. We have a git tab! This is how we will interface directly to Github.com
+1. Rstudio adds a 'git' tab. This is how we will interface directly to [github.com/](https://github.com/).
 
 <img src="../img/RStudio_IDE_git.png" width="900px">
 
@@ -299,7 +299,7 @@ The repository will contain:
 And, I typically create the following:
 
 * a folder for my raw unmodified datasets named `data/`.
-* a folder for my figures named `figures/`. I have a subfolder for each figure (e.g. `figure1/`).  
+* a folder for my figures named `figures/`. I have a subfolder for each figure (e.g. `figure1/`).
 * a folder for my R scripts named....`Rscripts/`.
 
 I'm going to go to the Finder (Windows Explorer on a PC) and copy a file into my repository from there. And then I'm going to go back to RStudio -- it shows up in the git tab! So the repository is being tracked, no matter how you make changes to it (changes do not have to be done only through RStudio).
@@ -375,13 +375,13 @@ Let's also explore commit history, file history.
 > > * 6) Click on the **Commit** button and write a small descriptive message. It should be the end of the sentence: "with this commit, ...".
 > >
 > {: .solution}
-{: .challenge}  
+{: .challenge}
 
 Remember, `git` will track anything within that folder (the way Dropbox does), it's not specific to RStudio!
 
 ## How often should I commit?
 
-Whenever you make changes to the files in Github, you will walk through the Pull -> Stage -> Commit -> Push steps.
+Whenever you make changes to files in your project folder (i.e. repository), you will walk through the Pull -> Stage -> Commit -> Push steps.
 
 I tend to do this every time I finish a task (basically when I start getting nervous that I will lose my work).  Once something is committed, it is very difficult to lose it.