This page explains how to set up Git (popular open source version control software), and GitHub (a popular online Git repository manager owned by Microsoft). Repository is simply the term used to describe a coding project in a version control system. All of your practical code will be stored in one repository, and your two assessments will each be stored in their own independent repositories . It is important to recognise that these are completely unrelated - you can use Git fine without GitHub (but you can’t use GitHub without Git).

Both of these are standard in the programming industry, and employers will normally expect you to have a working knowledge of Git (including remote repositories like GitHub) before they hire you.

This page includes setup instructions for three different scenarios (please make sure you use the right one!):

• Setting up Git in a University Computer Lab
• Setting up Git on your own Windows Machine
• Setting up Git on your own Mac

It also includes some reminders for Git usage:

• Git Cheatsheet
  • Git Usage
  • Getting out of trouble with Git

Further information on generating an SSH Key Pair (for Mac, Windows and Linux) and adding a new SSH key to your GitHub account is availabile on from Github, but please be aware that the information from the GitHub website will not work in the University computer labs.

Setting Up Git in a University Computer Lab

Here are the steps to set up Git in the computer lab:

1. Set up an account on GitHub with the username gis-[student number], for example, if you had student number 123456789, then your user account would be gis-123456789. Please do this even if you already have another GitHub account.

2. Open and log in to Apps Anywhere and select Git - this will open an ugly, old fashioned looking software window, which you can safely ignore.

3. Now, go into Start → Programs → Git (which will have appeared when you loaded Git from Apps Anywhere) and select Git Bash, a black command window should open.

4. The first step is to find a way for GitHub to authenticate you (instead of a username and password) when you interact with it via Git. This is achieved using an SSH Key Pair - which you can learn about here if interested, but for now it is sufficient to know that it is a pair of files containng random characters, one of which goes on your computer (the private key) and one of which goes on GitHub (the public key) - if you have the matching public key to GitHub’s private key, then you are authenticated!

   To generate a SSH key, Right Click → Paste, not Ctrl+V! the following into Git Bash and press Enter:

   ssh-keygen -t ed25519 -C "GISLabs" -f /p/.ssh/id_ed_25519
   

   It will then ask you to enter a passphrase, type nothing and just press Enter. Then press Enter again to confirm. If it works, you should get a message roughly (but not exactly) like this:

   Generating public/private ed25519 key pair.
   Created directory '/p/.ssh'.
   Enter passphrase for "/p/.ssh/id_ed_25519" (empty for no passphrase):
   Enter same passphrase again:
   Your identification has been saved in /p/.ssh/id_ed_25519
   Your public key has been saved in /p/.ssh/id_ed_25519.pub
   The key fingerprint is:
   SHA256:hbH7vk832gOUyGI3Or0z5r1aI+i79Rx380LrbEr8XOg GIS Labs
   The key's randomart image is:
   +--[ED25519 256]--+
   |                 |
   |        . .      |
   |       . + .     |
   |      . +So .    |
   |     . o + .     |
   |      +oB= +     |
   |      + Bo&o=    |
   |      o+ +B-Eo   |
   |                 |
   +----[SHA256]-----+txt
   

5. Now, you have generated your keys, we need to give the public key to GitHub. Return to GitHub in your web browser, click on your profile image in the top-right corner of the screen and select Settings:

   

   In settings, select SSG and GPG Keys from the menu on the left:

   

   Then select the Green New SSH Key button. You should now see this screen:

   

   Run this command to reveal your public key…

   cat /p/.ssh/id_ed25519.pub
   

   Which should look something like this:

   ssh-ed25519 AAAAC3NzoC1lZDI1NTE5ACCAIFw+WLCxF73MaDKJ64lSZeDpNm2PH3GDOEaXNfBu2HjB GISLabs
   

   Highlight it using your mouse and Right Click → Copy (not Ctrl+C) it onto your clipboard, then Paste it into the Key box on GitHub. THn fill in the Title box to GIS Lab, and click the green Add SSH Key button to finish:

   

   If all has gone to plan, you should not be able to see it listed in your SSH & GPG Keys page:

   

6. Once that is done, Right Click → Paste the following lines one by one into Git Bash (replace 123456789 with your student ID number, and your.name@postgrad.manchester.ac.uk with your UoM email address) and press Enter after each one:

   git config --global user.name "123456789"
   git config --global user.email "your.name@postgrad.manchester.ac.uk"
   git config --global core.sshCommand "ssh -i /p/.ssh/id_ed_25519"
   

7. Once you have done that, congratulations! You have set up Git in the labs and and linked it to your GitHub profile. These changes will follow you around any machine and computer lab using the P drive, so you should have no need to do this process again!

