Summary and Setup

Jimmy and Alfredo have been hired by Ratatouille restaurant (a special restaurant from Euphoric State University) to investigate if it is possible to make the best recipes archive ever. They want to be able to work on indexing the prices at the same time, but they have run into problems doing this in the past. If they take turns, each one will spend a lot of time waiting for the other to finish, but if they work on their own copies and email changes back and forth things will be lost, overwritten, or duplicated.

A colleague suggests using version control to manage their work. Version control is better than mailing files back and forth:

  • Nothing that is committed to version control is ever lost, unless you work really, really hard at losing it. Since all old versions of files are saved, it’s always possible to go back in time to see exactly who wrote what on a particular day, or what version of a program was used to generate a particular set of results.

  • As we have this record of who made what changes when, we know who to ask if we have questions later on, and, if needed, revert to a previous version, much like the “undo” feature in an editor.

  • When several people collaborate in the same project, it’s possible to accidentally overlook or overwrite someone’s changes. The version control system automatically notifies users whenever there’s a conflict between one person’s work and another’s.

Teams are not the only ones to benefit from version control: lone researchers can benefit immensely. Keeping a record of what was changed, when, and why is extremely useful for all researchers if they ever need to come back to the project later on (e.g., a year later, when memory has faded).

Version control is the lab notebook of the digital world: it’s what professionals use to keep track of what they’ve done and to collaborate with other people. Every large software development project relies on it, and most programmers use it for their small jobs as well. And it isn’t just for software: books, papers, small data sets, and anything that changes over time or needs to be shared can and should be stored in a version control system.

Prerequisite

Prerequisites

In this lesson we use Git from the Unix Shell. Some previous experience with the shell is expected, but isn’t mandatory.

Setup

Callout

Install Git

Follow these installation instructions according to your Operating System (OS).

Please install Git for Windows using the instructions below.

  • Download the Git for Windows installer installed.
  • Run the installer and follow the steps below:
    • Click on “Next” four times (two times if you’ve previously installed Git). You don’t need to change anything in the Information, location, components, and start menu screens.
    • From the dropdown menu, “Choosing the default editor used by Git”, select “Use the Nano editor by default” (NOTE: you will need to scroll up to find it) and click on “Next”.
    • On the page that says “Adjusting the name of the initial branch in new repositories”, ensure that “Let Git decide” is selected. This will ensure the highest level of compatibility for our lessons.
    • Ensure that “Git from the command line and also from 3rd-party software” is selected and click on “Next”. (If you don’t do this Git Bash will not work properly, requiring you to remove the Git Bash installation, re-run the installer and to select the “Git from the command line and also from 3rd-party software” option.)
    • Select “Use bundled OpenSSH”.
    • Ensure that “Use the native Windows Secure Channel Library” is selected and click on “Next”.
    • Ensure that “Checkout Windows-style, commit Unix-style line endings” is selected and click on “Next”.
    • Ensure that “Use Windows’ default console window” is selected and click on “Next”.
    • Ensure that “Default (fast-forward or merge) is selected and click”Next”
    • Ensure that “Git Credential Manager” is selected and click on “Next”.
    • Ensure that “Enable file system caching” is selected and click on “Next”.
    • Click on “Install”.
    • Click on “Finish” or “Next”.
  • If your “HOME” environment variable is not set (or you don’t know what this is):
  • Open command prompt (Open Start Menu then type cmd and press Enter)
  • Type the following line into the command prompt window exactly as shown:

    setx HOME “%USERPROFILE%”

  • Press Enter, you should see SUCCESS: Specified value was saved.
  • Quit command prompt by typing exit then pressing Enter

If you prefer, here is a video tutorial with the instructions: https://www.youtube.com/watch?v=339AEqk9c-8

Please open the Terminal app. To open Terminal, try one or both of the following:

  • In Finder, select the Go menu, then select Utilities. Locate Terminal in the Utilities folder and open it.
  • Use the Mac ‘Spotlight’ computer search function. Search for: Terminal and press Return.

In Terminal, type git –version and press Enter/Return. If Git is installed, you should see a message similar to git version X.XX.X.

If it’s not installed already, follow the instructions on the official git website to install Git.

If Git is not already available on your machine you can try to install it via your distro’s package manager. For Debian/Ubuntu run sudo apt-get install git and for Fedora run sudo dnf install git.

Creating a GitHub Account

You will need an account for GitHub to follow episodes 7 & 8 in this lesson.

  1. Go to https://github.com and follow the “Sign up” link at the top-right of the window.
  2. Follow the instructions to create an account.
  3. Verify your email address with GitHub.
  4. Configure multifactor authentication (see below).

Multi-factor Authentication

In 2023, GitHub introduced a requirement for all accounts to have multi-factor authentication (2FA) configured for extra security. Several options exist for setting up 2FA, which are summarised here:

  1. If you already use an authenticator app, like Google Authenticator or Duo Mobile on your smartphone for example, add GitHub to that app.
  2. If you have access to a smartphone but do not already use an authenticator app, install one and add GitHub to the app.
  3. If you do not have access to a smartphone or do not want to install an authenticator app, you have two options:
    1. set up 2FA via text message (list of countries where authentication by SMS is supported), or
    2. use a hardware security key like YubiKey or the Google Titan key.

The GitHub documentation provides more details about configuring 2FA.

Preparing Your Working Directory

We’ll do our work in the Desktop folder so make sure you change your working directory to it with:

BASH 

$ cd
$ cd Desktop

Cheat sheet for the workshop

Here is the cheat sheet created by Carpentry @ UCSB for this workshop [Download PDF].

It’s based on the key points of this lesson and the GitHub Training cheat sheet available here