Summary and Setup

Git Collaboration

Welcome to the Git Collaboration course material.

This course aims to help you develop a deeper understanding of how Git works to facilitate collaboration. It builds on foundational Git courses such as Software Carpentry: Git Novice and Git and GitHub through GitKraken : From Zero to Hero!.

The core idea around which the course is based is to improve your understanding of working with branches and how to make a clean Git history in terms of commits and pull requests which in turn makes it easier to collaborate and work on code with others (including your future self!).

The course is split into six episodes. The first three introduce the concepts of branches and how to navigate them and handle diverging branches and introduces the concept of atomic commits and keeping your commit history clean. The remaining three chapters introduce the concept of Git along with the Pre-Commit framework and how these can be leveraged in Continuous Integration.

Git


There are many Git clients (porcelains) out there and many Integrated Development Environments (IDEs) support Git actions and facilitate using the bewildering array of options, but this course teaches the Command Line Interface (CLI) to Git as it means we have a consistent interface to teach the principles that you can take away to your own choice of Git client. Below there are instructions for installing Git on each of the three most common operating systems.

Please complete these setup tasks before attending the course. If you have any issues getting setup please either contact an instructor in advance or arrive early and seek assistance from an instructor.

Install Git

As this is a course about using Git you will need to have it installed on your computer. If you’re already using Git then the chances are high you already have it installed or it may be integrated into your Integrated Development Environment (IDE).

For consistency across operating systems this course uses the Command Line Interface (CLI) to Git and instructions below will guide you through installation on different Operating Systems. The principles can be applied to any Git Porcelain (client) that you choose (e.g. GitKraken), including IDEs such as VSCode, PyCharm, RStudio and Emacs, although not all will support all of the functions introduced here (e.g. the RStudio Git interface is very basic).

You can use the official binary but we encourage you to use Git for Windows which includes the Bash shell and there are excellent instructions on how to install this on the Carpentries installation instructions for the Bash Shell (NB the Git instructions for Windows on this page direct the reader to the Bash Shell instructions as they are bundled together).

Git is not included in the MacOS distribution by default. The official instructions suggests using either Homebrew, MacPorts or Xcode.

Homebrew

BASH

brew install git

MacPorts

BASH

sudo port install git

Most GNU/Linux distributions will have Git installed by default. If not you can install it using the package manager for your distribution. This will vary between distributions but some common ones are shown below. They assume you have root (administrator) access to your system via sudo. If sudo is not configured but you have root access then su and remove the sudo prefix from the following commands.

Arch

BASH

sudo pacman -Syu git

Debian/Ubuntu

BASH

sudo apt-get install git

Fedora

BASH

sudo dnf install git

Gentoo

BASH

sudo emerge -av dev-vcs/git

GitHub


You will also need an account on GitHub. If you do not already have one please register, if you have an academic email address such as @<institute>.ac.uk or @<institute.edu> then registering with this address will give you access to a few more features.

SSH Keys


ESSENTIAL

You MUST generate an SSH key using a secure password, then add the public component to your GitHub account.

There is a detailed article on creating SSH keys under Linux and OSX that works with Git Bash too. It is recommended to use the newer ed25519 algorithm. In a terminal or Git Bash shell, you can do this using the following commands. You will be prompted to enter your password twice, make sure to enter a secure (i.e. long) password, password-less keys are insecure!, make sure you remember what the password is (Hint use a password manager!).

BASH

ssh-keygen -a 100 -t ed25519
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/neil/.ssh/id_ed25519):
Enter passphrase for "id_ed25519" (empty for no passphrase):
Enter same passphrase again:

As shown above, you will need to confirm the location that the SSH keys will be saved to (hit enter to select the default which will be ~/.ssh/id_ed25519) and then enter a secure passphrase (you will be asked to enter it twice to confirm you know what it is, do not forget it!).

This creates two files in the ~/.ssh/ directory by default, the private key (~/.ssh/id_ed25519') and the public key (~/.ssh/id_ed25519.pub). These are text files and it is the contents of the later that you need to add to GitHub (see next solution). You can view the contents of the ~/.ssh/id_ed25519.pub file that you need to copy to your GitHub account with.

BASH

cat ~/.ssh/id_ed25519.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIARcKip5cMGhQvOooF0sAFTvLAj8R7wz+7cPV9BndPtL neil@haldane

Once you have created your SSH key you need to copy it to your account, got to Settings > SSH and GPG Keys and click on the New SSH key button. Enter a name for your key, set the Key type to Authenticaion Key and paste your public key (the contents of the file ending in .pub) into the Key box then click the Add SSH key button.

You can test if you have setup your SSH key by running the following command which should produce similar output.

BASH

ssh -T git@github.com
Hi ns-rse! You've successfully authenticated, but GitHub does not provide shell access.

If you do not see the above successful authentication message please get in touch before the course starts.

Key Points

  • You should have Git installed on your computer and opening a Terminal (or Git Bash Shell on Windows) you should be able to type git and receive a summary of available commands.
  • You should have setup a GitHub account.
  • You should have created an SSH key and uploaded the public component to your GitHub Account (Settings > SSH and GPG Keys).