From f30e64244430e3ec94040199cd22dfc51639b934 Mon Sep 17 00:00:00 2001 From: Alex Ball Date: Tue, 31 Mar 2026 10:55:55 +0100 Subject: [PATCH 1/3] Update links and improve accessibility in Instructor Notes Some links were outdated, and some link texts went against good practice for accessibility (using the URL or obscure phrases like "this" or "this page"). I have also reworded the point about whitespace differences to make it a bit more logical. --- instructors/instructor-notes.md | 33 +++++++++++++++------------------ 1 file changed, 15 insertions(+), 18 deletions(-) diff --git a/instructors/instructor-notes.md b/instructors/instructor-notes.md index 93fdb0e9..07a22534 100644 --- a/instructors/instructor-notes.md +++ b/instructors/instructor-notes.md @@ -14,7 +14,7 @@ Known problems that learners encounter: ## Making a handout -To make a handout for this lesson, adapt/print from [https://librarycarpentry.org/lc-git/reference.html](https://librarycarpentry.org/lc-git/reference.html). +To make a handout for this lesson, adapt/print from the [Reference page](https://librarycarpentry.org/lc-git/reference.html). *** @@ -54,12 +54,14 @@ working in teams or not, because it is ## Teaching Notes -- Resources for "splitting" your shell so that recent commands remain in view: [https://github.com/rgaiacs/swc-shell-split-window](https://github.com/rgaiacs/swc-shell-split-window). +- Utility for "splitting" your shell so that recent commands remain in view: [Software Carpentry Shell Split Window](https://github.com/UCL-ARC/swc-shell-split-window). - Make sure the network is working *before* starting this lesson. - Drawings are particularly useful in this lesson: if you have a whiteboard, - use it to visualise and describe the [GitHub flow](https://guides.github.com/introduction/flow/). + use it to visualise and describe GitHub flow. + The [current documentation of GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow) is text-heavy, + so it might be easier to draw inspiration from the interactive guide "[Understanding the GitHub flow](https://web.archive.org/web/20200728161719/https://guides.github.com/introduction/flow/)" from 2020. - Version control is usually not the first subject in a workshop, so get learners to create a GitHub account after the session before. @@ -67,21 +69,19 @@ working in teams or not, because it is during Git configuration) will be viewable to the public by default. However, there are many reasons why a learner may not want their personal information viewable, and GitHub has [resources for keeping an email address - private](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address). + private](https://docs.github.com/en/account-and-profile/how-tos/email-preferences/setting-your-commit-email-address). -- If some learners are using Windows, there will inevitably be issues - merging files with different line endings. (Even if everyone's on - some flavor of Unix, different editors may or may not add a - newline to the last line of a file.) Take a moment to explain - these issues, since learners will almost certainly trip over them - again. If learners are running into line ending problems, GitHub - has a [page](https://help.github.com/en/articles/dealing-with-line-endings) that helps with troubleshooting. +- It is likely that learners will run into issues when merging files due to whitespace differences. + For example, a text editor might automatically add a newline to the last line of a file, causing an unexpected difference. + Conflicts can also arise due to Windows using different line endings from other operating systems. + Take a moment to explain these issues, since learners will almost certainly trip over them again. + GitHub provides guidance on [how to configure Git to handle line endings](https://docs.github.com/en/get-started/git-basics/configuring-git-to-handle-line-endings). -- We don't use a Git GUI in these notes because we haven't found one that +- We don't use a Git GUI in this lesson because we haven't found one that installs easily and runs reliably on the three major operating systems, and because we want learners to understand what commands are being run. That said, instructors should demo a GUI on their desktop at some point during - this lesson and point learners at [this page](https://git-scm.com/downloads/guis). + this lesson and point learners at the Git website's [list of available GUIs](https://git-scm.com/tools/guis). - Instructors should show learners graphical diff/merge tools like [DiffMerge](https://sourcegear.com/diffmerge/). @@ -93,9 +93,6 @@ working in teams or not, because it is - Further resources: - - [git-it](https://github.com/jlord/git-it-electron#git-it-desktop-app) is a self-paced command-line Git demo, - with [git-it-electron](https://github.com/jlord/git-it-electron) its GitHub Desktop successor. - - Try GitHub's [resources to learn Git](https://try.github.io/) or Codeacademy's [Learn Git](https://www.codecademy.com/learn/learn-git). + - [Git-it](https://github.com/jlord/git-it-electron#git-it-desktop-app) is a self-paced Git demo that runs as an app on your computer. + - Try GitHub's [resources to learn Git](https://learn.github.com/) or Codecademy's [Learn Git & GitHub](https://www.codecademy.com/learn/learn-git). - For instructors, [the Git parable](https://tom.preston-werner.com/2009/05/19/the-git-parable.html) is useful background reading. - - From cd3e6fdfec41b5770d89f1ec4a85ab011d013574 Mon Sep 17 00:00:00 2001 From: Alex Ball Date: Tue, 31 Mar 2026 11:15:23 +0100 Subject: [PATCH 2/3] Tidy formatting of Instructor Notes With the current template,

