Merge branch 'main' into replace_checkout_with_restore

.github/workflows/README.md

@@ -2,7 +2,7 @@
 
 This directory contains workflows to be used for Lessons using the {sandpaper}
 lesson infrastructure. Two of these workflows require R (`sandpaper-main.yaml`
-and `pr-recieve.yaml`) and the rest are bots to handle pull request management.
+and `pr-receive.yaml`) and the rest are bots to handle pull request management.
 
 These workflows will likely change as {sandpaper} evolves, so it is important to
 keep them up-to-date. To do this in your lesson you can do the following in your
@@ -94,9 +94,9 @@ branch called `update/workflows` and a pull request is created. Maintainers are
 encouraged to review the changes and accept the pull request if the outputs
 are okay.
 
-This update is run ~~weekly or~~ on demand.
+This update is run weekly or on demand.
 
-### 03 Maintain: Update Pacakge Cache (update-cache.yaml)
+### 03 Maintain: Update Package Cache (update-cache.yaml)
 
 For lessons that have generated content, we use {renv} to ensure that the output
 is stable. This is controlled by a single lockfile which documents the packages
@@ -140,7 +140,7 @@ Once the checks are finished, a comment is issued to the pull request, which
 will allow maintainers to determine if it is safe to run the 
 "Receive Pull Request" workflow from new contributors.
 
-### Recieve Pull Request (pr-recieve.yaml)
+### Receive Pull Request (pr-receive.yaml)
 
 **Note of caution:** This workflow runs arbitrary code by anyone who creates a
 pull request. GitHub has safeguarded the token used in this workflow to have no
@@ -171,7 +171,7 @@ The artifacts produced are used by the next workflow.
 
 ### Comment on Pull Request (pr-comment.yaml)
 
-This workflow is triggered if the `pr-recieve.yaml` workflow is successful.
+This workflow is triggered if the `pr-receive.yaml` workflow is successful.
 The steps in this workflow are:
 
 1. Test if the workflow is valid and comment the validity of the workflow to the

.github/workflows/sandpaper-version.txt

@@ -1 +1 @@
-0.11.16
+0.16.5

CONTRIBUTING.md

@@ -26,12 +26,13 @@ introduce yourself and to meet some of our community members.
 
 2. If you have a [GitHub][github] account, or are willing to [create
    one][github-join], but do not know how to use Git, you can report problems
-   or suggest improvements by [creating an issue][issues]. This allows us to
-   assign the item to someone and to respond to it in a threaded discussion.
+   or suggest improvements by [creating an issue][repo-issues]. This allows us
+   to assign the item to someone and to respond to it in a threaded discussion.
 
 3. If you are comfortable with Git, and would like to add or change material,
    you can submit a pull request (PR). Instructions for doing this are
