done polishing local repo working section

Author: trevorcampbell

version-control.Rmd

@@ -184,7 +184,7 @@ editing, and deleting files as you normally would—you must:
 
 In this section we will discuss all three of these steps in detail.
 
-### Commiting changes to a local repository 
+### Committing changes to a local repository {#commit-changes}
 
 When working on files in your local version control 
 repository (e.g., using Jupyter) and saving your work, these changes will only initially exist in the
@@ -282,10 +282,10 @@ image_read("img/vc7-pull.png") %>%
   image_crop("3632x2000")
 ```
 
-## Working with remote repositories on GitHub 
+## Working with remote repositories using GitHub 
 
 Now that you have been introduced to some of the key general concepts 
-and workflows of Git version control, we will next walk through the practical steps. 
+and workflows of Git version control, we will walk through the practical steps. 
 There are several different ways to start using version control
 with a new project. For simplicity and ease of setup, 
 we recommend creating a remote repository first.
@@ -350,16 +350,16 @@ image_read("img/version_control/new_repository_03.png") %>%
 
 The pen tool can be used to edit existing plain text files. When you click on 
 the pen tool the file will be opened in a text box where you can use your 
-keyboard to make changes (Figure \@ref(fig:pen-tool-01) & \@ref(fig:pen-tool-02)).
+keyboard to make changes (Figures \@ref(fig:pen-tool-01) and \@ref(fig:pen-tool-02)).
 
-```{r pen-tool-01, fig.cap = 'Clicking on the pen tool opens a textbox for editing plain text files.', fig.retina = 2}
+```{r pen-tool-01, fig.cap = 'Clicking on the pen tool opens a text box for editing plain text files.', fig.retina = 2}
 image_read("img/version_control/pen-tool_01.png") %>%
   image_flop() %>%
   image_crop("3584x1500") %>%
   image_flop()
 ```
 
-```{r pen-tool-02, fig.cap = 'The textbox where edits can be made after clicking on the pen tool.', fig.retina = 2}
+```{r pen-tool-02, fig.cap = 'The text box where edits can be made after clicking on the pen tool.', fig.retina = 2}
 image_read("img/version_control/pen-tool_02.png") %>%
   # image_flop() %>%
   image_crop("3584x1300") # %>%
@@ -374,6 +374,17 @@ generates a useful version history for that file. On GitHub, if you click the
 green "Commit changes" button, it will save the file and then make a commit
 (Figure \@ref(fig:pen-tool-03)).
 
+Recall from Section \@ref(commit-changes) that you normally have to add files
+to the staging area before committing them. Why don't we have to do that when
+we work directly on GitHub? Behind the scenes, when you click the green "Commit changes"
+button, GitHub *is* adding that one file to the staging area prior to committing it.
+But note that on GitHub you are limited to committing changes to only one file at a time. 
+When you work in your own local repository, you can commit
+changes to multiple files simultaneously. This is especially useful when one
+"improvement" to the project involves modifying multiple files.
+You can also do things like run code when working in a local repository, which you cannot
+do on GitHub. In general, editing on GitHub is reserved for small edits to plain text files.
+
 ```{r pen-tool-03, fig.cap = 'Saving changes using the pen tool requires committing those changes, and an associated commit message.', fig.retina = 2}
 image_read("img/version_control/pen-tool_03.png") %>%
   image_crop("3583x1500+1+500")
@@ -403,7 +414,7 @@ Note that GitHub understands and renders `.md` files using a
 very similar to Jupyter notebooks, so the "Preview" tab is especially helpful 
 for checking markdown code correctness.
 
-```{r create-new-file-02, fig.cap = 'New plain text files require a filename be inputted in the textbox circled in red, and file content entered in the larger text box (red arrow).', fig.retina = 2}
+```{r create-new-file-02, fig.cap = 'New plain text files require a filename in the text box circled in red, and file content entered in the larger text box (red arrow).', fig.retina = 2}
 image_read("img/version_control/create-new-file_02.png") %>%
   image_flop() %>%
   image_crop("3584x1300") %>%
@@ -421,6 +432,11 @@ image_read("img/version_control/create-new-file_03.png") %>%
 You can also upload files that you have created on your local machine by using 
 the "Add file" drop down menu and selecting "Upload files"
 (Figure \@ref(fig:upload-files-01)).
+To select the files from your local computer to upload, you can either drag and 
+drop them into the grey box area shown below, or click the "choose your files" 
+link to access a file browser dialog. Once the files you want to upload have 
+been selected, click the green "Commit changes" button at the bottom of the 
+page (Figure \@ref(fig:upload-files-02)).
 
 ```{r upload-files-01, fig.cap = 'New files of any type can be uploaded to GitHub.', fig.retina = 2}
 image_read("img/version_control/upload-files_01.png") %>%
