Git Essential Training Companion Guide
maintained by Sean Barker
(or, go back to the Unix Crash Course)

Overview

An important tool in any programmer's toolchest is a robust version control system (or VCS). A VCS is used to track changes to documents and manage multiple users' access to the same files. Here at Bowdoin, you are likely to use version control in the context of working in a group and/or submitting your completed work (but there are plenty of good reasons to use a VCS as an individual too).

The most popular VCS used today is Git. There are many online tutorials on using git (of varying quality); one of the most thorough tutorials is the video series Git Essential Training: The Basics. However, the complete course is quite involved for a complete VCS beginner who just needs to get some work done, and the course doesn't cover a few important things you'll need to know for coursework. This companion guide will highlight the most important pieces of Git Essential Training (and a followup course, Git: Branches, Merges, and Remotes). As you become more experienced with git, you are encouraged to return to these courses and learn about the more advanced topics covered.

Prerequisites

This guide assumes you have already completed the Unix Crash Course (or are otherwise familiar with the command line). If you haven't done that yet, do that first.

Accessing LinkedIn Learning

The video series are available on LinkedIn Learning, which can be accessed through your Bowdoin account as described in this document. Once you have access to LinkedIn Learning, follow the link below to begin the course. Refer to this guide before you start each module, which will advise which sections you should focus on and which you can skip over (of course, you can go through the entire course instead if you wish).

1 - Git Essential Training

Before we jump in, a quick note on terminology: git is the name of a VCS program that manages files within collections (called repositories). The git program itself should not be confused with GitHub, which is a website that hosts git repositories and makes them available over the internet (e.g., to you on multiple computers, or to collaborators). Since one of the major roles of a VCS is to facilitate seamless collaboration, a service like GitHub is invaluable for this purpose. However, git can be used entirely independently of services like GitHub, and this video series does not discuss GitHub at all. Following this course, we will cover (very briefly) the essential aspects of GitHub that you will need to share your work.

Git Essential Training: The Basics

Module 1 (What Is Git?)

Module 2 (Install Git)

Module 3 (Getting Started)

Module 4 (Git Concepts and Architecture)

Module 5 (Make Changes to Files)

Module 6 (Use Git with a Real Project)

Module 7 (Undo Changes)

Module 8 (Ignore Files)


2 - Using GitHub

Having gone through the course above, you should now have a basic understanding of how to work with a git repository. This is not sufficient, however, to share your repository with others (e.g., with other students in a group, or with your professor to submit work). To accomplish these kinds of tasks, we need to have a repository that is available over the internet. The most common way to do so is by using an online git host like GitHub (there are others as well, but GitHub is the most popular). Using a service like GitHub also provides the important advantage of easily backing up your work.

The basic idea of a GitHub repository is fairly simple. Instead of just a single git repository that exists on your local machine, now there will be two repositories: the one on your local machine, and a separate repository that exists on GitHub's server and is available to others. Several new git commands will be used to interact with the remote repository.

Creating a GitHub Account

First, if you don't already have a GitHub account, go there and create a (free) account. Using your Bowdoin email is recommended, as doing so will give you some added benefits that GitHub provides to students. If you already have a GitHub account, it's perfectly fine to continue using that.

Working with a GitHub Repository

For our immediate purposes, we only need to think about three operations in order to interact with a remote (GitHub) repository: Note that the above descriptions are highly simplified, and git is doing quite a bit more under-the-hood when you run these commands. However, for a beginner working alone on a GitHub-hosted project, this understanding should be sufficient.

Getting the Repository URL

To start using a repository hosted on GitHub, you will need the right URL to use in the clone command. To find it, go to your GitHub repository in a web browser and make sure you're on the Code tab. On this page, there should be a bright green button also labeled Code. Click that, and it will show you a few different options (e.g., HTTPS or SSH), which will specify different URLs. HTTPS is the simplest option, and you can copy/paste the corresponding URL into your git clone command. Having done so, git will then prompt you for your GitHub username and password whenever you interact with the remote repository (e.g., push or pull). More convenient, however, is configuring GitHub access using an SSH key, which will allow you to access GitHub without needing to type your username and password every time (consult the Unix Crash Course for a refresher on the concepts of SSH keys).

Configuring SSH Key Access

Assuming you already have an SSH key, follow these steps to configure GitHub to use your SSH key for access. First, put your two keyfiles (public key like jdoe-keypair.pub and private key like jdoe-keypair.pem) inside the .ssh folder in your home directory (i.e., the ~/.ssh directory). Remember that this is the home directory on the machine from which you are running git commands (i.e., most likely hopper, turing, dover, or foxcroft). If you are working on hopper or turing, this step may already be done for you.

Next, go to the key settings page of your GitHub account. Click New SSH Key. Give the key some descriptive name (like "My Bowdoin CS key") and then in the Key field, paste in the contents of your public key file (not your private key file!). Here is a quick command to display the contents of your public key file, assuming that your public key is named ~/.ssh/jdoe-keypair.pub:

cat ~/.ssh/jdoe-keypair.pub
Paste the output of that command (using your actual filename) into the Key field of the GitHub settings page, then click Add SSH key.

Now that your GitHub account is configured to accept your key, you need to configure your SSH client (from the machine where you're calling git) to use your key when connecting to GitHub. To do so, open the file ~/.ssh/config (this file may not exist, in which case you should create it). Save the following into this file, substituting the key filename appropriately (note that this should be the filename of your private key):

Host github.com
    IdentityFile ~/.ssh/jdoe-keypair.pem

If you had to create your SSH config file, you'll also need to run one more (one-time) command to set the file permissions appropriately:

chmod 600 ~/.ssh/config
Having done this, you are now all set to use SSH key authentication with GitHub. Go back to your GitHub repository code page and copy the SSH URL (it will look something like git@github.com/some-organization/some-repo-name - don't change any part of this). Use this URL in your initial clone command, and you should never need to enter a username or password for GitHub. Note that you may need to enter "yes" to accept the key the first time you run a git command that uses the key (most likely the initial git clone).

3 - Collaboration with Git and GitHub

Note: You do not need to complete this section if you are not working in a group. In fact, if you are just learning git and are going to be working individually at first, I recommend against going through this material now. Instead, get some experience and familiarity using git, and then come back later and complete this part when you are getting ready to work in a team.

The description of working with GitHub in the previous part is sufficient when only a single user is actively working in the repository. However, things get more complicated when you have true collaboration (i.e., a team of two or more people working on the same project). The primary potential difficulty is that two people, working independently on the same file in their (separate) local repositories, may make conflicting (local) commits and then try to push them to the remote repository. The first person to do so will succeed (updating the remote repository). However, when the second person then attempts to sync with the remote repository, there will be an error due to the mismatch; git cannot tell whether the first person's or the second person's conflicting edits should persist. This type of scenario almost never happens with only a single user, but is much more likely to happen at some point when a team is working together.

To learn about how to deal with this type of situation, some knowledge of more advanced git features is necessary. As with our initial introduction to git, we will draw on another video series that is a followup to the first series. As before, consult the guide below in order to refer to the most relevant videos; there are still a number of advanced features covered that we don't need to worry about for the moment.

Several of the modules in this series are not directly relevant to the problem at hand, so we will be skipping them entirely. The modules and sections you should go through are given below.

Git: Branches, Merges, and Remotes

Module 2 (Branching)

Module 6 (Set Up a Remote)

Module 7 (Collaborate with a Remote)

Module 4 (Merge Branches)

As always, you should feel free to go through the entire series if/when you want to learn more about some of the more useful advanced features of git (particularly branching).
Last updated March 2021.