-   [included below](#using-github).
+   [included below](#using-github). For inspiration about changes that need to
+   be made, check out the [list of open issues][issues] across the Carpentries.
 
 Note: if you want to build the website locally, please refer to [The Workbench
 documentation][template-doc].
@@ -49,8 +50,8 @@ There are many ways to contribute, from writing new exercises and improving
 existing ones to updating or filling in the documentation and submitting [bug
 reports][issues] about things that do not work, are not clear, or are missing.
 If you are looking for ideas, please see [the list of issues for this
-repository][repo], or the issues for [Data Carpentry][dc-issues], [Library
-Carpentry][lc-issues], and [Software Carpentry][swc-issues] projects.
+repository][repo-issues], or the issues for [Data Carpentry][dc-issues],
+[Library Carpentry][lc-issues], and [Software Carpentry][swc-issues] projects.
 
 Comments on issues and reviews of pull requests are just as welcome: we are
 smarter together than we are on our own. **Reviews from novices and newcomers
@@ -102,6 +103,7 @@ media, slack, newsletters, and email lists. You can also [reach us by
 email][contact].
 
 [repo]: https://github.com/swcarpentry/git-novice
+[repo-issues]: https://github.com/swcarpentry/git-novice/issues
 [contact]: mailto:team@carpentries.org
 [cp-site]: https://carpentries.org/
 [dc-issues]: https://github.com/issues?q=user%3Adatacarpentry

README.md

@@ -1,31 +1,29 @@
-[![Create a Slack Account with us](https://img.shields.io/badge/Create_Slack_Account-The_Carpentries-071159.svg)](https://swc-slack-invite.herokuapp.com/)
-[![Slack Status](https://img.shields.io/badge/Slack_Channel-swc--git-E01563.svg)](https://swcarpentry.slack.com/messages/C91JS49HD)
+[![Create a Slack Account with us](https://img.shields.io/badge/Create_Slack_Account-The_Carpentries-071159.svg)](https://slack-invite.carpentries.org/)
+[![Slack Status](https://img.shields.io/badge/Slack_Channel-swc--git-E01563.svg)](https://carpentries.slack.com/messages/C91JS49HD)
 
 # git-novice
 
 An introduction to version control for novices using Git.
 Please see [https://swcarpentry.github.io/git-novice/](https://swcarpentry.github.io/git-novice/) for a rendered version of this material,
-[the lesson template documentation][lesson-example]
-for instructions on formatting, building, and submitting material,
-or run `make` in this directory for a list of helpful commands.
+or [the lesson template documentation][lesson-example] for instructions on formatting, building, and submitting material.
 
 Maintainers:
 
-- [Nima Hejazi][hejazi_nima]: [@nhejazi](https://github.com/nhejazi)
 - [Kat Koziar][koziar_kat]: [@kekoziar](https://github.com/kekoziar)
-- [Madicken Munk][munk_madicken]: [@munkm](https://github.com/munkm)
+- [Martino Sorbaro][sorbaro_mart]: [@martinosorb](https://github.com/martinosorb)
 
 Alumni maintainers:
 
 - [Ivan Gonzalez][gonzalez_ivan]: [@iglpdc](https://github.com/iglpdc)
 - [Daisie Huang][huang_daisie]: [@daisieh](https://github.com/daisieh)
+- [Nima Hejazi][hejazi_nima]: [@nhejazi](https://github.com/nhejazi)
+- [Madicken Munk][munk_madicken]: [@munkm](https://github.com/munkm)
 
-[lesson-example]: https://swcarpentry.github.io/lesson-example
+
+[lesson-example]: https://carpentries.github.io/sandpaper-docs/
 [hejazi_nima]: https://carpentries.org/instructors/#nhejazi
 [koziar_kat]: https://carpentries.org/instructors/#kekoziar
 [munk_madicken]: https://carpentries.org/instructors/#munkm
 [gonzalez_ivan]: https://carpentries.org/instructors/#iglpdc
 [huang_daisie]: https://software-carpentry.org/team/#huang_daisie
-
-
-
+[sorbaro_mart]: https://carpentries.org/instructors/#martinosorb

episodes/01-basics.md

@@ -22,9 +22,7 @@ to keep track of what one person did and when.
 Even if you aren't collaborating with other people,
 automated version control is much better than this situation:
 
-!["Piled Higher and Deeper" by Jorge Cham, http://www.phdcomics.com](fig/phd101212s.png)
-
-"Piled Higher and Deeper" by Jorge Cham, [http://www.phdcomics.com](https://www.phdcomics.com)
+!["notFinal.doc" by Jorge Cham, <https://www.phdcomics.com>](fig/phd101212s.png){alt='Comic: a PhD student sends "FINAL.doc" to their supervisor, but after several increasingly intense and frustrating rounds of comments and revisions they end up with a file named "FINAL_rev.22.comments49.corrections.10.#@$%WHYDIDCOMETOGRADSCHOOL????.doc"'}
 
 We've all been in this situation before: it seems unnecessary to have
 multiple nearly-identical versions of the same document. Some word
@@ -40,19 +38,20 @@ think of it as a recording of your progress: you can rewind to start at the base
 document and play back each change you made, eventually arriving at your
 more recent version.
 
-![](fig/play-changes.svg){alt='Changes Are Saved Sequentially'}
+![](fig/play-changes.svg){alt='A diagram demonstrating how a single document grows as the result of sequential changes'}
 
 Once you think of changes as separate from the document itself, you
 can then think about "playing back" different sets of changes on the base document, ultimately
 resulting in different versions of that document. For example, two users can make independent
 sets of changes on the same document.
 
-![](fig/versions.svg){alt='Different Versions Can be Saved'}
+![](fig/versions.svg){alt='A diagram with one source document that has been modified in two different ways to produce two different versions of the document'}
 
-Unless multiple users make changes to the same section of the document - a conflict - you can
+Unless multiple users make changes to the same section of the document - a 
+[conflict](../learners/reference.md#conflict) - you can
 incorporate two sets of changes into the same base document.
 
-![](fig/merge.svg){alt='Multiple Versions Can be Merged'}
+![](fig/merge.svg){alt='A diagram that shows the merging of two different document versions into one document that contains all of the changes from both versions'}
 
 A version control system is a tool that keeps track of these changes for us,
 effectively creating different versions of our files. It allows us to decide
@@ -126,5 +125,3 @@ the same files concurrently.
 - Version control also allows many people to work in parallel.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
-
-

episodes/02-setup.md

@@ -48,7 +48,7 @@ For this lesson, we will be interacting with [GitHub](https://github.com/) and s
 
 ## Keeping your email private
 
-If you elect to use a private email address with GitHub, then use that same email address for the `user.email` value, e.g. `username@users.noreply.github.com` replacing `username` with your GitHub one.
+If you elect to use a private email address with GitHub, then use GitHub's no-reply email address for the `user.email` value. It looks like `ID+username@users.noreply.github.com`. You can look up your own address in your GitHub [email settings](https://github.com/settings/emails).
 
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
@@ -79,7 +79,7 @@ $ git config --global core.autocrlf input
 And on Windows:
 
 ```bash
-$ git config --global core.autocrlf false
+$ git config --global core.autocrlf true
 ```
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::

episodes/03-create.md

@@ -23,7 +23,7 @@ we can start using it.
 We will continue with the story of Wolfman and Dracula who are investigating if it
 is possible to send a planetary lander to Mars.
 
-![](fig/motivatingexample.png){alt='motivatingexample'}
+![](fig/motivatingexample.png){alt='The main elements of the story: Dracula, Wolfman, the Mummy, Mars, Pluto and The Moon'}
 [Werewolf vs dracula](https://www.deviantart.com/b-maze/art/Werewolf-vs-Dracula-124893530)
 by [b-maze](https://www.deviantart.com/b-maze) / [Deviant Art](https://www.deviantart.com/).
 [Mars](https://en.wikipedia.org/wiki/File:OSIRIS_Mars_true_color.jpg) by European Space Agency /
@@ -85,7 +85,7 @@ we will lose the project's history.
 Next, we will change the default branch to be called `main`.
 This might be the default branch depending on your settings and version
 of git.
-See the [setup episode](02-setup.md) for more information on this change.
+See the [setup episode](02-setup.md#default-git-branch-naming) for more information on this change.
 
 ```bash
 $ git checkout -b main
@@ -95,8 +95,7 @@ $ git checkout -b main
 Switched to a new branch 'main'
 ```
 
-We can check that everything is set up correctly
-by asking Git to tell us the status of our project:
+We can now start using one of the most important git commands, which is particularly helpful to beginners. `git status` tells us the status of our project, and better, a list of changes in the project and options on what to do with those changes. We can use it as often as we want, whenever we want to understand what is going on.
 
 ```bash
 $ git status
@@ -166,7 +165,7 @@ fatal: Not a git repository (or any of the parent directories): .git
 ## Correcting `git init` Mistakes
 
 Wolfman explains to Dracula how a nested repository is redundant and may cause confusion
-down the road. Dracula would like to remove the nested repository. How can Dracula undo
+down the road. Dracula would like to go back to a single git repository. How can Dracula undo
 his last `git init` in the `moons` subdirectory?
 
 :::::::::::::::  solution
@@ -183,14 +182,14 @@ that are not tracked by Git can easily be removed like any other "ordinary" file
 $ rm filename
 ```
 
-Similarly a directory can be removed using `rm -r dirname` or `rm -rf dirname`.
+Similarly a directory can be removed using `rm -r dirname`.
 If the files or folder being removed in this fashion are tracked by Git, then their removal
 becomes another change that we will need to track, as we will see in the next episode.
 
 ### Solution
 
 Git keeps all of its files in the `.git` directory.
-To recover from this little mistake, Dracula can just remove the `.git`
+To recover from this little mistake, Dracula can remove the `.git`
 folder in the moons subdirectory by running the following command from inside the `planets` directory:
 
 ```bash
@@ -199,6 +198,7 @@ $ rm -rf moons/.git
 
 But be careful! Running this command in the wrong directory will remove
 the entire Git history of a project you might want to keep.
+In general, deleting files and directories using `rm` from the command line cannot be reversed.
 Therefore, always check your current directory using the command `pwd`.
 
 
@@ -213,5 +213,3 @@ Therefore, always check your current directory using the command `pwd`.
 - Git stores all of its repository data in the `.git` directory.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
-
-

episodes/04-changes.md

@@ -31,7 +31,7 @@ Let's create a file called `mars.txt` that contains some notes
 about the Red Planet's suitability as a base.
 We'll use `nano` to edit the file;
 you can use whatever editor you like.
-In particular, this does not have to be the `core.editor` you set globally earlier. But remember, the bash command to create or edit a new file will depend on the editor you choose (it might not be `nano`). For a refresher on text editors, check out ["Which Editor?"](https://swcarpentry.github.io/shell-novice/03-create/) in [The Unix Shell](https://swcarpentry.github.io/shell-novice/) lesson.
+In particular, this does not have to be the `core.editor` you set globally earlier. But remember, the bash command to create or edit a new file will depend on the editor you choose (it might not be `nano`). For a refresher on text editors, check out ["Which Editor?"](https://swcarpentry.github.io/shell-novice/03-create.html#which-editor) in [The Unix Shell](https://swcarpentry.github.io/shell-novice/) lesson.
 
 ```bash
 $ nano mars.txt
@@ -334,7 +334,7 @@ than you would like!
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
-![](fig/git-staging-area.svg){alt='The Git Staging Area'}
+![](fig/git-staging-area.svg){alt='A diagram showing how "git add" registers changes in the staging area, while "git commit" moves changes from the staging area to the repository'}
 
 Let's watch as our changes to a file move from our editor
 to the staging area
@@ -587,7 +587,7 @@ we first need to add the changed files to the staging area
 (`git add`) and then commit the staged changes to the
 repository (`git commit`):
 
-![](fig/git-committing.svg){alt='The Git Commit Workflow'}
+![](fig/git-committing.svg){alt='A diagram showing two documents being separately staged using git add, before being combined into one commit using git commit'}
 
 :::::::::::::::::::::::::::::::::::::::  challenge
 
@@ -622,19 +622,19 @@ Which command(s) below would save the changes of `myfile.txt`
 to my local Git repository?
 
 1. ```bash
-  $ git commit -m "my recent changes"
-  ```
+   $ git commit -m "my recent changes"
+   ```
 2. ```bash
-  $ git init myfile.txt
-  $ git commit -m "my recent changes"
-  ```
+   $ git init myfile.txt
+   $ git commit -m "my recent changes"
+   ```
 3. ```bash
-  $ git add myfile.txt
-  $ git commit -m "my recent changes"
-  ```
+   $ git add myfile.txt
+   $ git commit -m "my recent changes"
+   ```
 4. ```bash
-  $ git commit -m myfile.txt "my recent changes"
-  ```
+   $ git commit -m myfile.txt "my recent changes"
+   ```
 
 :::::::::::::::  solution
 
@@ -659,11 +659,11 @@ The staging area can hold changes from any number of files
 that you want to commit as a single snapshot.
 
 1. Add some text to `mars.txt` noting your decision
-  to consider Venus as a base
+   to consider Venus as a base
 2. Create a new file `venus.txt` with your initial thoughts
-  about Venus as a base for you and your friends
+   about Venus as a base for you and your friends
 3. Add changes from both files to the staging area,
-  and commit those changes.
+   and commit those changes.
 
 :::::::::::::::  solution
 
@@ -791,5 +791,3 @@ $ git diff me.txt
 - Write a commit message that accurately describes your changes.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
-
-

episodes/05-history.md

@@ -73,7 +73,7 @@ If we want to see the differences between older commits we can use `git diff`
 again, but with the notation `HEAD~1`, `HEAD~2`, and so on, to refer to them:
 
 ```bash
-$ git diff HEAD~3 mars.txt
+$ git diff HEAD~2 mars.txt
 ```
 
 ```output
@@ -93,7 +93,7 @@ well as the commit message, rather than the *differences* between a commit and o
 working directory that we see by using `git diff`.
 
 ```bash
-$ git show HEAD~3 mars.txt
+$ git show HEAD~2 mars.txt
 ```
 
 ```output
@@ -122,7 +122,7 @@ while `HEAD~123` goes back 123 commits from where we are now.
 
 We can also refer to commits using
 those long strings of digits and letters
-that `git log` displays.
+that both `git log` and `git show` display.
 These are unique IDs for the changes,
 and "unique" really does mean unique:
 every change to any set of files on any computer
@@ -262,12 +262,12 @@ the commit in which we made the change we're trying to discard.
 In the example below, we want to retrieve the state from before the most
 recent commit (`HEAD~1`), which is commit `f22b25e`. We use the `.` to mean all files:
 
-![](fig/git-restore.svg){alt='Git Restore'}
+![](fig/git-restore.svg){alt='A diagram showing how git restore can be used to restore the previous version of two files'}
 
 So, to put it all together,
 here's how Git works in cartoon form:
 
-![https://figshare.com/articles/How_Git_works_a_cartoon/1328266](fig/git_staging.svg)
+![https://figshare.com/articles/How_Git_works_a_cartoon/1328266](fig/git_staging.svg){alt='A diagram showing the entire git workflow: local changes are staged using git add, applied to the local repository using git commit, and can be restored from the repository using git checkout'}
 
 
 The fact that files can be reverted one by one
@@ -559,5 +559,3 @@ $ git log --patch HEAD~9 *.txt
 - `git restore` recovers old versions of files.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
-
-