@@ -429,58 +445,48 @@ image_read("img/version_control/upload-files_01.png") %>%
   image_flop()
 ```
 
-To select the files from your local computer to upload, you can either drag and 
-drop them into the grey box area shown below, or click the "choose your files" 
-link to access a file browser dialog. Once the files you want to upload have 
-been selected, click the green "Commit changes" button at the bottom of the 
-page (Figure \@ref(fig:upload-files-02)).
-
-```{r upload-files-02, fig.cap = 'Uploaded files can specified by dragging them into the GitHub website where specified (red circle) or by clicking on the "choose your files" to select them via a file browser. Uploaded files are also required to be committed along with an associated commit message.', fig.retina = 2}
+```{r upload-files-02, fig.cap = 'Specify files to upload by dragging them into the GitHub website (red circle) or by clicking on "choose your files." Uploaded files are also required to be committed along with an associated commit message.', fig.retina = 2}
 image_read("img/version_control/upload-files_02.png") %>%
   image_flop() %>%
   image_crop("3584x2200") %>%
   image_flop()
 ```
 
 Note that Git and GitHub are designed to track changes in individual files. 
-*Do not* upload your whole project in an archive file (e.g. `.zip`). If you do,
-then Git can only keep track of changes to the entire `.zip` file---that 
-wouldn't be very useful if you're trying to see the history of changes to a 
-single code file in your project!
-
+**Do not** upload your whole project in an archive file (e.g. `.zip`). If you do,
+then Git can only keep track of changes to the entire `.zip` file, which will not
+be human-readable. Committing one big archive defeats the whole purpose of using
+version control: you won't be able to see, interpret, or find changes in the history
+of any of the actual content of your project!
 
 ## Working with local repositories using Jupyter {#local-repo-jupyter}
-
-### Cloning a repository using Jupyter 
-
-Although there are several ways to create and edit files on 
-GitHub, they are not quite powerful enough for 
-efficiently creating and editing complex files, or files that need to be 
-executed to assess whether they work (e.g., files containing code). 
-For example, 
-you wouldn't be able to run analysis written with R code directly on GitHub.
-Thus, it is useful to be able to connect the project repository 
-that was created on GitHub to a coding environment. 
-This can be done using the Git. 
-Git can be run via several different ways, 
-below we show how to do this using the Jupyter Git extension.
-The Jupyter Git extension can be run via Jupyter on your local computer, 
-or on a JupyterHub server. 
+Although there are several ways to create and edit files on GitHub, they are
+not quite powerful enough for efficiently creating and editing complex files,
+or files that need to be executed to assess whether they work (e.g., files
+containing code).  For example, you wouldn't be able to run analysis written
+with R code directly on GitHub.  Thus, it is useful to be able to connect the
+remote repository that was created on GitHub to a local coding environment.  This
+can be done by creating and working in a local copy of the repository.
+In this chapter, we focus on interacting with Git via Jupyter using
+the Jupyter Git extension. The Jupyter Git extension
+can be run via Jupyter on your local computer, or on a JupyterHub server. 
 *Note: we recommend reading Chapter \@ref(getting-started-with-jupyter)* 
 *to learn how to use Jupyter before reading this chapter.*
 
-We need to *clone* our project's Git repository to our local computer 
-or JupyterHub server---i.e., make a 
+### Cloning a repository using Jupyter 
+
+The first step is to *clone* the remote repository on GitHub to create a local repository,
+i.e., make a 
 copy that knows where it was obtained from so that it knows where send/receive 
 new committed edits. In order to do this, first copy the URL from the HTTPS tab 
 of the Code drop down menu on GitHub (Figure \@ref(fig:clone-02)).
 
