Merge pull request #9 from NCEAS/auth-dev

Added SSH Authentication Instructions

branches.qmd

@@ -6,25 +6,25 @@ title: "Branches"
 
 By the end of this module, you will be able to:
 
-- <u>Define</u> "branch" in the context of `git`/GitHub 
+- <u>Define</u> "branch" in the context of Git/GitHub 
 - <u>Summarize</u> the main steps of a workflow that uses branches
 - <u>Create</u> a branch on an existing repository
 
 ## What is a Branch?
 
-A **branch** is essentially a working environment in your `git` repository that is separate from your main working area. This can be incredibly useful when you have a task to work on but you don't want to risk damaging the version of your code that already works. Note that "branch" can be either a noun or a verb as with many of the `git` vocabulary words discussed earlier (e.g., "commit", "push", etc.).
+A **branch** is essentially a working environment in your Git repository that is separate from your main working area. This can be incredibly useful when you have a task to work on but you don't want to risk damaging the version of your code that already works. Note that "branch" can be either a noun or a verb as with many of the Git vocabulary words discussed earlier (e.g., "commit", "push", etc.).
 
 Branches are typically created with **the intent to put the work in the branch back into the main branch when you are done with it.** Implicit in that rationale is the fact that most branches are created with a specific task/sub-task in mind and known to be temporary from the outset.
 
-As an example, imagine that you want to put a better engine in your car but you don't want to risk damaging your car as you go about that job. In `git` terms you could create a branch to work on those mechanical improvements while at the same time preserving your original car separately (in the "main" branch). When you're done experimenting and happy with the new version of your car, you can merge the two cars keeping all of the improvements you made in your branch.
+As an example, imagine that you want to put a better engine in your car but you don't want to risk damaging your car as you go about that job. In Git terms you could create a branch to work on those mechanical improvements while at the same time preserving your original car separately (in the "main" branch). When you're done experimenting and happy with the new version of your car, you can merge the two cars keeping all of the improvements you made in your branch.
 
-Even if you think you've never worked with `git` branches you actually have! All `git` repositories actually start in a branch named "main" so even if you've never intentionally created a branch, you've been working in your "main" branch all along.
+Even if you think you've never worked with Git branches you actually have! All Git repositories actually start in a branch named "main" so even if you've never intentionally created a branch, you've been working in your "main" branch all along.
 
 ## Brief Overview of Branch Workflow
 
-Before diving into the specifics of how to use branches while working with `git`, let's take a look at a general overview of that process.
+Before diving into the specifics of how to use branches while working with Git, let's take a look at a general overview of that process.
 
-As with many other `git` operations, the first thing to do is **<span style="color:blue">pull</span>** from GitHub to your local repository to ensure that you're working with the most up-to-date version of everything in the repo (see **Step 1** below).
+As with many other Git operations, the first thing to do is **<span style="color:blue">pull</span>** from GitHub to your local repository to ensure that you're working with the most up-to-date version of everything in the repo (see **Step 1** below).
 
 Once that is done, you can create a branch on your local machine (automatically shifting your RStudio project into that new branch). Doing this on your machine also updates GitHub to show that there are multiple branches (see **Step 2** below).
 
@@ -38,7 +38,7 @@ Given that most branches are not used again after they are merged, it is often a
 
 However, deletion of the branch either locally or via GitHub **must** come *after* step 5!
 
-As you can see from the above text and the below diagram, branches have a few more moving parts than the `git` and GitHub operations we've discussed so far. That said, they can be a powerful tool in service of collaborative work because you can have multiple branches active at the same all working on separate tasks. This approach can be an easy (or at least eas*ier*) workflow for working together while avoiding conflicts (again, see "Appendix A: Conflicts").
+As you can see from the above text and the below diagram, branches have a few more moving parts than the Git and GitHub operations we've discussed so far. That said, they can be a powerful tool in service of collaborative work because you can have multiple branches active at the same all working on separate tasks. This approach can be an easy (or at least eas*ier*) workflow for working together while avoiding conflicts (again, see "Appendix A: Conflicts").
 
 <p align="center">
 <img src="images/branches/git-branch-workflow.png" width="75%"/>
