Summary and Setup

What We Will Try to Do

Begin to understand and use the Unix shell, Git and Codeberg. You will not be an expert by the end of the class. You will probably not even feel very comfortable using Git. This is okay. We want to make a start but, as with any skill, using Git takes practice. In this lesson we use Git from the Unix shell. No previous experience with the shell is needed: the first two episodes cover everything you need to know.

Workshop formats

This lesson can be taught in two formats:

  • Half-day workshop (4 hours): episodes 1–6. You learn to navigate the shell and work with files, track changes with Git and share your work on Codeberg.
  • Lunch-to-lunch workshop (1.5 days): all episodes. In addition, you learn how to manage a project with issues and how to contribute to other people’s projects with forks, pull requests and reviews in the Codeberg web interface.

Learning objectives

After the half-day workshop, you will be able to …

  1. apply the Unix shell to navigate the file system and to create, view, rename, copy and delete files and folders.
  2. apply file naming conventions under guidance, using the example of your own project folder.
  3. explain the relevance and benefits of versioning for your work.
  4. explain Git as an example of distributed versioning software and how it relates to hosting platforms such as Codeberg.
  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.
  6. apply Git and Codeberg to share your work: connect a local repository to a remote one and exchange changes with push and pull.
  7. explain best practices for the use of versioning software, such as meaningful commit messages and secure authentication with SSH keys.
  8. apply a README file under guidance as a method of documenting a project.
  9. explain the role of licences for the reusability of material published in a repository.

After the lunch-to-lunch workshop, you will additionally be able to …

  1. apply project management methods – issues, labels, milestones and project boards – to plan and track tasks in a Codeberg repository.
  2. apply Codeberg for collaborative work: propose changes to another person’s repository with a fork, a branch and a pull request.
  3. analyse proposed changes in a pull request collaboratively in a review.
  4. explain basic concepts of access control using the example of repository permissions (owner, collaborator, fork, protected branch).
  5. explain the relevance of transparency and traceability for research, using the history of commits, issues and pull requests as an example.

The learning objectives are based on the learning objectives matrix for research data management (LOM-RDM, version 3).

Be Excellent to Each Other

  • If you spot someone in the class who is struggling with something and you think you know how to help, please give them a hand. Try not to do the task for them: instead explain the steps they need to take and what these steps will achieve.

Be Patient With The Instructor and Yourself

  • This is a big group, with different levels of knowledge, different computer systems.
  • This isn’t your instructor’s full-time job (though if someone wants to pay them to play with computers all day they’d probably accept). They will do their best to make this session useful.
  • This is your session. If you feel we are going too fast, then please put up a pink sticky. We can decide as a group what to cover.
Prerequisite

Prerequisites

  1. Set up a Codeberg account (see Setup)
  2. Install Git on your own computer (on Windows, this includes the Git Bash shell, see Setup)

Installing Git and a shell

We use Git from a Unix shell, specifically Bash (Bourne Again Shell). Since several Carpentries lessons rely on Git, please see this section of the workshop template for instructions on installing Git for various operating systems.

Prerequisite

Opening the shell

  • Windows: Installing Git for Windows also installs Git Bash, a Bash shell for Windows. Open it by selecting Git Bash from the start menu (in the Git folder). CMD and PowerShell, the default shells on Windows, use different commands and won’t work with this lesson.

  • macOS: Open Terminal from /Applications/Utilities or with Spotlight Search. Since macOS Catalina, the default shell is zsh, which is very similar to Bash; everything in this lesson works in zsh, too. If you prefer, you can switch to Bash by entering bash followed by the enter key.

  • Linux: Look for Terminal in your applications. The default shell is usually Bash. If your machine is set up differently, you can start it by typing bash followed by the enter key.

To check that Git is installed, type the following in the shell and press enter:

BASH 

$ git --version

OUTPUT 

git version 2.47.0

Any recent version number is fine. If you encounter issues, the Carpentries has a Configuration Problems and Solutions wiki page that may help.

Creating a Codeberg Account

You will need an account for Codeberg to follow this lesson.

  1. Go to https://codeberg.org and follow the “Register” link at the top-right of the window.
  2. Follow the instructions to create an account. Your username will be part of the addresses of your repositories and websites (for example https://yourname.codeberg.page/), so choose it with care.
  3. Verify your email address with Codeberg.
  4. We recommend to configure two-factor authentication (see below).

Codeberg is a non-profit platform for free and open content. Please have a look at its Terms of Use before using it for your own projects.

Two-factor Authentication

Codeberg does not require two-factor authentication (2FA), but it is a good idea to enable it for extra security. You can use an authenticator app on your smartphone, like FreeOTP or Aegis, or a hardware security key like a Yubikey. The Codeberg documentation explains how to set it up.