markdown source builds

Auto-generated via `{sandpaper}` Source : ac1fb3b Branch : main Author : Martino Sorbaro <[email protected]> Time : 2025-02-03 16:33:17 +0000 Message : Merge pull request swcarpentry#1065 from swcarpentry/941-link-to-official-mercurial-docs-instead-of-our-lesson Update 01-basics.md
WEHI-Education · Feb 7, 2025 · 47f6344 · 47f6344
1 parent 3e471d2
commit 47f6344
Show file tree

Hide file tree

Showing 31 changed files with 365 additions and 1,484 deletions.
diff --git a/01-basics.md b/01-basics.md
@@ -71,13 +71,12 @@ Tools like [RCS](https://en.wikipedia.org/wiki/Revision_Control_System), [CVS](h
 many large companies.
 However, many of these are now considered legacy systems (i.e., outdated) due to various
 limitations in their capabilities.
-More modern systems, such as Git and [Mercurial](https://swcarpentry.github.io/hg-novice/),
+More modern systems, such as [Git](https://en.wikipedia.org/wiki/Git) and [Mercurial](https://en.wikipedia.org/wiki/Mercurial),
 are *distributed*, meaning that they do not need a centralized server to host the repository.
-These modern systems also include powerful merging tools that make it possible for
-multiple authors to work on
+These modern systems also include powerful merging tools that make it possible for multiple authors to work on
 the same files concurrently.
 
-
+For those interested, The Carpentries has a [Version Control with Mercurial](https://swcarpentry.github.io/hg-novice/) lesson (2013-2018), which provides additional context and historical perspective.
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 :::::::::::::::::::::::::::::::::::::::  challenge

diff --git a/02-setup.md b/02-setup.md
@@ -57,7 +57,7 @@ If you elect to use a private email address with GitHub, then use GitHub's no-re
 
 ## Line Endings
 
-As with other keys, when you hit <kbd>Enter</kbd> or <kbd>↵</kbd> or on Macs, <kbd>Return</kbd> on your keyboard,
+As with other keys, when you press <kbd>Enter</kbd> or <kbd>↵</kbd> or on Macs, <kbd>Return</kbd> on your keyboard,
 your computer encodes this input as a character.
 Different operating systems use different character(s) to represent the end of a line.
 (You may also hear these referred to as newlines or line breaks.)
@@ -111,8 +111,8 @@ It is possible to reconfigure the text editor for Git whenever you want to chang
 ## Exiting Vim
 
 Note that Vim is the default editor for many programs. If you haven't used Vim before and wish to exit a session without saving
-your changes, press <kbd>Esc</kbd> then type `:q!` and hit <kbd>Enter</kbd> or <kbd>↵</kbd> or on Macs, <kbd>Return</kbd>.
-If you want to save your changes and quit, press <kbd>Esc</kbd> then type `:wq` and hit <kbd>Enter</kbd> or <kbd>↵</kbd> or on Macs, <kbd>Return</kbd>.
+your changes, press <kbd>Esc</kbd> then type `:q!` and press <kbd>Enter</kbd> or <kbd>↵</kbd> or on Macs, <kbd>Return</kbd>.
+If you want to save your changes and quit, press <kbd>Esc</kbd> then type `:wq` and press <kbd>Enter</kbd> or <kbd>↵</kbd> or on Macs, <kbd>Return</kbd>.
 
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
@@ -161,7 +161,7 @@ Let's close the file without making any additional changes.  Remember, since typ
 issues, it's safer to view the configuration with:
 
 ```bash
-$ git config --list
+$ git config --list --global
 ```
 
 And if necessary, change your configuration using the

diff --git a/03-create.md b/03-create.md
@@ -67,19 +67,6 @@ including the tracked files and sub-directories located within the project's dir
 If we ever delete the `.git` subdirectory,
 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#default-git-branch-naming) for more information on this change.
-
-```bash
-$ git checkout -b main
-```
-
-```output
-Switched to a new branch 'main'
-```
-
 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

diff --git a/04-changes.md b/04-changes.md
@@ -27,11 +27,10 @@ You should be in the `recipes` directory.
 $ cd ~/Desktop/recipes
 ```
 
-Let's create a file called `guacamole.md` that contains the basic structure to
-have a recipe.
+Let's create a file called `guacamole.md` that contains the basic structure of a recipe.
 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.html#which-editor) 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 steps 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 guacamole.md
@@ -40,11 +39,12 @@ $ nano guacamole.md
 Type the text below into the `guacamole.md` file:
 
 ```output
-# Ingredients
-# Instructions
+# Guacamole
+## Ingredients
+## Instructions
 ```
 
-Let's first verify that the file was properly created by running the list command (`ls`):
+Save the file and exit your editor. Next, let’s verify that the file was properly created by running the list command (`ls`):
 
 ```bash
 $ ls
@@ -54,15 +54,16 @@ $ ls
 guacamole.md
 ```
 
-`guacamole.md` contains a single line, which we can see by running:
+`guacamole.md` contains three lines, which we can see by running:
 
 ```bash
 $ cat guacamole.md
 ```
 
 ```output
-# Ingredients
-# Instructions
+# Guacamole
+## Ingredients
+## Instructions
 ```
 
 If we check the status of our project again,
@@ -201,11 +202,12 @@ $ cat guacamole.md
 ```
 
 ```output
-# Ingredients
-- avocado
-- lemon
-- salt
-# Instructions
+# Guacamole
+## Ingredients
+* avocado
+* lemon
+* salt
+## Instructions
 ```
 
 When we run `git status` now,
@@ -219,7 +221,7 @@ $ git status
 On branch main
 Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
-  (use "git checkout -- <file>..." to discard changes in working directory)
+  (use "git restore <file>..." to discard changes in working directory)
 
 	modified:   guacamole.md
 
@@ -246,12 +248,13 @@ diff --git a/guacamole.md b/guacamole.md
 index df0654a..315bf3a 100644
 --- a/guacamole.md
 +++ b/guacamole.md
-@@ -1,2 +1,5 @@
- # Ingredients
-+- avocado
-+- lemon
-+- salt
- # Instructions
+@@ -1,3 +1,6 @@
+ # Guacamole
+ ## Ingredients
++* avocado
++* lemon
++* salt
+ ## Instructions
 ```
 
 The output is cryptic because
@@ -273,15 +276,14 @@ If we break it down into pieces:
 After reviewing our change, it's time to commit it:
 
 ```bash
-$ git commit -m "Add basic guacamole's ingredients"
-$ git status
+$ git commit -m "Add ingredients for basic guacamole"
 ```
 
 ```output
 On branch main
 Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
-  (use "git checkout -- <file>..." to discard changes in working directory)
+  (use "git restore <file>..." to discard changes in working directory)
 
 	modified:   guacamole.md
 
@@ -294,11 +296,11 @@ Let's fix that:
 
 ```bash
 $ git add guacamole.md
-$ git commit -m "Add basic guacamole's ingredients"
+$ git commit -m "Add ingredients for basic guacamole"
 ```
 
 ```output
-[main 34961b1] Add basic guacamole's ingredient
+[main 34961b1] Add ingredients for basic guacamole
  1 file changed, 3 insertions(+)
 ```
 
@@ -357,11 +359,12 @@ $ cat guacamole.md
 ```
 
 ```output
-# Ingredients
-- avocado
-- lime
-- salt
-# Instructions
+# Guacamole
+## Ingredients
+* avocado
+* lime
+* salt
+## Instructions
 ```
 
 ```bash
@@ -373,13 +376,14 @@ diff --git a/guacamole.md b/guacamole.md
 index 315bf3a..b36abfd 100644
 --- a/guacamole.md
 +++ b/guacamole.md
-@@ -1,5 +1,5 @@
- # Ingredients
- - avocado
--- lemon
-+- lime
- - salt
- # Instructions
+@@ -1,6 +1,6 @@
+ # Guacamole
+ ## Ingredients
+ * avocado
+-* lemon
++* lime
+ * salt
+ ## Instructions
 ```
 
 So far, so good:
@@ -409,13 +413,14 @@ diff --git a/guacamole.md b/guacamole.md
 index 315bf3a..b36abfd 100644
 --- a/guacamole.md
 +++ b/guacamole.md
-@@ -1,5 +1,5 @@
- # Ingredients
- - avocado
--- lemon
-+- lime
- - salt
- # Instructions
+@@ -1,6 +1,6 @@
+ # Guacamole
+ ## Ingredients
+ * avocado
+-* lemon
++* lime
+ * salt
+ ## Instructions
 ```
 
 it shows us the difference between
@@ -460,7 +465,7 @@ commit 34961b159c27df3b475cfe4415d94a6d1fcd064d
 Author: Alfredo Linguini <[email protected]>
 Date:   Thu Aug 22 10:07:21 2013 -0400
 
-    Add basic guacamole's ingredients
+    Add ingredients for basic guacamole
 
 commit f22b25e3233b4645dabd0d81e651fe074bd8e73b
 Author: Alfredo Linguini <[email protected]>
@@ -530,7 +535,7 @@ $ git log --oneline
 
 ```output
 005937f (HEAD -> main) Modify guacamole to the traditional recipe
-34961b1 Add basic guacamole's ingredients
+34961b1 Add ingredients for basic guacamole
 f22b25e Create a template for recipe
 ```
 
@@ -546,7 +551,7 @@ $ git log --oneline --graph
 
 ```output
 * 005937f (HEAD -> main) Modify guacamole to the traditional recipe
-* 34961b1 Add basic guacamole's ingredients
+* 34961b1 Add ingredients for basic guacamole
 * f22b25e Create a template for recipe
 ```
 
@@ -571,21 +576,13 @@ Two important facts you should know about directories in Git.
   Note, our newly created empty directory `cakes` does not appear in
   the list of untracked files even if we explicitly add it (*via* `git add`) to our
   repository. This is the reason why you will sometimes see `.gitkeep` files
-  in otherwise empty directories. Unlike `.gitignore`, these files are not special
-  and their sole purpose is to populate a directory so that Git adds it to
-  the repository. In fact, you can name such files anything you like.
+  in otherwise empty directories. The sole purpose of `.gitkeep` files is to populate a directory so that Git adds it to the repository. The name `.gitkeep` is just a convention, and in fact, you can name these files anything you like.
 
 2. If you create a directory in your Git repository and populate it with files,
-  you can add all files in the directory at once by:
-
-  ```bash
-  git add <directory-with-files>
-  ```
-
-  Try it for yourself:
+  you can add all the files in the directory at once by referring to the directory in your `git add` command. Try it for yourself:
 
   ```bash
-  $ touch cakes/brownie cakes/lemon_drizzle
+  $ touch cakes/brownie_cakes/lemon_drizzle
   $ git status
   $ git add cakes
   $ git status
@@ -694,10 +691,11 @@ $ cat guacamole.md
 ```
 
 ```output
-# Ingredients
-- avocado (1.35)
-- lime (0.64)
-- salt (2)
+# Guacamole
+## Ingredients
+* avocado (1.35)
+* lime (0.64)
+* salt (2)
 ```
 
 ```bash
@@ -707,9 +705,9 @@ $ cat groceries.md
 
 ```output
 # Market A
-- avocado: 1.35 per unit.
-- lime: 0.64 per unit
-- salt: 2 per kg
+* avocado: 1.35 per unit.
+* lime: 0.64 per unit
+* salt: 2 per kg
 ```
 
 Now you can add both files to the staging area. We can do that in one line: