GitHub

• Forking a Git Repository
• Setting Up a Git Repository
• How to set up VS Code with git.arts.ac.uk
• Getting Started with Git and Github

Forking a Git Repository

A common way to run classes at the CCI is for your lecturer to manage homework through a main git repository that they update with new files weekly, and ask you to make a fork of it to complete the work. Once you have a fork of the repository set up properly, this can be a very efficient workflow, but it takes a bit of getting used to!

In order to follow these instructions, make sure that you have first gone through the process of creating a CCI Github account and setting it up locally.

Overview: what are we doing

Forked repositories are really useful as they allow the lecturer to update code in a single location every week, which students can then integrate into their own work.

The key to using forks correctly is to make sure that you are pushing changes to your repository, but pulling changes from their repository. (if you make edits online, you'll also need to pull from your remote too, but it's best to try and manage everything locally if you can). The eventual aim of what we're trying to achieve is illustrated by this diagram:

We'll work through getting to this in the steps below, starting from making the cloud-based fork.

Step 1: make a fork of the remote repository

This step should be completed in your browser. Navigate to the repository you want to fork, e.g. the one that your lecturer made, and click the 'fork' button. This will take you to a page that allows you to name your copy -- you can either change this, or leave it the same, it won't affect the function. If you have already made a fork, it will link you to your existing copy.

Once you have created the fork, it will take you to your copy of the repository. This should look the same as the original, but this one belongs to you! Note that the name of the person who owns the repository has changed, but it contains a link to the original repository underneath the main title.

Step 2: clone your fork locally

Next, you want to create a local copy of your fork. This is where you will edit the code to do your homework. It's important that you clone your repo, not the original one! That's because your one is the one you have permission to update and push to.

To make a local copy, navigate to the 'Code' tab and copy the 'SSH' version of the URL, not the HTTPS!

Open your terminal (if you are using Windows, you should use Git Bash here rather than Command Prompt), and navigate to the folder you want to create your repository in. Make sure you don't clone the repository inside an existing git repo -- this will cause you problems. The best way to check if you're in a git repo already is to type git status -- if it gives you an error like fatal! not a git repository then you know it's safe to clone things there.

In this instance, I'm going to clone my repository to Desktop:

so, the commands are:

cd where/you/want/repo
git clone git@git.arts.ac.uk:yourname/repo-name.git
cd repo-name

Step 3: add the original repository as an upstream branch

Now, you have a local copy of your code. You can add, commit and push to your fork of the repository, and this will work just like a repository that you made. However, if your lecturer is regularly publishing changes to your code, you will also want to link their repository as what's called the upstream repository, so you can regularly pull and incorporate their changes.

In order to do this, we want to look at the state of the remotes. The remote branches point to copies of the repository that exist online. You want the origin to be pointing to a repository that you own, and to have the upstream point to your lecturer's repository.

The origin is what git thinks of as the 'default' -- so when you type in git push or git pull without specifying a named repository, git will assume you mean that one.

To inspect your remote branches, type in the command git remote -v:

You should see 2 links, both to the origin repository. We want to keep these! We're going to add a new one.

On git.arts.ac.uk, navigate to the original repository, the one that belongs to your lecturer. Like before, copy the SSH url from the 'code' icon in the top right.

Navigate back to the same terminal window. Now type the following command (replacing the url). This will add a new remote to your local repository, called 'upstream'. Make sure you use your lecturer's repo here, not yours!:

git remote add upstream git@git.arts.ac.uk:your-lecturer/your-lecturers-repo.git

Run git remote -v again, and you should see something like the following:

At this point, we now have the setup shown in the diagram at the top of the page. When you want to integrate changes made by your lecturer, run the command:

git pull upstream main

If this doesn't work, you might want to check that the main branch of your lecturer's git repository is definitely called main -- some older versions of git use master. If that's the case, you would write:

git pull origin master

Bonus: general workflow advice

When working with git, it's always a good idea to commit and push your changes at the end of each working session (and every time you add a new feature), and then pull changes before starting to edit code when you are next working. This minimises the chances of conflicts and also makes sure everything is up to date. Working with forked repos is no different. Depending on whether you are also editing your online repo, or collaborating with anyone, you might want to leave out the second 'git pull'.

As such, each session will look like:

cd /path/to/repo
git status 			// see what's up, not always needed
git pull upstream main 		// pulls from your lecturer's repo
git pull			// pulls from your fork, not always needed

... edit your files, test things ... 

git add .			// stages your changes for commit
git commit -m "message" 	// commits with a commit message
git push			// pushes your changes to your fork