Setting up Git on your own Windows machine

Here are the steps to set up Git on your own Windows machine:

1. Set up an account on GitHub with the username gis-[student number], for example, if you had student number 123456789, then your user account would be gis-123456789. Please do this even if you already have another GitHub account.

2. Install the correct version of Git for your machine (probably x64 Setup if you aren’t sure).

3. Now, in the search bar (on the Taskbar at the bottom) type Git Bash and open it. A black command window should open.

4. The first step is to find a way for GitHub to authenticate you (instead of a username and password) when you interact with it via Git. This is achieved using an SSH Key Pair - which you can learn about here if interested, but for now it is sufficient to know that it is a pair of files containong random characters, one of which goes on your computer (the private key) and one of which goes on GitHub (the public key) - if you have the matching public key to GitHub’s private key, then you are authenticated!

   To generate a SSH key, Right Click → Paste, not Ctrl+V! the following into Git Bash and press Enter:

   ssh-keygen -t ed25519 -C "MyWindows"
   

   It will then ask you about the location to save it (press Enter to accept the default) and to enter a passphrase (type nothing and just press Enter). Then press Enter again to confirm. If it works, you should get a message roughly (but not exactly) like this:

   Generating public/private ed25519 key pair.
   Created directory '.ssh'.
   Enter passphrase for ".ssh/id_ed_25519" (empty for no passphrase):
   Enter same passphrase again:
   Your identification has been saved in .ssh/id_ed_25519
   Your public key has been saved in .ssh/id_ed_25519.pub
   The key fingerprint is:
   SHA256:hbH7vk832gOUyGI3Or0z5r1aI+i79Rx380LrbEr8XOg GIS Labs
   The key's randomart image is:
   +--[ED25519 256]--+
   |                 |
   |        . .      |
   |       . + .     |
   |      . +So .    |
   |     . o + .     |
   |      +oB= +     |
   |      + Bo&o=    |
   |      o+ +B-Eo   |
   |                 |
   +----[SHA256]-----+txt
   

5. Now, you have generated your keys, we need to give the public key to GitHub. Return to GitHub in your web browser, click on your profile image in the top-right corner of the screen and select Settings:

   

   In settings, select SSG and GPG Keys from the menu on the left:

   

   Then click the green New SSH Key button on the top right of the screen. You should now see this screen:

   

   Copy and Right Click → Paste (not Ctrl+V) this command into Git Bash and press Enter to reveal your public key:

   cat .ssh/id_ed25519.pub
   

   Which should look something like this:

   ssh-ed25519 AAAAC3NzoC1lZDI1NTE5ACCAIFw+WLCxF73MaDKJ64lSZeDpNm2PH3GDOEaXNfBu2HjB MyWindows
   

   Highlight it using your mouse and Right Click → Copy (not Ctrl+C) it onto your clipboard, then Paste it into the Key box on GitHub. THn fill in the Title box to GIS Lab, and click the green Add SSH Key button to finish:

   

   If all has gone to plan, you should not be able to see it listed in your SSH & GPG Keys page:

   

6. Once that is done, Right Click → Paste the following lines one by one into Git Bash (replace 123456789 with your student ID number, and your.name@postgrad.manchester.ac.uk with your UoM email address) and press Enter after each one:

   git config --global user.name "123456789"
   git config --global user.email "your.name@postgrad.manchester.ac.uk"
   

7. Once you have done that, congratulations! You have set up Git on your machine and and linked it to your GitHub profile. These changes will follow you around any machine and computer lab using the P drive, so you should have no need to do this process again!

Setting up Git on your own Mac machine

Here are the steps to set up Git on your own Windows machine:

1. Set up an account on GitHub with the username gis-[student number], for example, if you had student number 123456789, then your user account would be gis-123456789. Please do this even if you already have another GitHub account.

2. Now, open Applications → Utilities → Terminal (or just search for Terminal in Spotlight) and open it.

