Merge branch 'main' into 71_pr_not_same_pull

config.yaml

@@ -70,6 +70,7 @@ episodes:
 - Break.md
 - 07-github.md
 - 08-github-interface.md
+- 09-github-history.md
 - 10-pull-requests.md
 - End.md
 - 10-open.md

episodes/01-basics.md

@@ -62,6 +62,88 @@ metadata make up a [repository](../learners/reference.md#repository).
 Repositories can be kept in sync across different computers, facilitating
 collaboration among different people.
 
+## Terminology
+
+This workshop may contain language that is new to you.
+The [Glossary](../learners/reference.md#glossary) section
+outlines key Git & GitHub terminology for your reference.
+
+::: instructor
+
+### Explain Key Terminology
+
+Take this opportunity to show the learners where the glossary can be found.
+Explain the difference between Git & GitHub using the glossary!
+Or if there is time to spare, the first challenge on this page
+gets the learners to use the glossary to explain the difference
+to a partner or write it down in their own words.
+
+:::
+
+### Distributed Version Control
+
+Git is an example of a
+[distributed version control](../learners/reference.md#glossary) system.
+This means that each collaborator has a copy of the entire repository.
+
+```mermaid
+---
+title: Distributed Version Control (e.g. Git)
+---
+flowchart TD
+    accDescr {A flowchart showing a remote server on GitHub and three local repository copies on collaborators computers. This is a distributed version control system as everyone has a copy of the entire repository and its history.}
+    subgraph "Remote Server (GitHub)"
+        r1[(Origin Repository)]
+    end
+    subgraph "<div style="margin-top: 14em">Computer 3</div>"
+        r2[(Repository)]
+        id2[Working Copy]
+    end
+    subgraph "<div style="margin-top: 14em">Computer 2</div>"
+        r3[(Repository)]
+        id3[Working Copy]
+    end
+    subgraph "<div style="margin-top: 14em">Computer 1</div>"
+        r4[(Repository)]
+        id4[Working Copy]
+    end
+    r1 -->|pull| r2 -.->|push| r1
+    r1 -->|pull| r3 -.->|push| r1
+    r1 -->|pull| r4 -.->|push| r1
+    r2 -->|checkout| id2 -.->|commit| r2
+    r3 -->|checkout| id3 -.->|commit| r3
+    r4 -->|checkout| id4 -.->|commit| r4
+```
+
+#### Centralised (FCM)
+
+FCM and SVN are examples of
+[centralised version control](../learners/reference.md#glossary) systems.
+Here there is only one repository on a central server.
+
+```mermaid
+---
+title: Centralised Version Control (e.g. SVN)
+---
+flowchart TD
+    accDescr {A flowchart showing a central remote server and three local working copies on collaborators computers.}
+    subgraph "Remote Server"
+        id1[(Central Repository)]
+    end
+    subgraph "<div style="margin-top: 5em">Computer 3</div>"
+        id2[Working Copy]
+    end
+    subgraph "<div style="margin-top: 5em">Computer 2</div>"
+        id3[Working Copy]
+    end
+    subgraph "<div style="margin-top: 5em">Computer 1</div>"
+        id4[Working Copy]
+    end
+    id1 -->|checkout| id2 -.->|commit| id1
+    id1 -->|checkout| id3 -.->|commit| id1
+    id1 -->|checkout| id4 -.->|commit| id1
+```
+
 :::::::::::::::::::::::::::::::::::::::::  callout
 
 ## The Long History of Version Control Systems
@@ -103,6 +185,16 @@ fcm ...
 
 :::::::::::::::::::::::::::::::::::::::  challenge
 
+Use the [Glossary](../learners/reference.md#glossary) to describe
+the difference between Git & GitHub in your own words.
+
+Share your description with other learners if you
+are comfortable doing so.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::  challenge
+
 ## Paper Writing
 
 - Imagine you drafted an excellent paragraph for a paper you are writing, but later ruin

episodes/04-changes.md

@@ -303,7 +303,7 @@ If we break it down into pieces:
   In particular,
   the `+` marker in the first column shows where we added a line.
 
-::: spoiler
+::: callout
 
 ### git difftool
 
@@ -318,13 +318,26 @@ The `-g` flag launches the default gui diff tool. To change defaults:
 
 ```bash
 git config --global diff.tool <tool>
-git config --global diff.guitool <tool>
-git config --global --add difftool.prompt false
+git config --global diff.guitool <gui-tool>
+git config --global difftool.prompt false
+git config --global difftool.guiDefault auto
 ```
 
-Where `<tool>` is your preferred diffing tool such as [meld](https://gnome.pages.gitlab.gnome.org/meld/).
+Where `<tool>` is a diffing tool such as Vim,
+`<gui-tool>` is your preferred graphical user interface
+diffing tool such as [meld](https://gnome.pages.gitlab.gnome.org/meld/).
 The third line disables the Git prompt which asks you to confirm
 whether to launch the diff for every changed file.
+The last line automatically detects support for launching the
+gui based tool and launches `<gui-tool>` preferentially
+over `<tool>`. With this set to auto there is no need to
+add the `-g` flag when running `git difftool`.
+
+To see a list of available tools run:
+
+```bash
+$ git difftool --tool-help
+```
 
 :::
 

episodes/05-history.md

@@ -132,11 +132,38 @@ $ git log --oneline --graph
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
+### A common alias for git log
+
+It is often useful to use the `--decorate`, `--oneline`, and `--graph`
+flags all at once.
+To avoid us having to write out the three flags each time we can set an alias:
+
+```bash
+$ git config --global alias.dog "log --decorate --oneline --graph"
+```
+
+This alias makes these two commands equivalent:
+
+```bash
+$ git dog
+$ git log --decorate --oneline --graph
+```
+
+`--decorate` ensures commits with reference names[^refs] are displayed
+when using older versions of git.
+
+[^refs]: [References](https://git-scm.com/book/ms/v2/Git-Internals-Git-References)
+in Git are user friendly links to specific commits.
+For instance `HEAD` is a reference to the latest commit on a branch.
+Programs with regular releases might add reference tags such as `v1.0`
+to a specific commit to mark a new release.
+These references can be used instead of a commit identifier such as `e48heu0`.
+
 ## Identifying Commits
 
 As we saw in the previous episode, we can refer to commits by their
 identifiers.  You can refer to the *most recent commit* of the working
-directory by using the identifier `HEAD`.
+directory by using the reference name `HEAD`.
 
 We've been adding small changes at a time to `forecast.md`, so it's easy to track our
 progress by looking, so let's do that using our `HEAD`s.  Before we start,

episodes/06-reverting-changes.md

@@ -161,11 +161,68 @@ Generally it is best to spot and revert mistakes before the commit stage.
 The table below summarises how to revert a change depending on where in the 
 commit process you are:
 
-| **To revert files you have ...** |     **git command**     |
-|:--------------------------------:|:-----------------------:|
-| modified                         | `$ git restore <files>` |
-| staged                           | `$ git reset <files>`   |
-| committed                        | `$ git revert <commit>` |
+| **To revert files you have ...** |         **git command**          |
+|:--------------------------------:|:--------------------------------:|
+| modified                         | `$ git restore <files>`          |
+| staged                           | `$ git restore --staged <files>` |
+| committed                        | `$ git revert <commit>`          |
+
+We have already practised restoring modified files.
+Now let's practise restoring staged changes.
+Go ahead and make a similar change like you did earlier
+to your `forecast.md`:
+
+```bash
+$ nano forecast.md
+$ cat forecast.md
+```
+
+```output
+# Forecast
+
+## Today
+
+Cloudy with a chance of sun.
+Mild temperatures around 16 °C.
+
+## Tomorrow
+
+Morning rainbows followed by light showers.
+Another ill-considered change.
+```
+
+Add the changes:
+
+```bash
+$ git add forecast.md
+```
+
+Now `git status` shows:
+
+```bash
+$ git status
+```
+
+```output
+On branch forecast
+Changes to be committed:
+  (use "git restore --staged <file>..." to unstage)
+	modified:   forecast.md
+```
+
+And we can use the hint to unstage our changes:
+
+```bash
+$ git restore --staged forecast.md
+```
+
+Our modifications to the `forecast.md` file have been unstaged
+and are now back in the working copy.
+We can restore these modifications fully with:
+
+```bash
+$ git restore forecast.md
+```
 
 :::::::::::::::::::::::::::::::::::::::  challenge
 

episodes/07-github.md

@@ -47,8 +47,26 @@ explanation of why the repository needs to be empty.
 
 ![](fig/github-create-repo-02.png){alt='The second step in creating a repository on GitHub: filling out the new repository form to provide the repository name, and specify that neither a readme nor a license should be created'}
 
+::: spoiler
+
+### Repository Visibility
+
+Here we have chosen to make our repository public.
+The visibility of your repository depends on which option you choose:
+
+- Private: only you
+- Internal (organisations only): read permissions to anyone in the organisation
+- Public: read permissions to anyone
+
+Some organisations will restrict the creation of public repositories
+so you may find their default is internal.
+If your project deals with sensitive material then create a private repository.
+
+:::
+
 As soon as the repository is created, GitHub displays a page with a URL and some
-information on how to configure your local repository:
+information on how to configure your local repository.
+Ignore the suggested commands for now as we will run these later.
 
 ![](fig/github-create-repo-03.png){alt='The summary page displayed by GitHub after a new repository has been created. It contains instructions for configuring the new GitHub repository as a git remote'}
 
@@ -125,6 +143,22 @@ talking about how they might be used for collaboration.
 
 ## 3\. SSH Background and Setup
 
+::: instructor
+
+Some learners may have set up an ssh key already.
+If they have a key with this name: `~/.ssh/id_ed25519_github`
+and can successfully authenticate with `ssh -T [email protected]`
+they can skip this section.
+
+If their ssh key name does not match the one above we **strongly**
+recommend they follow the instructions below.
+
+Those who are skipping this section can revisit the challenges
+in earlier episodes (yellow callouts with a lightning bolt)
+or read through the [discussion notes](../learners/discuss.md).
+
+:::
+
 Before you can connect to a remote repository, you need to set up a way for your computer to authenticate with GitHub so it knows it's you trying to connect to the remote repository.
 
 We are going to set up the method that is commonly used by many different services to authenticate access on the command line.  This method is called Secure Shell Protocol (SSH). SSH is a cryptographic network protocol that allows secure communication between computers using an otherwise insecure network.
@@ -318,6 +352,25 @@ Hi Eleanor! You've successfully authenticated, but GitHub does not provide shell
 
 Good! This output confirms that the SSH key works as intended. We are now ready to push our work to the remote repository.
 
+::: spoiler
+
+### Troubleshooting SSH Setup
+
+If your new key failed to connect you may need to alter your ssh config.
+
+1. Create the `~/.ssh/config` file if it doesn't exist
+2. Add the following to the file:
+
+```ssh-config
+Host github.com
+  IdentityFile ~/.ssh/id_ed25519_github
+```
+
+This explicitly states which key to use for github.com
+and is needed if you have many SSH keys already for other hosts.
+
+:::
+
 ## 4\. Push local changes to a remote
 
 Now that authentication is setup, we can return to the local repository.

episodes/09-branches.md

@@ -66,6 +66,23 @@ Your branch is up to date with 'origin/main'.
 nothing to commit, working tree clean
 ```
 
+::: spoiler
+
+### FCM Comparison
+
+`main` == `trunk`
+
+In an earlier episode we set our default branch
+to be called `main`.
+This is where our stable production code
+lives and is equivalent to `trunk`.
+
+We could have also named this branch `trunk` in Git.
+We chose `main` as it is a more common default branch name
+for Git and matches the default on GitHub.
+
+:::
+
 ## Creating Branches
 
 Our current repository looks something like this: