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