updated github.md

pjbartlein · Feb 22, 2024 · 52bc5c4 · 52bc5c4
1 parent 3db776d
commit 52bc5c4
Show file tree

Hide file tree

Showing 3 changed files with 82 additions and 32 deletions.
diff --git a/docs/github.html b/docs/github.html
@@ -559,11 +559,11 @@ <h3><span class="header-section-number">2.2.1</span> Clone the
 <li>Browse to the folder: <code>/Users/Projects/</code> (but not
 <code>/Users/username/Projects/geog490project</code>)</li>
 <li>click on “Create Project”</li>
-<li>(Note that there is no connection between the folder names, the
-<code>/Projects</code> folder is just that, the
-<code>/geog490project</code> is named for the course project.)</li>
 </ul>
-<p>(note that <code>.gitignore</code>, <code>README.md</code> and
+<p>(Note that there is no connection between the folder names, the
+<code>/Projects</code> folder is just that, the
+<code>/geog490project</code> is named for the course project.)</p>
+<p>(Note that <code>.gitignore</code>, <code>README.md</code> and
 <code>geog490test.Rproj</code> files, and two folders <code>/.git</code>
 and <code>/Rproj.user</code> will have turned up in the working
 directory. You might not be able to see them if hidden files (that begin
@@ -574,12 +574,19 @@ <h3><span class="header-section-number">2.2.1</span> Clone the
 number="2.2.2">
 <h3><span class="header-section-number">2.2.2</span> Generate a Personal
 Access Token</h3>
+<p>See Section 9.1 of <a
+href="https://happygitwithr.com/index.html">[HappyGitWithR]</a>. There
+is a similar, but a bit more detailed discussion in the documentation
+for the <code>{usethis}</code> package at: <a
+href="https://usethis.r-lib.org/articles/git-credentials.html">[https://usethis.r-lib.org/articles/git-credentials.html]</a>
+(TL;DR = “Too long; didn’t read”!)</p>
 <p>Now, using RStudio, generate a personal access code (PAT):</p>
 <ul>
 <li><p>install the <code>{usethis}</code> package
-(install.packages(“usethis”);</p></li>
+(install.packages(“usethis”). (This will also install the
+<code>{gh}</code> and <code>{gitcreds}</code> packages.)</p></li>
 <li><p>type the following at the command line in the Console pane:</p>
-<pre><code>  library(usethis)
+<pre><code>  library(usethis)        
   usethis::create_github_token()</code></pre></li>
 </ul>
 <p>Note the double colons (“<code>::</code>”). This will open up a web
@@ -591,12 +598,25 @@ <h3><span class="header-section-number">2.2.2</span> Generate a Personal
 </ul>
 <p>A new page will open, with the new token in a green box. Copy the
 token, and save it on your computer somewhere you’ll be able to find it
-again.</p>
+again. (But don’t save it in
+<code>/Users/username/Projects/geog490project</code>; GitHub scans for
+PATs in uploaded files.)</p>
 <p>Then, switch back to RStudio, and type the following at the command
 line in the Console pane:</p>
-<pre><code>    credentials::set_github_pat()</code></pre>
+<pre><code>    gitcreds::gitcreds_set() </code></pre>
 <p>A “Password” box should pop up. Paste the PAT into the box. This sets
 the PAT.</p>
+<p><strong>Important:</strong> Restart R. (Session &gt; Restart R)</p>
+<p>There are three functions in the various packages that handle
+communications with GitHub that can be used to see if the PAT has been
+installed and working; each reports something a little different:</p>
+<pre><code>    usethis::gh_token_help()
+    gh::gh_whoami()
+    usethis::git_sitrep()</code></pre>
+<p>The <code>gh::gh_whoami()</code> is particularly useful, because it
+prints out a fragment of the PAT. If it doesn’t look right, the PAT can
+be deleted using <code>gitcreds::gitcreds_delete()</code> and process
+above repeated. You probably won’t have to do that.</p>
 </div>
 <div id="editupdate-a-file-then-commit-and-push-to-github"
 class="section level3" number="2.2.3">
@@ -709,7 +729,7 @@ <h2><span class="header-section-number">3.2</span> Back on the local
 number="3.2.1">
 <h3><span class="header-section-number">3.2.1</span> Build a multi-page
 web site</h3>
-<p>Restart RStudio. (<strong>Important</strong>)</p>
+<p><strong>Important</strong>: Restart RStudio</p>
 <p>As an example, download or copy the following “Example 5” files into
 <code>https://github.com/gh-username/geog490project</code>:</p>
 <ul>

diff --git a/docs/md/github.md b/docs/md/github.md
@@ -58,35 +58,47 @@ Start RStudio, and:
 - Project directory name:  `geog490project`  
 - Browse to the folder:  `/Users/Projects/` (but not `/Users/username/Projects/geog490project`) 
 - click on "Create Project" 
-- 
+
 (Note that there is no connection between the folder names, the `/Projects` folder is just that, the `/geog490project` is named for the course project.)
 
-(note that `.gitignore`, `README.md` and `geog490test.Rproj` files, and two folders `/.git` and `/Rproj.user` will have turned up in the working directory. You might not be able to see them if hidden files (that begin with a `.` on the Mac), are indeed hidden. Don't worry if you don't see them.
+(Note that `.gitignore`, `README.md` and `geog490test.Rproj` files, and two folders `/.git` and `/Rproj.user` will have turned up in the working directory. You might not be able to see them if hidden files (that begin with a `.` on the Mac), are indeed hidden. Don't worry if you don't see them.
 
 ### Generate a Personal Access Token ###
 
+See Section 9.1 of [[HappyGitWithR]](https://happygitwithr.com/index.html). There is a similar, but a bit more detailed discussion in the documentation for the `{usethis}` package at: [[https://usethis.r-lib.org/articles/git-credentials.html]](https://usethis.r-lib.org/articles/git-credentials.html) (TL;DR = "Too long; didn't read"!)
+
 Now, using RStudio, generate a personal access code (PAT):
 
-- install the `{usethis}` package (install.packages("usethis");
-- type the following at the command line in the Console pane:
-
-		library(usethis)
-		usethis::create_github_token()
+- install the `{usethis}` package (install.packages("usethis"). (This will also install the `{gh}` and `{gitcreds}` packages.) 
+- type the following at the command line in the Console pane:  
 
+		library(usethis)		
+		usethis::create_github_token()
+		
 Note the double colons ("`::`"). This will open up a web page at GitHub, where you will be invited to 
 
 - enter the PAT's "use case" (enter "RStudio");
 - select an expiration time ("No expiration" is ok);
 - scroll to the bottom, and click on the "Generate token" button.
 
-A new page will open, with the new token in a green box. Copy the token, and save it on your computer somewhere you'll be able to find it again.
+A new page will open, with the new token in a green box. Copy the token, and save it on your computer somewhere you'll be able to find it again. (But don't save it in `/Users/username/Projects/geog490project`; GitHub scans for PATs in uploaded files.)
 
 Then, switch back to RStudio, and type the following at the command line in the Console pane:
 
-		credentials::set_github_pat()
+		gitcreds::gitcreds_set() 
 
 A "Password" box should pop up. Paste the PAT into the box. This sets the PAT.
 
+**Important:** Restart R. (Session > Restart R)
+
+There are three functions in the various packages that handle communications with GitHub that can be used to see if the PAT has been installed and working; each reports something a little different:
+
+		usethis::gh_token_help()
+		gh::gh_whoami()
+		usethis::git_sitrep()
+
+The `gh::gh_whoami()` is particularly useful, because it prints out a fragment of the PAT. If it doesn't look right, the PAT can be deleted using `gitcreds::gitcreds_delete()` and process above repeated. You probably won't have to do that.
+
 ### Edit/update a file, then "Commit" and "Push" to GitHub
 
 Then, still on the local machine:
@@ -151,11 +163,15 @@ Anything that winds up in the `/docs` folder will be available to the `*.html` w
 
 ### Build a multi-page web site ###
 
-Restart RStudio. (**Important**)
+**Important**: Restart RStudio
 
 As an example, download or copy the following "Example 5" files into  `https://github.com/gh-username/geog490project`:
 
-  - [[index.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/index.Rmd)  - [[intro.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/intro.Rmd)  - [[alpha_plot_RMarkdown_Site.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/alpha_plot_RMarkdown_Site.Rmd)  - [[about.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/about.Rmd)  - [[_site.yml]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/\_site.yml)
+  - [[index.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/index.Rmd)
+  - [[intro.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/intro.Rmd)
+  - [[alpha_plot_RMarkdown_Site.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/alpha_plot_RMarkdown_Site.Rmd)
+  - [[about.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/about.Rmd)
+  - [[_site.yml]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/\_site.yml)
 
 Knit the files (except for `_site.yml`) by clicking on the "knit" button, and Build the website (see the Build pane). The files created will wind up in the `/docs` folder. 
 

diff --git a/md/github.md b/md/github.md
@@ -58,36 +58,46 @@ Start RStudio, and:
 - Project directory name:  `geog490project`  
 - Browse to the folder:  `/Users/Projects/` (but not `/Users/username/Projects/geog490project`) 
 - click on "Create Project" 
-- 
+
 (Note that there is no connection between the folder names, the `/Projects` folder is just that, the `/geog490project` is named for the course project.)
 
-(note that `.gitignore`, `README.md` and `geog490test.Rproj` files, and two folders `/.git` and `/Rproj.user` will have turned up in the working directory. You might not be able to see them if hidden files (that begin with a `.` on the Mac), are indeed hidden. Don't worry if you don't see them.
+(Note that `.gitignore`, `README.md` and `geog490test.Rproj` files, and two folders `/.git` and `/Rproj.user` will have turned up in the working directory. You might not be able to see them if hidden files (that begin with a `.` on the Mac), are indeed hidden. Don't worry if you don't see them.
 
 ### Generate a Personal Access Token ###
 
+See Section 9.1 of [[HappyGitWithR]](https://happygitwithr.com/index.html). There is a similar, but a bit more detailed discussion in the documentation for the `{usethis}` package at: [[https://usethis.r-lib.org/articles/git-credentials.html]](https://usethis.r-lib.org/articles/git-credentials.html) (TL;DR = "Too long; didn't read"!)
+
 Now, using RStudio, generate a personal access code (PAT):
 
-- install the `{usethis}` package (install.packages("usethis");
-- type the following at the command line in the Console pane:
-
-		library(usethis)
-		usethis::create_github_token()
+- install the `{usethis}` package (install.packages("usethis"). (This will also install the `{gh}` and `{gitcreds}` packages.) 
+- type the following at the command line in the Console pane:  
 
+		library(usethis)		
+		usethis::create_github_token()
+		
 Note the double colons ("`::`"). This will open up a web page at GitHub, where you will be invited to 
 
 - enter the PAT's "use case" (enter "RStudio");
 - select an expiration time ("No expiration" is ok);
 - scroll to the bottom, and click on the "Generate token" button.
 
-A new page will open, with the new token in a green box. Copy the token, and save it on your computer somewhere you'll be able to find it again.
+A new page will open, with the new token in a green box. Copy the token, and save it on your computer somewhere you'll be able to find it again. (But don't save it in `/Users/username/Projects/geog490project`; GitHub scans for PATs in uploaded files.)
 
 Then, switch back to RStudio, and type the following at the command line in the Console pane:
 
-		credentials::set_github_pat()
+		gitcreds::gitcreds_set() 
 
 A "Password" box should pop up. Paste the PAT into the box. This sets the PAT.
 
-Restart R: Session > Restart R.
+**Important:** Restart R. (Session > Restart R)
+
+There are three functions in the various packages that handle communications with GitHub that can be used to see if the PAT has been installed and working; each reports something a little different:
+
+		usethis::gh_token_help()
+		gh::gh_whoami()
+		usethis::git_sitrep()
+
+The `gh::gh_whoami()` is particularly useful, because it prints out a fragment of the PAT. If it doesn't look right, the PAT can be deleted using `gitcreds::gitcreds_delete()` and process above repeated. You probably won't have to do that.
 
 ### Edit/update a file, then "Commit" and "Push" to GitHub
 
@@ -153,11 +163,15 @@ Anything that winds up in the `/docs` folder will be available to the `*.html` w
 
 ### Build a multi-page web site ###
 
-Restart RStudio. (**Important**)
+**Important**: Restart RStudio
 
 As an example, download or copy the following "Example 5" files into  `https://github.com/gh-username/geog490project`:
 
-  - [[index.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/index.Rmd)  - [[intro.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/intro.Rmd)  - [[alpha_plot_RMarkdown_Site.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/alpha_plot_RMarkdown_Site.Rmd)  - [[about.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/about.Rmd)  - [[_site.yml]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/\_site.yml)
+  - [[index.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/index.Rmd)
+  - [[intro.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/intro.Rmd)
+  - [[alpha_plot_RMarkdown_Site.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/alpha_plot_RMarkdown_Site.Rmd)
+  - [[about.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/about.Rmd)
+  - [[_site.yml]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/\_site.yml)
 
 Knit the files (except for `_site.yml`) by clicking on the "knit" button, and Build the website (see the Build pane). The files created will wind up in the `/docs` folder.