Instructor Notes

Using a software tool to handle the versions of your project files lets you focus on the more interesting/innovative aspects of your project.

Version control’s advantages
- It’s easy to set up
- Every copy of a Git repository is a full backup of a project and its history
- A few easy-to-remember commands are all you need for most day-to-day version control tasks
- Hosting services like Codeberg provide a web-based collaboration service
Two main concepts
- commit: a recorded set of changes in your project’s files
- repository: the history of all your project’s commits
Why use Codeberg?
- No need for a server: easy to set up
- Non-profit, community-run and hosted in the EU, built on free software (Forgejo)
- Everything learners practise transfers directly to GitHub, GitLab and institutional instances, which their colleagues may already be using

Overall

Version control might be the most important topic we teach, but Git is definitely the most complicated tool. However, Git is the basis of nearly all open software and research repository platforms (Codeberg, GitHub, GitLab, …), so the time and effort required to teach fundamental Git is justified and worthwhile.

Because of this complexity, we don’t teach novice learners about many interesting topics, such as branching, hashes, and commit objects.

Instead we try to convince them that version control is useful for researchers working in teams or not, because it is

a better way to “undo” changes,
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 Codeberg.
- Try updating their version of OpenSSH version.

Making a handout

To make a handout for this lesson, adapt/print from the Reference page.

Teaching Notes

Utility for “splitting” your shell so that recent commands remain in view: Software Carpentry 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 fork-and-pull-request workflow. The Codeberg documentation on pull requests and Git flow can serve as inspiration.
Version control is usually not the first subject in a workshop, so get learners to create a Codeberg account after the session before. Remind learners that the username and email they use for Codeberg (and setup 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. Codeberg lets them hide their email address on their profile and use a private noreply address for commits (see the account settings).
Codeberg Pages only publishes public repositories and needs a webhook (episode “Codeberg Pages”). The most common problems are a wrong target URL (it must end with /hello-world/) or a missing pages branch filter. Check “Recent deliveries” on the webhook page together with the learner.
Codeberg Pages does not render Markdown. If learners ask why the original Library Carpentry lesson uses index.md: GitHub Pages runs Jekyll, Codeberg Pages only serves files.
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. The Pro Git book explains how to configure Git to handle line endings with the core.autocrlf setting.
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 the Git website’s list of available GUIs.
Instructors should show learners graphical diff/merge tools like DiffMerge.
When appropriate, explain that we teach Git rather than CVS, Subversion, or Mercurial primarily because of its wide adoption and the many platforms built on it: CVS and Subversion are now seen as legacy systems, and Mercurial isn’t nearly as widely used in the sciences right now.
Further resources:
- Git-it is a self-paced Git demo that runs as an app on your computer.
- The Codeberg documentation covers everything shown in this lesson and more.
- For instructors, the Git parable is useful background reading.

What is Git/Codeberg?

Getting started with Git

Demonstrating how to edit a text file

When showing how to edit index.md for the first time, Nano is the most convenient editor to use – you don’t have to leave the shell and it should work for everyone – but few learners will be fully confident with it. Take them step-by-step through one of the two ways of saving and closing the file:

Ctrl + X to close the file; Y to save the file; Enter to keep the same filename.
Ctrl + O to save the file; Enter to keep the same filename; Ctrl + X to close the file.

You could also keep a file manager window open (e.g. File Explorer, Finder, Files/Nautilus, Dolphin) to demonstrate locating the file and opening it in a suitable GUI text editor. Look out for learners who need help with this.

Review

Running the review exercise over Zoom

If you are teaching this lesson over Zoom, you may find it preferable to run the review exercise in one large group instead of splitting out into breakout rooms. One way to adapt the exercise is to set up a shared online drawing board using a service such as Miro, and share the link so all the learners can access it.

Ask the learners to recall the commands and concepts they’ve used and add them to the board using, say, green sticky notes for Shell commands and yellow sticky notes for Git commands. Then use this as the basis for a quiz: ask the learners to explain what a command does, or describe an action and ask which command is needed. If you ask the learners to reply using the Zoom chat or Q&A, rather than verbally, it gives everyone a chance to answer.

As a next step, work together on some diagrams to illustrate key concepts such as commits and branches, the staging area, or how origin and cloned repositories relate. Use background shapes, arrows, lines and text as appropriate.

Finally, ask learners to work individually on their own sections of the drawing board; you could keep a topic back from the group activity specifically for this part of the exercise, or ask the learners to come up with their own versions of the collaborative drawings.