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