and
elements don't work well. These changes bring the page more in line with swcarpentry/git-novice. --- instructors/instructor-notes.md | 28 ++++++++++------------------ 1 file changed, 10 insertions(+), 18 deletions(-) diff --git a/instructors/instructor-notes.md b/instructors/instructor-notes.md index 07a22534..6c182195 100644 --- a/instructors/instructor-notes.md +++ b/instructors/instructor-notes.md @@ -2,24 +2,6 @@ title: Instructors' Guide --- -*** - -# Tips and Tricks - -Known problems that learners encounter: - -*Windows*: When using an outdated version of Windows OpenSSH, learners cannot set up the SSH connection to GitHub. SOLUTION: Update OpenSSH version. - -*** - -## Making a handout - -To make a handout for this lesson, adapt/print from the [Reference page](https://librarycarpentry.org/lc-git/reference.html). - -*** - -# General notes on Git - Using a software tool to handle the versions of your project files lets you focus on the more interesting/innovative aspects of your project. @@ -52,6 +34,16 @@ working in teams or not, because it is - a better way to collaborate than mailing files back and forth, and - a better way to share your code and other scientific work with the world. +## Troubleshooting Common Problems + +- When using an outdated version of Windows OpenSSH, learners cannot set up the SSH connection to GitHub. + + - Try updating their version of OpenSSH version. + +## Making a handout + +To make a handout for this lesson, adapt/print from the [Reference page](https://librarycarpentry.org/lc-git/reference.html). + ## Teaching Notes - Utility for "splitting" your shell so that recent commands remain in view: [Software Carpentry Shell Split Window](https://github.com/UCL-ARC/swc-shell-split-window). From 09a83ece8402ef979c194b114203e4b344c5e32d Mon Sep 17 00:00:00 2001 From: Alex Ball Date: Tue, 31 Mar 2026 11:24:55 +0100 Subject: [PATCH 3/3] Extend tip on how to troubleshoot line ending issues The new text comes from swcarpentry/git-novice. --- instructors/instructor-notes.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/instructors/instructor-notes.md b/instructors/instructor-notes.md index 6c182195..6f60c459 100644 --- a/instructors/instructor-notes.md +++ b/instructors/instructor-notes.md @@ -67,7 +67,8 @@ To make a handout for this lesson, adapt/print from the [Reference page](https:/ For example, a text editor might automatically add a newline to the last line of a file, causing an unexpected difference. Conflicts can also arise due to Windows using different line endings from other operating systems. Take a moment to explain these issues, since learners will almost certainly trip over them again. - GitHub provides guidance on [how to configure Git to handle line endings](https://docs.github.com/en/get-started/git-basics/configuring-git-to-handle-line-endings). + GitHub provides guidance on [how to configure Git to handle line endings](https://docs.github.com/en/get-started/git-basics/configuring-git-to-handle-line-endings); + the [section on refreshing a repository](https://docs.github.com/en/github/using-git/configuring-git-to-handle-line-endings#refreshing-a-repository-after-changing-line-endings) may be helpful if learners need to change the `core.autocrlf` setting after already having made one or more commits. - We don't use a Git GUI in this lesson because we haven't found one that installs easily and runs reliably on the three major operating systems, and