@@ -64,7 +64,7 @@ Once you're happy with the name, click **"Create"** (you can ignore the other op
 <img src="images/branches/branches-2-name-new-branch.png" width="65%"/>
 </p>
 
-This will create a confirmation message that is superficially similar to the format of messages returned by other `git` actions.
+This will create a confirmation message that is superficially similar to the format of messages returned by other Git actions.
 
 <p align="center">
 <img src="images/branches/branches-2b-success-dialogue.png" width="75%"/>
@@ -85,7 +85,7 @@ You can now work in a branch *in the same way* that you work with GitHub via RSt
 3. **<span style="color:blue">Pull</span>** from GitHub to reduce the chances of a conflict
 4. **<span style="color:green">Push</span>** your committed changes to GitHub
 
-The reason you use the same workflow is--as previously stated--even if you don't typically use branches, all work in `git` is functionally done in the "main" branch of your repository.
+The reason you use the same workflow is--as previously stated--even if you don't typically use branches, all work in Git is functionally done in the "main" branch of your repository.
 
 For a more in-depth review of the RStudio-GitHub workflow, see Chapter 3: Using GitHub via Rstudio
 

conflicts.qmd

@@ -12,7 +12,7 @@ By the end of this module, you will be able to:
 
 ## What is a Merge Conflict?
 
-Merge conflicts are a normal part of the `git` workflow so don't get discouraged when you run into them! They occur when `git` cannot figure out how to automatically merge new changes together. This can happen when you and your collaborators change the same lines in the same file without first pulling the changes that the other party has made.
+Merge conflicts are a normal part of the Git workflow so don't get discouraged when you run into them! They occur when Git cannot figure out how to automatically merge new changes together. This can happen when you and your collaborators change the same lines in the same file without first pulling the changes that the other party has made.
 
 ## Brief Overview of Merge Conflict Workflow
 
@@ -70,7 +70,7 @@ After clicking **<span style="color:blue">Pull</span>**, we get a new error mess
 
 ![](images/conflicts/conflicts-7-birds-pull.png)
 
-Looking closer, the merge conflict prompted a new version of `test-script.R` to pop up. This version contains our edits and our collaborator's edits, along with the delimiter lines that start with `<<<<<<<`, `=======`, and `>>>>>>>`. `git` is urging us to manually fix the conflicted lines before continuing.
+Looking closer, the merge conflict prompted a new version of `test-script.R` to pop up. This version contains our edits and our collaborator's edits, along with the delimiter lines that start with `<<<<<<<`, `=======`, and `>>>>>>>`. Git is urging us to manually fix the conflicted lines before continuing.
 
 <p align="center"/>
 <img src="images/conflicts/conflicts-8-conflicted-lines.png" width="80%"/>

forks.qmd

@@ -6,21 +6,21 @@ title: "Forks"
 
 By the end of this module, you will be able to:
 
-- <u>Define</u> "fork" in the context of `git`/GitHub
+- <u>Define</u> "fork" in the context of Git/GitHub
 - <u>Contrast</u> forks with branches
 - <u>Use</u> the fork feature on GitHub for an existing repository
 
 ## What is a Fork?
 
-A **fork** is a duplicate of a `git` repository that is owned by someone other than you. Any repository that you can view on GitHub, you can fork. Forks allow you to start with a complete repository and then edit it for your own use as needed.
+A **fork** is a duplicate of a Git repository that is owned by someone other than you. Any repository that you can view on GitHub, you can fork. Forks allow you to start with a complete repository and then edit it for your own use as needed.
 
-The difference between **forks** and **branches** is a source of great confusion for many (even veteran!) `git` users but hopefully this list helps to clarify:
+The difference between **forks** and **branches** is a source of great confusion for many (even veteran!) Git users but hopefully this list helps to clarify:
 
 1. A fork creates a new repository while a branch exists within a given repository
 
 2. A fork is owned by a different user/organization than the original, a branch does not change repository ownership
 
-3. A fork's "parent" repository is not recognized by `git` but `git` does 'know' which branch a given branch originates from.
+3. A fork's "parent" repository is not recognized by Git but Git does 'know' which branch a given branch originates from.
 
 ## Choosing Whether to Fork or to Branch
 
@@ -32,7 +32,7 @@ It is important to note that both forks and branches can be merged back into the
 
 ## Brief Overview of Fork Workflow
 
-Forking is (arguably) one of the more straightforward `git` workflows but before we cover it in detail, let's review the broader context.
+Forking is (arguably) one of the more straightforward Git workflows but before we cover it in detail, let's review the broader context.
 
 You begin by going to the GitHub page for a repository that you do not own. From there, there is a convenient "Fork" button you can click that (after a screen very much like that of creating a new repository) creates a duplicate of the repository in your profile's repository list.
 

git_ignore.qmd

@@ -12,7 +12,7 @@ By the end of this module, you will be able to:
 
 ## Overview
 
-The purpose of the `.gitignore` is evident in its name: anything included in it is *ignored by `git`*. This can be useful if you want to include data in your local version of your repository but don't want to risk sharing that data by committing it to a GitHub repository you plan to make public at some point. This file exists at the top level of every repository and can be customized however is most useful to you and your collaborators.
+The purpose of the `.gitignore` is evident in its name: anything included in it is *ignored by Git*. This can be useful if you want to include data in your local version of your repository but don't want to risk sharing that data by committing it to a GitHub repository you plan to make public at some point. This file exists at the top level of every repository and can be customized however is most useful to you and your collaborators.
 
 ## Creating a `.gitignore`
 
@@ -50,7 +50,7 @@ After you click it you'll be looking at a file that looks very similar to any ot
 <img src="images/git_ignore/ignore-6-viewing.png" width = "100%"/>
 </p>
 
-Now let's add something to it! As you can see from the Git pane of the above image (top right), after cloning our new repository, the only file `git` is flagging as untracked is the .Rproj file created whenever you make a new RStudio project.
+Now let's add something to it! As you can see from the Git pane of the above image (top right), after cloning our new repository, the only file Git is flagging as untracked is the .Rproj file created whenever you make a new RStudio project.
 
 If we add `*.Rproj` to our `.gitignore`, the Git pane will show that the only change is that lines have been added to the `.gitignore`. The .Rproj file with the double yellow question marks next to it is gone!
 
@@ -81,7 +81,7 @@ There are many different opinions on what should go into a `.gitignore` but we h
 3. **Other Considerations**
 
     - Some people recommend adding <u>everything your script creates</u> to the `.gitignore`. The theory being that if someone wants to see those outputs, they would only need to run your script(s) in order to create their own versions
-    - Another way of thinking about this is to create a dedicated folder to store products in (e.g., "data", "exports", etc.) and then add that folder to the `.gitignore`. This means you don't need to worry about adding specific files to the `.gitignore` so long as all the files live in a folder you've already designated as something for `git` to not track
+    - Another way of thinking about this is to create a dedicated folder to store products in (e.g., "data", "exports", etc.) and then add that folder to the `.gitignore`. This means you don't need to worry about adding specific files to the `.gitignore` so long as all the files live in a folder you've already designated as something for Git to not track
 
 4. Do you have another idea for what you typically add to a `.gitignore`?
 
@@ -135,16 +135,16 @@ Ultimately, this is up to you and your team to decide! Hopefully our outlined re
 
 ## Ignoring Previously Tracked Content
 
-Imagine a situation where you commit a data file to your GitHub repository and push that commit. Now your data file is tracked by `git` and every time you alter that file RStudio's "Git" pane will notify you that the file changed by placing the blue "M" next to the file's name. Let's say that eventually you decide that you want to (1) remove the file from your GitHub repository and (2) stop `git` from tracking *future* changes to the file. If this is the case, you'll need to do the following:
+Imagine a situation where you commit a data file to your GitHub repository and push that commit. Now your data file is tracked by Git and every time you alter that file RStudio's "Git" pane will notify you that the file changed by placing the blue "M" next to the file's name. Let's say that eventually you decide that you want to (1) remove the file from your GitHub repository and (2) stop Git from tracking *future* changes to the file. If this is the case, you'll need to do the following:
 
 1. Either (A) delete the file or (B) move it out of the repository's folder
 
-    - Either option will register as "deleting" the file from `git`'s perspective
+    - Either option will register as "deleting" the file from Git's perspective
 
 2. **Commit** the deletion
 
 3. **<span style="color:green">Push</span>** that change
 
 4. Add the name of that file to your `.gitignore`
 
-Once you've done these steps, even if you put the file back in your repository, `git` won't track its addition or any changes to it over time.
+Once you've done these steps, even if you put the file back in your repository, Git won't track its addition or any changes to it over time.

github.qmd

@@ -1,39 +1,39 @@
 ---
-title: "`git` & GitHub"
+title: "Git & GitHub"
 ---
 
 ## Module Learning Objectives
 
 By the end of this module, you will be able to:
 
-- <u>Describe</u> the difference between `git` and GitHub
+- <u>Describe</u> the difference between Git and GitHub
 - <u>Navigate</u> GitHub via a web browser
 - <u>Use</u> GitHub to create a new repository
 - <u>Edit</u> a new repository through GitHub's interface
 
 ## Version Control Background
 
-Version control systems (including `git`) are built to preserve the iterative versions that we create on the way to a final product. For instance, when writing a scientific manuscript we might have several discrete stages (e.g., separate drafts after successive rounds of feedback from collaborators) as well as the sort of small-scale changes we don't necessarily preserve in separate files (e.g., workshopping a particular sentence for rhetorical flow).
+Version control systems (including Git) are built to preserve the iterative versions that we create on the way to a final product. For instance, when writing a scientific manuscript we might have several discrete stages (e.g., separate drafts after successive rounds of feedback from collaborators) as well as the sort of small-scale changes we don't necessarily preserve in separate files (e.g., workshopping a particular sentence for rhetorical flow).
 
 **Version control systems provide a framework for preserving these changes without cluttering your computer with all of the files that precede the final version.**
 
 <p align="center">
 <img src="images/comics/phd_comics_final.png" align="center" width="60%"/>
 </p>
 
-## `git`-Specific Background
+## Git-Specific Background
 
-`git` can be enabled on a specific folder/directory on your file system to version files within that directory (including sub-directories). In `git` (and other version control systems) terms, this "tracked folder" is called a **repository** (which formally is a specific data structure storing versioning information).
+Git can be enabled on a specific folder/directory on your file system to version files within that directory (including sub-directories). In Git (and other version control systems) terms, this "tracked folder" is called a **repository** (which formally is a specific data structure storing versioning information).
 
 Although there many ways to start a new repository, [GitHub](https://github.com/) (or any other cloud solutions, such as [GitLab](https://about.gitlab.com/)) provide among the most convenient way of starting a repository.
 
-Let's distinguish between `git` and GitHub:
+Let's distinguish between Git and GitHub:
 
-- __`git`__: version control software used to track files in a folder (a repository)
-    - `git` creates the versioned history of a repository
-- __GitHub__: website that allows users to store their `git` repositories and share them with others (i.e. a graphical user interface or "GUI")
+- __Git__: version control software used to track files in a folder (a repository)
+    - Git creates the versioned history of a repository
+- __GitHub__: website that allows users to store their Git repositories and share them with others (i.e. a graphical user interface or "GUI")
 
-**GitHub is a company that hosts `git` repositories online** and provides several collaboration features. GitHub fosters a great user community and has built a nice web interface to `git`, also adding great visualization/rendering capacities of your data.
+**GitHub is a company that hosts Git repositories online** and provides several collaboration features. GitHub fosters a great user community and has built a nice web interface to Git, also adding great visualization/rendering capacities of your data.
 
 - **GitHub.com**: <https://github.com>
 - **A user account**: <https://github.com/brunj7>
@@ -86,7 +86,7 @@ And finally, if we examine one of the changes made on April 25, we can see exact
 
 <img src="images/github/github-9-specific-changes.png" width="100%"/>
 
-The red lines have been deleted while the green lines are new additions. Tracking these changes, and seeing how they relate to released versions of software and files is exactly what `git` and GitHub are good for. We will show how they can really be effective for tracking versions of scientific code, figures, and manuscripts to accomplish a reproducible workflow.
+The red lines have been deleted while the green lines are new additions. Tracking these changes, and seeing how they relate to released versions of software and files is exactly what Git and GitHub are good for. We will show how they can really be effective for tracking versions of scientific code, figures, and manuscripts to accomplish a reproducible workflow.
 
 Note: it is possible to edit and add files entirely on the GitHub website, by navigating to the specific file or repository. However, for this workshop, we will be editing and adding files through RStudio instead.