Preamble

This a workshop I wrote for IDDO’s coding club to introduce complete beginners to version control with git and the many pros to using GitHub. During this workshop, we will:

  • Learn how to initialise a local repository, how to make commits, and how to go back to past versions of our repo
  • Learn how to push our repository to GitHub, how to fork a GitHub repository, and how to collaborate through pull requests
  • Learn some other neat features of GitHub, such as Overleaf integration and github.io!

This workshop is for absolute beginners. Version control is confusing! Once you’ve got through the basics, here are some resources for different skills levels:

  • git is my lab book
  • and of course, your friendly neighbourhood LLM is absolutely welcome :)

Before we get started: the command line

Today, we’ll be driving git using the command line. In RStudio (or whichever IDE you’re using), navigate to the Terminal window. Welcome to the command line. Some useful commands:

  • pwd: print working directory
  • cd: change directories
  • mkdir: make directory
  • mv: move (a file or files from one location to another)
  • cp: copy (a file or files from one location to another)
  • ls: list all files in a directory
  • less: view the contents of a file
  • man: show the manual for a command, with all the different options associated with it, e.g. man ls

If you’re unfamiliar, let’s have a quick play around with these. CMD/A and CMD/E are my favourite command line shortcuts. There are lots of other commands and interesting ways to use them but we’ll move on for now!

Version control: why are we here?

Have you ever found yourself hours or days into a change to a coding or stats project, only to realise you need to go back? It’s times like these when version control can be very powerful! By tracking your progress on your code you can:

  • go back to specific versions of your code
  • track your progress with annotations on each major change to your code
  • try out new additions of your code without losing a stable version of it
  • (and, with a platform like GitHub, allow other people to track your progress)

One widely-used system for version control is git.

Our first repository

To make your first repository, navigate to the directory where you would like it to be located.

Terminology alert!

“repository” or “repo”: think of this as a folder where all your code and other stuff goes. Each repo is a self-contained unit for a single project. - “local” repository: the version of your repo on your computer. - “remote” repository: the version of your repo on GitHub, for example.

Like so:

mkdir best_project  # for example
cd best_project  
git init

You can check that you have successfully initialised your repo by checking its status:

git status

Our first commit

There’s nothing in our repo yet! Let’s add a README. This command creates a file called README.txt and puts some text in it

echo "a very nice readme" > README.txt

Check the status of your repo again. I get:

On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    README.txt

nothing added to commit but untracked files present (use "git add" to track)

This tells a couple of important things. We’ll get to branches later, but importantly, the status message tells us the repo has no commits yet. Let’s remedy that!

Terminology alert! “commit”: a discrete change to your repository. Each commit is a snapshot of the repository. Commits are a two-step process: 1. Add files to staging area. (Or, prepare your snapshot.) 2. Commit! (Take a photo!) {: .notice–info}

To add files to the staging area, we can use add:

git add README.txt

Check your repo’s status again. Has the README made it to the staging area?

Now commit:

git commit -m "my first commit"

The text that follows -m is the commit message. We write this ourselves to give a human-readable description of changes in the new commit. The commit message is more important than you might think! Use it to track your own progress as you write your code: what are the key changes in each commit? Consider yourself in the future, when you’ve forgotten the train of thought you had as you wrote and edited your code: what will you need to know in order to find your place. It might help to think of your set of commit messages as a lab book. In a wet lab, scientists use a lab book to track each of the things they do during their experiment, so that they have a record when their results don’t turn out how they would expect. This is what we should be using commit messages for!

Exercise: our second commit

  1. Make a change to your repository. Edit your README, or add a file.
  2. Check the status of your repository, add your changes to the staging area. This command might be useful:
git add *

This will add all untracked changes to the staging area. 3. Commit! Make sure you use a descriptive commit message.