edited version control PAT

Author: trevorcampbell

version-control.Rmd

@@ -484,37 +484,39 @@ can be run by Jupyter on your local computer, or on a JupyterHub server.
 
 ### Generating a GitHub personal access token
 
-To send and retrieve work between your local computer 
-and the remote version control repository on GitHub,
-you will frequently need to perform authentication 
-to prove you have the permission to do this.
+To send and retrieve work between your local repository 
+and the remote repository on GitHub,
+you will frequently need to authenticate with GitHub 
+to prove you have the required permission.
 There are several methods to do this, 
 but for beginners we recommend using the HTTPS method 
-because it is easier to do and requires less setup.
+because it is easier and requires less setup.
 In order to use the HTTPS method, 
-GitHub requires the use of a personal access token 
-(PAT)\index{git!personal access token} 
-in place of a password because it is more secure.
+GitHub requires you to provide a *personal access token*. \index{GitHub!personal access token} 
+A personal access token is like a password—so keep it a secret!—but it gives
+you more fine-grained control over what parts of your account
+the token can be used to access, and lets you set an expiry date for the authentication.
 To generate a personal access token, 
-go to the Personal access tokens section of the Developer Settings page 
-(accessed via the Settings menu).
-This is accessible via: 
-[https://github.com/settings/tokens](https://github.com/settings/tokens).
+you must first visit [https://github.com/settings/tokens](https://github.com/settings/tokens),
+which will take you to the "Personal access tokens" page in your account settings.
 Once there, click "Generate new token" (Figure \@ref(fig:generate-pat-01)).
 Note that you may be asked to re-authenticate with your username 
 and password to proceed.
 
-(ref:generate-pat-01) The "Generate new token" button used to initiate the creation of a new personal access token. It is found on the Personal access tokens section of the Developer Settings page (accessed via the Settings menu).
+(ref:generate-pat-01) The "Generate new token" button used to initiate the creation of a new personal access token. It is found in the "Personal access tokens" section of the "Developer settings" page in your account settings.
 
 ```{r generate-pat-01, fig.cap = '(ref:generate-pat-01)', fig.retina = 2, out.width="100%"}
 image_read("img/generate-pat_01.png")
 ```
 
-Next you will be asked to add a note for your personal access token 
-(this should be a descriptor of what you are using it for) 
-and then select the scope of permission given to the token. 
-We recommend selecting only the "repo" to err on the side of higher security. 
-To generate the token, scroll to the bottom of that page 
+Next you will be asked to add a note for your personal access token. 
+This should be a descriptor of the token's purpose.
+Finally, you need to select permissions for the token; this is where
+you can control what parts of your account the token can be used to access.
+Make sure to choose only those permissions that you absolutely require. In
+Figure \@ref(fig:generate-pat-02), we tick only the "repo" box, which gives the 
+token access to our repositories (so that we can push and pull) but none of our other GitHub 
+account features. Finally, to generate the token, scroll to the bottom of that page 
 and click the green "Generate token" button (Figure \@ref(fig:generate-pat-02)).
 
 (ref:generate-pat-02) Webpage for creating a new personal access token.
@@ -524,24 +526,23 @@ image_read("img/generate-pat_02.png")
 ```
 
 Finally, you will be taken to a page where you will be able to see 
-and copy the personal access token you just generated. 
-You will only be able to see this once, 
-so make sure you store this in a safe place 
-that just you can access when you need to use it in the future 
-for authentication (Figure \@ref(fig:generate-pat-03)).
-For example, a password manager is an excellent place to securely store this, 
-and other, personal access tokens.
+and copy the personal access token you just generated (Figure \@ref(fig:generate-pat-03)). 
+Since it provides access to certain parts of your account, you should
+treat this token like a password; for example, you should consider 
+securely storing it using a password manager (and your other passwords and tokens, too!).
+Note that this page will only display the token to you once,
+so make sure you store it in a safe place right away. If you accidentally forget to
+store it, though, do not fret—you can delete that token by clicking the 
+"Delete" button next to your token, and generate a new one from scratch. 
+To learn more about GitHub authentication, 
+see the additional resources section at the end of this chapter.
 
 (ref:generate-pat-03) Display of the newly generated personal access token.
 
 ```{r generate-pat-03, fig.cap = '(ref:generate-pat-03)', fig.retina = 2, out.width="100%"}
 image_read("img/generate-pat_03.png")
 ```
 
-If you want to learn more about GitHub authentication, 
-we link to two excellent sources for this in our additional resources section 
-at the end of this chapter.
-
 ### Cloning a repository using Jupyter 
 
 The first step is to *clone* the \index{git!clone} remote repository on GitHub to create a local repository,
@@ -582,9 +583,9 @@ image_read("img/version_control/clone_04.png") %>%
 ```
 
 ### Specifying files to commit
-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 
+Now that you 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 you created and saved a new file (named `eda.ipynb`) that you 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), click the Jupyter Git extension 
@@ -598,8 +599,8 @@ This opens the Jupyter Git graphical user interface pane. Next,
 click the plus sign (+) beside the file(s) that you want to "add"  \index{git!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.
+However, next time you edit this file  and want to add the changes,
+you will find it under the "Changed" heading.
 
 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`.
@@ -613,9 +614,9 @@ image_read("img/version_control/git_add_02.png")
 ```
 
 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 
+flagging this file so that Git knows you want a snapshot of its current state 
 as a commit (Figure \@ref(fig:git-add-03)).
-Now we are ready to "commit" the changes. 
+Now you are ready to "commit" the changes. 
 Make sure to include a (clear and helpful!) message about what was changed
 so that your collaborators (and future you) know what happened in this commit. 
 
@@ -628,12 +629,12 @@ image_read("img/version_control/git_add_03.png")
 ### Making the commit
 
 To snapshot the changes with an associated commit message, 
-we put a message in the text box at the bottom of the Git pane 
+you must 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)). \index{git!commit}
 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 