-```{r clone-02, fig.cap = 'The remote address (URL) corresponding to the location of the GitHub repository needed to clone it to a computer can be found under the green "Code" button.', fig.retina = 2}
+```{r clone-02, fig.cap = 'The remote address (URL) corresponding to the location of the remote GitHub repository can be found in the green "Code" drop down menu.', fig.retina = 2}
 image_read("img/version_control/clone_02.png") %>%
   image_crop("3584x1500")
 ```
 
-Then open JupyterHub, and click the Git+ icon on the file browser tab 
+Then open Jupyter, and click the Git+ icon on the file browser tab 
 (Figure \@ref(fig:clone-01)).
 
 ```{r clone-01, fig.cap = 'The Jupyter Git Clone icon (red circle)', fig.retina = 2}
@@ -496,56 +502,44 @@ image_read("img/version_control/clone_03.png") %>%
   image_crop("2400x1430+1")
 ```
 
-On the file browser tab, you will now see a folder for your project's repository 
-(and inside it will be all the files that existed on GitHub, 
-Figure \@ref(fig:clone-04)).
+On the file browser tab, you will now see a folder for the repository.
+Inside this folder  will be all the files that existed on GitHub (Figure \@ref(fig:clone-04)).
 
 ```{r clone-04, fig.cap = 'Cloned GitHub repositories can been seen and accessed via the Jupyter file browser.', fig.retina = 2}
 image_read("img/version_control/clone_04.png") %>%
   image_crop("2400x1430+1")
 ```
 
-### Working in a cloned repository using Jupyter
-
-Now that you have cloned your repository from GitHub to your local computer
-(i.e., JupyterHub or your laptop), you can get to work editing, creating, 
-and deleting files using an application, such as Jupyter. 
-Below we walk through how to use the Jupyter Git extension tool to do 
-each of the steps outlined above.
-
 ### Specifying files to commit
-
-Below we created and saved a new file (named `eda.ipynb`) that we would 
-like to send back to the project repository on GitHub.
+Now that we have cloned the remote repository from GitHub to create a local repository,
+you can get to work editing, creating,  and deleting files. 
+For example, suppose we created and saved a new file (named `eda.ipynb`) that we would 
+like to send back to the project repository on GitHub (Figure \@ref(fig:git-add-01)).
 To "add" this modified file to the staging area (i.e., flag that this is a
-file whose changes we would like to commit), we click the Jupyter Git extension 
-icon on the far left-hand side of JupyterLab (Figure \@ref(fig:git-add-01)).
+file whose changes we would like to commit), click the Jupyter Git extension 
+icon on the far left-hand side of Jupyter (Figure \@ref(fig:git-add-01)).
 
 ```{r git-add-01, fig.cap = 'Jupyter Git extension icon (circled in red).', fig.retina = 2}
 image_read("img/version_control/git_add_01.png")
 ```
 
-This opens the Jupyter Git graphical user interface pane, and then we
-click the plus sign (+) beside the file that we want to "add" 
-(Figure \@ref(fig:git-add-02)). 
+This opens the Jupyter Git graphical user interface pane. Next,
+click the plus sign (+) beside the file(s) that you want to "add" 
+(Figure \@ref(fig:git-add-02)). Note that because this is the 
+first change for this file, it falls under the "Untracked" heading. 
+However, next time we edit this file  and want to add the changes,
+we will find it under the "Changed" heading.
 
-> **Note:** because this is the first change for this file that we want to add, 
-> it falls under the "Untracked" heading. 
-> However, next time we edit this file 
-> and want to add the changes we made, 
-> we will find it under the "Changed" heading.
-
-> **Note:** do not add the `eda-checkpoint.ipynb` file 
-> (sometimes called `.ipynb_checkpoints`). 
-> This file is automatically created by Jupyter when you work on `eda.ipynb`. 
-> You generally do not add auto-generated files to Git repositories,
-> only add the files you directly create and edit.
+You will also see an `eda-checkpoint.ipynb` file under the "Untracked" heading.
+This is a temporary "checkpoint file" created by Jupyter when you work on `eda.ipynb`.
+You generally do not want to add auto-generated files to Git repositories;
+only add the files you directly create and edit.
 
 ```{r git-add-02, fig.cap = 'The plus sign (+) is used to add the `eda.ipynb` file to the staging area.', fig.retina = 2}
 image_read("img/version_control/git_add_02.png")
 ```
 
-This moves the file from the "Untracked" heading to the "Staged" heading, 
+Clicking the plus sign (+) moves the file from the "Untracked" heading to the "Staged" heading, 
 flagging this file so that Git knows we want a snapshot of its current state 
 as a commit (Figure \@ref(fig:git-add-02)).
 Now we are ready to "commit" the changes. 
@@ -559,53 +553,51 @@ image_read("img/version_control/git_add_03.png")
 ### Making the commit
 
 To snapshot the changes with an associated commit message, 
-we put the message in the text box at the bottom of the Git pane 
+we put a message in the text box at the bottom of the Git pane 
 and click on the blue "Commit" button (Figure \@ref(fig:git-commit-01)). 
 It is highly recommended to write useful and meaningful messages about what 
 was changed. These commit messages, and the datetime stamp for a given 
 commit, are the primary means to navigate through the project's history in the 
  event that we need to view or retrieve a past version of a file, or 
 revert our project to an earlier state.
+When you click the "Commit" button for the first time, you will be prompted to 
+enter your name and email. This only needs to be done once for each machine 
+you use Git on.
 
 ```{r git-commit-01, fig.cap = 'A commit message must be added into the Jupyter Git extension commit text box before the blue Commit button can be used to record the commit.', fig.retina = 2}
 image_read("img/version_control/git_commit_01.png")
 ```
 
-> When you click the "Commit" button for the first time, you will be prompted to 
-> enter your name and email. This only needs to be done once for each machine 
-> you use Git on.
-
 After "committing" the file(s), you will see there there are 0 "Staged" files 
-and we are now ready to push our changes (and the attached commit message) 
-to our project repository on GitHub (Figure \@ref(fig:git-commit-01)).
+and we are now ready to push our changes
+to our remote repository on GitHub (Figure \@ref(fig:git-commit-01)).
 
 ```{r git-commit-03, fig.cap = 'After recording a commit, the staging area should be empty.', fig.retina = 2}
 image_read("img/version_control/git_commit_03.png")
 ```
 
 ### Pushing the commits to GitHub
 
-To send the committed changes back to the project repository on 
-GitHub, we need to *push* them. 
-To do this we click on the cloud icon with the up arrow on the Jupyter Git tab 
+To send the committed changes back to the remote repository on 
+GitHub, we need to *push* them.  To do this we click on the cloud icon with the up arrow on the Jupyter Git tab 
 (Figure \@ref(fig:git-push-01)).
 
-```{r git-push-01, fig.cap = 'The Jupyter Git extension push button (circled in red).', fig.retina = 2}
+```{r git-push-01, fig.cap = 'The Jupyter Git extension "push" button (circled in red).', fig.retina = 2}
 image_read("img/version_control/git_push_01.png")
 ```
 
 We will then be prompted to enter our GitHub username 
 and password, and click the blue "OK" button (Figure \@ref(fig:git-push-02)).
 
-```{r git-push-02, fig.cap = 'The Jupyter Git extension to enter Git credentials to authorize the push to the remote repository.', fig.retina = 2}
+```{r git-push-02, fig.cap = 'Enter your Git credentials to authorize the push to the remote repository.', fig.retina = 2}
 image_read("img/version_control/git_push_02.png")
 ```
 
 If the files were successfully pushed to our project repository on 
 GitHub we will be given the success message shown below. 
 Click "Dismiss" to continue working in Jupyter (Figure \@ref(fig:git-push-03)).
 
-```{r git-push-03, fig.cap = 'The Jupyter Git extension prompt that the push was successful.', fig.retina = 2}
+```{r git-push-03, fig.cap = 'The prompt that the push was successful.', fig.retina = 2}
 image_read("img/version_control/git_push_03.png")
 ```