Setting Up a Git Repository

Git is a tool for versioning code. A git repository is a folder of files where changes made over time have been recorded. You might have encountered version control using software like Dropbox, Google Drive or Fusion360, all of which automatically keep records of changes to files. Git is designed specifically for versioning code, and is used ubiquitously in a professional software development context. If you've ever broken some code and wished you could go back to an earlier version, this is a classic use-case for git.

Git is distinct from Github, which is a website used to host and share git repositories, though the two are very often used together. Github is an extremely useful complement to git, which not only provides a smooth way to share and collaborate on code, but also allows free (!) hosting of websites via a service called Github Pages.

There are lots of great tutorials for using all of these tools, so this page is mostly a list of useful links with a broad description of principles.

Setting up Git on Your Computer

The first step is to download the git Command Line application -- there are versions for Windows, Mac and Linux. When interacting with git on a Mac or Linux computer, you will want to use the Terminal (sometimes called Shell, or Command Line on Linux). If you have a Windows computer, you will want to use Git Bash (the shell that you get when you download git) rather than Command Prompt for the tutorials linked below. (the reason for this is that Git Bash is a Unix-type shell, not a Windows shell -- the two have different sets of commands).

Installing git on Windows will get you to go through mulitple setup stages: it's fine to just go with the default for each, though it's a good idea to set your default branch to 'main' when prompted.

It is possible to use git via a GUI (a graphical interface that you click on, as opposed to a Terminal interface), Github Desktop is probably the best of these. I'd recommend trying to use the terminal (Command Line) version if you can, though, as through doing so you get a much better understanding of the process.

Initial Setup

When we use Git on a new computer for the first time, we need to configure a few things so run the follow commands in the terminal to set your name and and UAL email address.

git config --global user.name "Your Name"
git config --global user.email "yourname@arts.ac.uk"

If you are unfamiliar with the terminal then we suggest using VScode and becoming familiar with its inbuilt terminal which has clear instructions for its use. For further information on the Git setup process read Getting Started with Git.

Making a local Git Repository

A 'git repository' is a folder full of versioned files that lives on your computer. To turn ANY directory (folder) into a git repository navigate to that diretory (see Navigating the Filesystem with the Unix Shell )

cd path/to/folder
mkdir new-repository
cd new-repository

Once you have a folder set up, and you have navigated to it, run the following command:

git init  

The creates a hidden folder calleed .git in the directory which contians the git repository.

Save changes to your local Git Repository

Run the following command to save any change to files in the current directory to the local got repository. 'git add' tells git to save all the changes you made. 'git commit -m "some message"' saves a note or comment to those changes.

git add . -- tells git you'd like to save *all* the changes you made
git commit -m "some message" -- versions files with a message

Connecting with remote Git repositories on git.arts.ac.uk

If you are linking a local Git repository to a repository on git.arts.ac.uk for the first time you will need to make a git.arts.ac.uk account, generate an SSH key, and save it to your git arts account using the following instructions:

• Generate an SSH key on your computer. If you are on a Windows computer, you will want to run these commands in a Git Bash terminal. On a Mac or Linux, use Terminal (these screenshots are from a Mac but the commands will be the same)

  1. check whether you have any ssh keys already: Do this by running the command ls ~/.ssh in your Terminal. What this will do is list ssh keys if they exist. There are 2 possible outcomes from this step, which will affect what you do next:

     • Outcome 1 -- your terminal prints out 2 filenames, like id_rsa and id_rsa.pub, or id_ed25519 and id_ed25519.pub. If your Terminal looks like this then it means you have SSH keys already and you want to keep them! skip to step 3.
     • Outcome 2 -- your Terminal says something like No such file or directory, or prints a filename called known_hosts and nothing else. Go to step 2 -- you need to make an SSH key.

  2. create an SSH key if you didn't have one in the first step: To make an SSH key, we are going to use a command-line program called ssh-keygen. Make sure you don't already have an SSH key before running this (step 1) because it will overwrite old keys by default. To create the key, run the command ssh-keygen in your Terminal and press enter. It will launch a dialog, shown below: To create the key, press enter to accept each option. You don't need a passphrase, but you can set one if you like. When you see the randomart image (cute huh), the key has been completed.

  3. print your public SSH key to Terminal so we can use this in the next step Your public key is the keyfile that ends in .pub. It's either going to be called id_rsa.pub (by default it will be called this), though if your keys were called id_ed25519 in the first step it will be called id_ed25519.pub instead. Both will work. To print out your public key (we will want to copy it in the next stage of the process), use the concatenate command cat ~/.ssh/id_rsa.pub, as shown below: The part highlighted in blue is your key. You are going to want to copy the whole thing, including the bit that says ssh-rsa and your computer info at the end. Note that if the text at the start says BEGIN OPENSSH PRIVATE KEY then you've copied the wrong part of the key! Repeat the last step, and make sure you print the file that ends in .pub, not id_rsa