+ event that you 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 
@@ -643,9 +644,9 @@ you use Git on.
 image_read("img/version_control/git_commit_01.png")
 ```
 
-After "committing" the file(s), you will see there are 0 "Staged" files 
-and we are now ready to push our changes
-to our remote repository on GitHub (Figure \@ref(fig:git-commit-03)).
+After "committing" the file(s), you will see there are 0 "Staged" files. 
+You are now ready to push your changes
+to the remote repository on GitHub (Figure \@ref(fig:git-commit-03)).
 
 ```{r git-commit-03, fig.cap = 'After recording a commit, the staging area should be empty.', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/git_commit_03.png")
@@ -654,7 +655,8 @@ image_read("img/version_control/git_commit_03.png")
 ### Pushing the commits to GitHub
 
 To send the committed changes back to the remote repository on 
-GitHub, we need to *push* them. \index{git!push} To do this we click on the cloud icon with the up arrow on the Jupyter Git tab 
+GitHub, you need to *push* them. \index{git!push} To do this, 
+click on the cloud icon with the up arrow on the Jupyter Git tab 
 (Figure \@ref(fig:git-push-01)).
 
 (ref:git-push-01) The Jupyter Git extension "push" button (circled in red).
@@ -663,23 +665,25 @@ GitHub, we need to *push* them. \index{git!push} To do this we click on the clou
 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)).
+You will then be prompted to enter your GitHub username 
+and password. Instead of your password, though, you will 
+need to enter the personal access token that you generated
+earlier. Click the blue "OK" button to initiate the push (Figure \@ref(fig:git-push-02)).
 
 ```{r git-push-02, fig.cap = 'Enter your Git credentials to authorize the push to the remote repository.', fig.retina = 2, out.width="100%"}
 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)).
+If the files were successfully pushed to the project repository on 
+GitHub, you will be shown a success message (Figure \@ref(fig:git-push-03)). 
+Click "Dismiss" to continue working in Jupyter.
 
 ```{r git-push-03, fig.cap = 'The prompt that the push was successful.', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/git_push_03.png")
 ```
 
 If you visit the remote repository on GitHub, 
-you will see that the changes now exist there via their web interface 
+you will see that the changes now exist there too
 (Figure \@ref(fig:git-push-04))!
 
 ```{r git-push-04, fig.cap = 'The GitHub web interface shows a preview of the commit message, and the time of the most recently pushed commit for each file.', fig.retina = 2, out.width="100%"}
@@ -817,7 +821,7 @@ image_read("img/version_control/merge_conflict_03.png") %>%
 
 ### Handling merge conflicts
 
-To fix the merge conflict, \index{git!merge conflict} we need to open the offending file
+To fix the merge conflict, \index{git!merge conflict} you need to open the offending file
 in a plain text editor and look for special marks that Git puts in the file to
 tell you where the merge conflict occurred (Figure \@ref(fig:merge-conflict-04)). 
 
@@ -929,5 +933,4 @@ you can expand your knowledge through the resources listed below:
 and [*Happy Git with R*](https://happygitwithr.com/) are great resources to take the next steps in learning about Git and GitHub.
 - [Good enough practices in scientific computing](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510#sec014) [-@wilson2014best] provides more advice on useful workflows and "good enough" practices in data analysis projects.
 - In addition to [GitHub](https://github.com), there are other popular Git repository hosting services such as [GitLab](https://gitlab.com) and  [BitBucket](https://bitbucket.org). Comparing all of these options is beyond the scope of this book, and until you become a more advanced user you are perfectly fine to just stick with GitHub. Just be aware that you have options!
-- If you need additional help generating and using a personal access token with GitHub,
-[GitHub's documentation on creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and the *Happy Git with R* [Cache credentials for HTTPS](https://happygitwithr.com/credential-caching.html) chapter are excellent additional resources for this.
+- [GitHub's documentation on creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and the *Happy Git with R* [cache credentials for HTTPS](https://happygitwithr.com/credential-caching.html) chapter are both excellent additional resources to consult if you need additional help generating and using personal access tokens.