Summary and Setup

Git With It

Welcome to the Git With It 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 centred is to improve your understanding of working with branches and how to ensure you have a clean and informative Git history in terms of commits and pull requests. This helps make it easier to collaborate and work on code with others (including your future self!) because the history of changes is easy to understand.

The course is split into six episodes. The first three introduce the concepts of branches and how to navigate them, handle diverging branches and introduces the concept of atomic commits to help keep your commit history clean. The remaining chapters introduce the concept of “hooks” along with the Pre-Commit framework and how these can be leveraged in Continuous Integration. The final chapter introduces, briefly, some other very useful features of Git that make working with it that little bit easier.

We hope you enjoy the course and find it useful. If you have any feedback or find errors with the content, even if its just a tpyo please consider creating an issue to let us know about it.

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.

Miniforge/Conda

We use the Miniforge virtual environment management system to install virtual environments and Git as it provides a consistent experience across operating systems.

Discussion

Follow the install instructions for your operating system to install Miniforge.

Download and execute the Windows installer. Follow the prompts, taking note of the option to “Create start menu shortcuts”. The most convenient and tested way to use the installed software (such as commands conda and mamba) is via the “Miniforge Prompt” installed to the start menu.

Once installed you should find the Miniforge Prompt in your Start menu.

BASH 

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"

BASH 

wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"

Then…

BASH 

bash Miniforge3-$(uname)-$(uname -m).sh

Answer the prompts for selecting an installation location. At the end of the installation you will see the following output and question…

BASH 

installation finished.
Do you wish to update your shell profile to automatically initialize conda?
This will activate conda on startup and change the command prompt when activated.
If you'd prefer that conda's base environment not be activated on startup,
   run the following command when conda is activated:

conda config --set auto_activate_base false

Note: You can undo this later by running `conda init --reverse $SHELL`

Proceed with initialization? [yes|no]
[no] >>> yes

Answer yes as it ensures that the conda base environment is activated each time you create

Callout

Unable to activate environment

If you are prompted to run conda init before conda activate and find this doesn’t work then its possible a key step was missed out, most likely answering yes to have your shell profile updated mentioned above. To rectify this the following might help…

BASH 

source activate base

Create a Virtual Environment

We now need to create a virtual environment and install Python, Git and OpenSSH within it.

Discussion

You should now create a virtual environment for the course and install Git and OpenSSH from the Conda-Forge channel.

BASH 

conda create --name git-with-it --channel conda-forge python git openssh

As the prompt suggests activate the environment…

BASH 

conda activate git-with-it

Check these are installed using the following commands

BASH 

which {git,ssh,ssh-keygen}

This will print out the path to each of the programmes git, ssh and ssh-keygen, the first part of the path will depend on your computer, but the last part of the output of each should miniforge/bin/git, miniforge/bin/ssh and miniforge/bin/ssh-keygen respectively. An example is shown below.

BASH 

 which {git,python,ssh,ssh-keygen}
/home/neil/miniforge3/bin/git
/home/neil/miniforge3/bin/python
/home/neil/miniforge3/bin/ssh
/home/neil/miniforge3/bin/ssh-keygen

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

Discussion

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 installed under the Conda/Miniforge install you should have made following the above instructions. 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! and 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 with the .pub extension 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.

Clone a repository

To undertake the work in this course you need to have a Git repository to work on. We will use the python-maths repository for this.

Discussion

Cloning python-maths

You should clone the python-maths repository before joining the first training session to the computer you will be using to undertake the work. As you have now setup SSH keys under your GitHub account you can

  • Navigate to python-maths (use Ctrl+click to open in a new tab).
  • Click on the green Code button.
  • On the Local tab select SSH
  • Use the Copy button to the right of git@github.com:FAIR2-for-research-software/python-maths.git to copy the SSH URL.

You can clone the repository with the following…

BASH 

git clone git@github.com:FAIR2-for-research-software/python-maths
Key Points

Prior to attending the course you should have…

  • Installed Miniforge on your computer.
  • Created a virtual environment called git-with-it and included both git and openssh in this environment.
  • Created an SSH key and uploaded the public component to your GitHub Account (Settings > SSH and GPG Keys).
  • Cloned the python-maths repository.