Versioning Code With Git

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 ) amnd 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 following the create a key section of the how to connect to the CCI server guide.
Login to git.arts.ac.uk and copy your ssh key to https://git.arts.ac.uk/settings/keys
- Select 'New SSH key', call it any name you want, and copy it into the 'key' field.
Create a new remote git repository by clicking the green 'new' button at git.arts.ac.uk
Then to connect your local repository to your remote repository run the following command in the terminal being sure to write in your username and the name of the remote repository:

$ git remote add origin git@git.arts.ac.uk:YourUsername/NameOfYourRepository.git

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:

1. git init   -- make the current folder into a git repository
2. git remote add origin git@git.arts.ac.uk:YourUsername/TheRepositoryName.git -- connect the local to a remote repository on git.arts.ac.uk 
2. git status -- what's up with my repository
3. git add . -- tells git you'd like to save *all* the changes you made
4. git commit -m "some message" -- versions files with a message
5. 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!

1. cd -- change directory (folder) to the one you are currently in
2. touch new.txt -- make a new file called new.txt
3. ls -- list the files in the current directory(folder)
4. mkdir myfolder -- make a new directory (folder) called myfolder
5. clear -- clear the terminal screen
6. 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