Summary and Schedule

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 the course is that by improving your understanding of working with branches and how to make your commits tidier and neater it makes it easier to understand pull requests and Git history 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 introduces how to customise the configuration of your Git repository and how to make informative and atomic commits which makes the history easier to read and understand. Once the concepts of clean history are complete the material moves onto discuss branches, how switch between branches, moving around the history of a branch, correcting commits made to the wrong branch and stashing work in progress. This foundation of how branches work is the basis the next episode which shows how to deal with diverging branches. The concept of Git hooks are then introduced along with the Pre-Commit framework. Finally examples of how to leverage Continuous Integration in your workflow are introduced.

The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor.

Setup

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.

Example Repository

This course uses a GitHub Template that you will, in small groups, create a copy of and collaborate on. Using this template and setting it up is part of the course, you do not need to set it up in advance.

Install Git

Discussion

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, including IDEs, 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 

pacman -Syu git

Debian/Ubuntu

BASH 

apt-get install git

Fedora

BASH 

dnf install git

Gentoo

BASH 

emerge -av dev-vcs/git

GitHub

Discussion

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.

You should generate an SSH keys and use a secure password when creating them, then add the public component to your GitHub account.

There are comprehensive instructions on using the Windows SSH client PuTTY to generate SSH keys.

There is a detailed article on creating SSH keys under Linux and OSX. It is recommended to use the newer ed25519 algorithm. In a terminal you can do this using the following commands.

BASH 

ssh-keygen -a 100 -t ed25519

This creates two files in the ~/.ssh/ directory, 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

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.

Conda Environments

Anaconda Licensing

It is important to fully understand and adhere to the Anaconda Licensing which permits the use of their software (including Miniconda) in educational and research environments only if there is no commercial benefit. If the work you undertake involves commercial collaboration you should seek alternative solutions for virtual environments (e.g. virtualenvwrapper).

Discussion

In order to teach this course we need some code that is version controlled and some tasks to complete. Python has been chosen as the language to fulfill that task. You do not need to know Python in order to complete the course, the code you need to use is all provided and can be copy and pasted.

However, you do need what is known as a “Virtual Environment” setup to be able to install various programmes and run the checks that are part of this course. To that end you should install Miniconda3 on your system prior to attending the course.

If you are already familiar with Python and Virtual Environments you can simply create a fresh virtual environment to use for the course.

Please follow the instructions at Installing Miniconda for your Operating System.

You will have to create a virtual environment to undertake the course. If you have installed Miniconda as described above you open a terminal (Windows use the Git Bash Shell) and create a Virtual Environment called git-collaboation.

BASH 

conda create --name git-collaboration python=3.11
conda activate git-collaboration