• Now, we are going to add the SSH key to your git.arts account so you can connect to the server.

  1. Login to git.arts.ac.uk (not github.com) using your UAL login:
  2. Go to https://git.arts.ac.uk/settings/keys, you can also navigate to this page by going to your account settings in the top right hand menu, and then selecting "SSH and GPG keys" from the right hand side of the settings menu. In the screenshot below you can see I already have a few keys, because I access my account from a lot of different computers -- you just need to add one!
  3. Click the green button to the right that says "New SSH key", it will open up a new page with some textboxes to paste a key. Take the key that we printed at the end of the previous stage, and paste it into the main box. In the top box, put the name of the computer you made this key on, so you can remember. It should look like this: Click 'Add SSH key', and you should see the new key appear in your SSH and GPG keys page.

• To connect your local repository to your remote repository, you will want to create a new remote repository first.

  1. To create a repository, navigate to the git.arts.ac.uk homepage (not github.com) and click the green 'New' button on the repositories menu on the left hand side. It will open a dialog asking for a name and description of the new repository. Give it a name and a description, and do not tick create a README or 'add .gitignore', as this will make it difficult to link to an existing repository. When you click 'Create Repository', it will bring you to the following page:
  2. Back in your Terminal, inside your local git repository, you will need to paste the 3 commands listed under ...or push an existing repository from the command line. Press enter, and it should push the files from your computer onto git.arts. When you reload the page, you should see a github repository with a bunch of files you just added.

Save changes to your remote Git Repository on git.arts.ac.uk

Be sure you have already created a remote Git repository on your git.arts.ac.uk account, the example asumes a remote repository called 'NameOfYourRepository'. Then after running 'git add' and 'git commit', 'git push' will upload and save your files to git.arts.ac.uk/NameOfYourRepository

git add . 
git commit -m "some message" 
git push origin main

A summary of core git commands:

git init   -- make the current folder into a git repository
git remote add origin git@git.arts.ac.uk:YourUsername/TheRepositoryName.git -- connect the local to a remote repository on git.arts.ac.uk 
git status -- what's up with my repository
git add . -- tells git you'd like to save *all* the changes you made
git commit -m "some message" -- versions files with a message
git push origin main -- pushes commits to github if it's been set up

Some usefull core unix commands:

These are really gonna make a difference to your life if you know how to use them. It's possible to do these things in the file browser too, but knowing how to do these in terminal will save you a lot of time!

cd -- change directory (folder) to the one you are currently in
touch new.txt -- make a new file called new.txt
ls -- list the files in the current directory(folder)
mkdir myfolder -- make a new directory (folder) called myfolder
clear -- clear the terminal screen
pwd -- print working directory so you know where you are

Making a website with Github Pages

If nothing else, Github provides a clean and effective way of setting up a website for free. Git also integrates with services like Netlify and Vercel, which allow for more advanced sites to be set up, but for a basic HTML or Jekyll site Pages is totally great.

TODO: Write more instructions for this

Further reading: merges, tooling, Github Actions

TODO: Write instructions for this

How to set up VS Code with git.arts.ac.uk

(a.k.a. GitHub Enterprise for UAL)

GitHub provides a version of its version control platform for big organisations, such as us, and is a separate entity to GitHub.com.

In order to access this ‘enterprise’ version from VS Code, we need to create an access token, and change VS Code settings to use ssh and then we can use this token and clone the code manually to begin with, using GitHub Desktop or the command line.

This is a necessity since we now have 2-factor authentication on all our UAL accounts, so we have to generate an access token.

In this tutorial I explain how to clone (download) the code to your local machine and open the code in VS Code and edit it (step 1), create an access code (step 2) and change the VS Code settings in order to commit and push the changed code back to git.arts.ac.uk (step 3).

Step 1

You can log in to GitHub enterprise easily with GitHub desktop, once you have done so, clone your repository to your local filesystem (or follow the command-line instructions here).

Now, open that folder in VS Code, it will read the git source data from the repo. You may have to allow VS Code permissions:

Edit your code in some way to test the whole procedure works.

Step 2

Create an access token by logging in to git.arts.ac.uk and navigate to your profile, then settings and select developer settings on the left:

Create a new access token and give it all the permissions that you want to give (I have given VS Code all of them). I called it VS Code access. This will be used instead of your password.

Now we have our token, we can copy it and use it when VS Code asks us for it. Copy it now and store it somewhere safe.

Step 3

We need to tell VS Code to use SSH to interface with git. You can find this in settings and searching for ‘github’ and change the setting for HTTPS to SSH.

Now let’s get VS Code to commit the changes and push them up to git.arts.ac.uk

Stage the change by clicking the + (1) symbol of the file, then comment the changes (2) and then click the commit button (3).

VS Code will ask for your username: Then your password, in the same place, where you paste your personal access key.

Volia. Your file should be now pushed up to git.arts.ac.uk

Getting Started with Git and Github

Many classes in the CCI will either require or encourage you to use git and github in your work. These can be complex and confusing at first, and how you use them depends a bit on what you need to do.

git vs github

The first distinction that's normally quite important to make is that git and github are related but different things.

git is a piece of software that lives on your computer. It is used for saving versions of files that you are working on -- this is called 'version control'. Git is used on one folder at a time -- a folder that is being versioned with git is called a git repository. There are many different ways to use this software -- one of these is the command line.

github is a website online. It's used to share git repositories, and has a bunch of tools to allow people to collaborate on code. It's not the only website people use to do this, but it's the main one and it's very popular.

what about github desktop, git.arts.ac.uk?

github desktop is a piece of software you can use to manage git repositories on your computer. It's by no means the only way to do this -- Visual Studio Code also has tools for managing git repositories, and some people use git from the command line. It's a way of using git that is graphical rather than text-based.

git.arts.ac.uk is a version of the Github website that is managed by the CCI. It is often used for classes, as it allows CCI students (but not anyone else) to access the files. If you have a github account, it will not work with git.arts.ac.uk (you need to use your UAL account instead), but otherwise repositories will work the same (e.g. github desktop and the command line will still work).

and github pages?

Github Pages is a web hosting service run by github.com, that allows you to turn a repository containing web-compatible code into a website. The website will update when you update the files in the git repository. This doesn't happen automatically -- if you want a Github Pages site you need to approve this in settings.

SUMMARY:

• github desktop does the same job as using git from the command line -- it runs locally on your computer and allows you to both version files, and pull repositories from online.
• github and git.arts.ac.uk are both websites that people use to share and collaborate on git repositories.

what is a repository?

A git repository is a folder full of files that are being versioned using git. Tools like Github are used to share these repositories! Each git repository you have should have its own folder.

There are lots of ways of checking whether a folder is a git repository -- git stores the

how should I use git?

The core thing that git and github are used for is keeping track of a changing set of files. How you use these tools can depend on whose files they are! If you are making changes to your teacher's files, that's going to work differently to working on files that just belong to you.

Below are some common use cases.

At each of these points, you should end up with 2 things -- a local repository on your computer, that you can edit and run, and a remote repository on github (or git.arts). These things will be related, and if you own the remote repository, you should be able to push to it.

git setup

If you want to use git from the command line, there are a couple of extra setup steps, including making an SSH key. If you plan to use git for many projects, or learn how to use git professionally, this is a good idea. There are instructions for this process here.

If you are just getting started, or only want to use git for a one-off, you can follow these instructions to set up and configure Github Desktop.

Make a new git repository online

Follow these instructions to create a new git repository and clone it locally.

Push existing code to an empty git repository

If you have some code that you wish to publish on github, the steps are as follows:

• make an empty git repository online (this is the remote!) -> do this by following the steps above, but make sure you do not create a README or any other files.
• initialise your code as a git repository (this is local)
• link the remote repository to your local repository
• push your local files to the online repository

There is a full run-down of these instructions here.

Cloning a git repository

This is for when you want a copy of someone's code, and you might want to edit it, but you don't need to publish the changes that you have made. This is quite a common way to test out other peoples' scripts and tools. It's simpler than forking as you are just making a copy.

You can clone repositories either using the command line:

Get the url of the repository from the green 'code' button to the right of the repository's page.

Navigate to the folder where you want to have the repository on your computer, then use the git clone command to clone it.

cd where/you/want/repo
git clone git@git.arts.ac.uk:yourname/repo-name.git
cd repo-name

Making a fork of a git repository

This is something you will want to do if you need to make and version changes to someone else's code. It's a really common thing to do for classes that require a code-based homework each week. I wrote a longer guide to doing this here that uses the command line -- there's also a tutorial here for doing the same thing with Github Desktop.