markdown source builds

Auto-generated via {sandpaper}
Source  : b33dbf2
Branch  : main
Author  : Martino Sorbaro <[email protected]>
Time    : 2024-07-18 07:39:46 +0000
Message : Merge pull request swcarpentry#927 from kleuveld/replace_checkout_with_restore

change the use of git checkout to git restore

01-basics.md

@@ -38,20 +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](../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
@@ -125,5 +125,3 @@ the same files concurrently.
 - Version control also allows many people to work in parallel.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
-
-

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. `[email protected]` 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+[email protected]`. You can look up your own address in your GitHub [email settings](https://github.com/settings/emails).
 
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::

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 /
@@ -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.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
-
-

04-changes.md

@@ -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.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
-
-