3. The first step is to find a way for GitHub to authenticate you (instead of a username and password) when you interact with it via Git. This is achieved using an SSH Key Pair - which you can learn about here if interested, but for now it is sufficient to know that it is a pair of files containong random characters, one of which goes on your computer (the private key) and one of which goes on GitHub (the public key) - if you have the matching public key to GitHub’s private key, then you are authenticated!

   To generate a SSH key, Right Click → Paste, not Ctrl+V! the following into Git Bash and press Enter:

   ssh-keygen -t ed25519 -C "MyMac"
   

   It will then ask you to enter a passphrase, type nothing and just press Enter. Then press Enter again to confirm. If it works, you should get a message roughly (but not exactly) like this:

   Generating public/private ed25519 key pair.
   Created directory '.ssh'.
   Enter passphrase for ".ssh/id_ed_25519" (empty for no passphrase):
   Enter same passphrase again:
   Your identification has been saved in .ssh/id_ed_25519
   Your public key has been saved in .ssh/id_ed_25519.pub
   The key fingerprint is:
   SHA256:hbH7vk832gOUyGI3Or0z5r1aI+i79Rx380LrbEr8XOg GIS Labs
   The key's randomart image is:
   +--[ED25519 256]--+
   |                 |
   |        . .      |
   |       . + .     |
   |      . +So .    |
   |     . o + .     |
   |      +oB= +     |
   |      + Bo&o=    |
   |      o+ +B-Eo   |
   |                 |
   +----[SHA256]-----+txt
   

4. Now, you have generated your keys, we need to give the public key to GitHub. Return to GitHub in your web browser, click on your profile image in the top-right corner of the screen and select Settings:

   

   In settings, select SSG and GPG Keys from the menu on the left:

   

   Then click the green New SSH Key button on the top right of the screen. You should now see this screen:

   

   Run this command to reveal your public key…

   cat .ssh/id_ed25519.pub
   

   Which should look something like this:

   ssh-ed25519 AAAAC3NzoC1lZDI1NTE5ACCAIFw+WLCxF73MaDKJ64lSZeDpNm2PH3GDOEaXNfBu2HjB MyMac
   

   Highlight it using your mouse and Copy it onto your clipboard, then Paste it into the Key box on GitHub. Fill in the Title box to whatever value you used for MyMac, and click the green Add SSH Key button to finish:

   

   If all has gone to plan, you should not be able to see it listed in your SSH & GPG Keys page:

   

5. Once that is done, Right Click → Paste the following lines one by one into Git Bash (replace 123456789 with your student ID number, and your.name@postgrad.manchester.ac.uk with your UoM email address) and press Enter after each one:

   git config --global user.name "123456789"
   git config --global user.email "your.name@postgrad.manchester.ac.uk"
   

6. Once you have done that, congratulations! You have set up Git on your machine and and linked it to your GitHub profile. These changes will follow you around any machine and computer lab using the P drive, so you should have no need to do this process again!

Git Cheatsheet

All of the below are commands to run in Git Bash (Windows) or Terminal (Mac). Note that these are only the commands that we use in the course, and only very basic examples of those commands. A much more comprehensive instruction is given in Chacon and Straub (2014).

Git Usage

Clone a repository

git clone git@github/user/repo.git

Check the status of a git repository

git status

Check the log of previous commits in a git repository

git log

Add one or more files to a repository / stage existing files for commit

git add file1.py file2.py

Add all files to a repository / stage all new/changed files for commit

git add .

Commit staged files

git commit -m "message describing changes"

Commit all tracked files (no need to add)

git commit -a -m "message describing changes"

Push commits to remote repository

git push origin main

Commit and push in one line

git commit -a -m "message describing changes" && git push origin main

Pull commits from a repository

git pull origin main

Getting out of trouble with Git

While you are getting used to it, you might find that you run into some trouble with Git. Here are some common issues and solutions to fix them:

You have made some modifications that you regret - you want to revert back to the last commit

Easily done:

git restore file.py

You have staged a file that you don’t want to track

Unstage it with this:

git restore --staged file.py

You are tracking a file (that has already been committed) but now want to remove it from the repository

Make git stop tracking it with this:

git rm --cached file.py

You made a commit that you regret - you want to revert to the previous commit

Again easy (note that the simbol is ~, not -!). If you want to go back a different number of commits, you can do so by changing the number

git reset --hard HEAD~1

Your local repository gets out of sync with the remote

If you are working on a remote from multiple machines, you need to remember to push each time you finish and pull before you start to keep everything in sync. If you forget this, your repositories will get out of sync and you will get an error next time you try to push or pull. There are a few things to try here:

You can either reset your local repository to match the remote (losing any local modifications)…

git fetch --all
git reset --hard origin/main

…or reset your local repository to match the remote (saving any local changes by reverting them into unstaged changes)…

git fetch --all
git reset --soft origin/main

…or overwrite your remote repository to match the local one (losing any changes that were pushed there):

git push --force origin master

Think carefully before doing anything that will lose your code - and please do take the time to ask if you aren’t sure! Remember that your Git History is an important part of the marking criteria for your assessments, so it is vitally important that you do not delete your entire history!!!