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

Learning objectives and the LOM-RDM

The learning objectives on the start page are based on the learning objectives matrix for research data management, version 3 (Petersen et al. 2025, English version: https://doi.org/10.5281/zenodo.15846806, German version: https://doi.org/10.5281/zenodo.15025246). Most objectives were adapted to the lesson by adding conditions, as suggested in section 4.6 of the matrix README. Objectives 1–9 are covered in the half-day workshop, 10–14 only in the lunch-to-lunch workshop.

# Objective LOM-RDM ID Bloom level Episodes
1 Apply the Unix shell to navigate the file system and to create, view, rename, copy and delete files and folders 02_015_0539 3 1, 2
2 Apply file naming conventions under guidance, using the example of their own project folder 02_006_0326 3 2
3 Explain the relevance and benefits of versioning for their work 02_008_0355, 02_008_0356 2 3
4 Explain Git as an example of distributed versioning software and how it relates to hosting platforms such as Codeberg 02_008_0368 2 3
5 Apply Git to track changes to files: create a repository, stage and commit changes, and inspect the status, differences and history of a repository 02_008_0365 3 4, 5
6 Apply Git and Codeberg to share their work: connect a local repository to a remote one and exchange changes with push and pull 02_008_0365 3 5
7 Explain best practices for the use of versioning software, such as meaningful commit messages and secure authentication with SSH keys 02_008_0369 2 5
8 Apply a README file under guidance as a method of documenting a project 03_001_0606 3 2, 4, 5
9 Explain the role of licences for the reusability of material published in a repository 05_003_0921 2 5
10 Apply project management methods – issues, labels, milestones and project boards – to plan and track tasks in a Codeberg repository 06_007_1175 3 7
11 Apply Codeberg for collaborative work: propose changes to another person’s repository with a fork, a branch and a pull request 02_008_0371 3 8
12 Analyse proposed changes in a pull request collaboratively in a review 02_015_0544 4 8
13 Explain basic concepts of access control using the example of repository permissions (owner, collaborator, fork, protected branch) 02_013_0502 2 7, 8
14 Explain the relevance of transparency and traceability for research, using the history of commits, issues and pull requests as an example 05_011_1033 2 7

Notes:

  • Objective 1 adapts “apply different programming environments and tools” to the Unix shell; objective 13 adapts “analyse programme code collaboratively” to the changes proposed in a pull request.
  • The matrix lists 02_008_0365 (“apply versioning software”) at level 2, although “apply” is a level 3 verb; we use level 3.
  • Most objectives are intended for the target groups master students, early career researchers and data stewards in the matrix; 02_008_0368, 02_008_0369, 02_008_0371, 02_013_0502, 06_007_1175 and 05_011_1033 only for early career researchers and data stewards.

Workshop formats and schedules

The lesson is designed for two formats. Times include breaks; the episode timings in the lesson are guidelines and add up to more than the available time in the half-day format, so keep an eye on the clock.

Make sure learners have installed Git and created a Codeberg account before the workshop (see Setup). Without that, the half-day format won’t fit into four hours.

Half-day workshop (4 hours): episodes 1–6

Time Duration Content
0:00 10 min Welcome, introductions, check that everybody can open a shell
0:10 20 min 1 Navigating the filesystem
0:30 25 min 2 Working with files and directories
0:55 10 min 3 What is Git/Codeberg?
1:05 25 min 4 Getting started with Git
1:30 15 min Break
1:45 75 min 5 Sharing your work (SSH setup takes time!)
3:00 10 min Break
3:10 25 min 6 Review
3:35 25 min Buffer, questions, where to go from here, feedback
4:00 End

The buffer is usually needed for the SSH setup in episode 5.

Lunch-to-lunch workshop (1.5 days): all episodes

Day 1, afternoon (e.g. 13:00–17:00):

Time Duration Content
13:00 15 min Welcome, introductions, check that everybody can open a shell
13:15 20 min 1 Navigating the filesystem
13:35 25 min 2 Working with files and directories
14:00 10 min 3 What is Git/Codeberg?
14:10 25 min 4 Getting started with Git
14:35 15 min Break
14:50 75 min 5 Sharing your work
16:05 10 min Break
16:15 25 min 6 Review
16:40 20 min Questions, feedback for day 1
17:00 End of day 1

Day 2, morning (e.g. 9:00–12:30):

Time Duration Content
9:00 15 min Recap of day 1 (add, commit, push, pull)
9:15 45 min 7 Managing a project with issues
10:00 15 min Break
10:15 50 min 8 Contributing with pull requests
11:05 10 min Break
11:15 50 min Practice: learners set up a repository for one of their own projects (README, licence, a few issues), or repeat the issue and pull request workflow with another partner
12:05 25 min Wrap-up, where to go from here, feedback
12:30 End, lunch

The two days are linked: on day 2 learners need the my-git-repo-<name> repository and SSH key from day 1. Remind them to bring the same computer.

Notes on the shell episodes

The shell episodes are taken from Library Carpentry: The Unix Shell (episodes “Navigating the filesystem” and “Working with files and directories”) and shortened to what learners need for the Git episodes: pwd, ls (including ls -a for the hidden .git directory), cd, mkdir, touch, cat/head/tail/less (git log uses less), mv, cp and rm. No data download is needed: in episode 2, learners create the directory my-git-repo-<name> on their Desktop and a README.md in it. This directory becomes the Git repository in episode 4, and README.md is its first commit.

The name of the repository contains the learner’s first name, so that the repositories of all learners have different names. This avoids confusion on Codeberg and when learners fork their partner’s repository in the lunch-to-lunch workshop. Check that everybody uses lower case letters and no spaces.

Make sure the README.md is still there at the start of episode 4 (learners shouldn’t delete it while practising rm).

Windows OneDrive Notes

On Windows, Microsoft OneDrive may appear in the home directory list. It might be called ‘OneDrive’ or have a local name appended, such as “OneDrive-campus”. The Desktop is often found inside the OneDrive directory, so cd Desktop may not work.

To check, using Git Bash:

BASH 

$ ls -la OneDrive*

Avoid creating Git repositories inside a folder synchronised by OneDrive (or similar services): the synchronisation can interfere with the files in the .git directory. If a learner’s Desktop is synchronised, let them create my-git-repo-<name> directly in their home directory (cd and then mkdir my-git-repo-<name>) and use ~/my-git-repo-<name> instead of ~/Desktop/my-git-repo-<name> later on.

Notes on the issues and pull request episodes

The episodes “Managing a project with issues” and “Contributing with pull requests” are adapted from the GitLab for Software Development in Teams lesson in the Carpentries Incubator (episodes “Issues” and “Merge Requests”) and rewritten for Codeberg.

  • Learners work in pairs and play two roles at the same time: author of an issue/pull request in their partner’s repository, and maintainer of their own repository. Make the role switches explicit, e.g. with a slide “Now in YOUR repository”.
  • Issues and pull requests share one numbering on Codeberg. The issue from episode 7 is usually #1, but if learners experimented before, it can be a higher number. Learners need to use the right number in Closes #....
  • Only people with write access can set labels, milestones and assignees. The issue author therefore can’t set them in their partner’s repository – this is intended and shows the reporter/maintainer split.
  • The “Projects” tab may be disabled in some repositories; it can be switched on in the repository settings.
  • The pull request episode works entirely in the Codeberg web interface (fork, new file on a new branch, pull request, review, update, merge); only the final git pull happens in the shell. When the pull request page opens, check together that it goes from the learner’s fork into main of the partner’s repository.
  • The terminology differs between platforms: pull request (Codeberg, GitHub) = merge request (GitLab). Mention this, as learners may use GitLab at their institution.

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).

  • The original Library Carpentry lesson has an episode on GitHub Pages. We left out websites (Codeberg Pages) to keep the workshop manageable for beginners: on Codeberg, publishing a site needs a pages branch and a webhook in the repository settings. If learners ask, point them to the Codeberg Pages documentation.

  • 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:

Navigating the filesystem

Instructor Note

For notes about OneDrive, see the Instructor Notes.


Working with files and directories

What is Git/Codeberg?

Getting started with Git

Demonstrating how to edit a text file

When showing how to edit README.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.


Sharing your work

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.


Managing a project with issues

Contributing with pull requests