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?)

Watch Version control and About distributed version control, which will give you a good overview of version control in general as well as git specifically. You can skip The history behind Git.

Module 2 (Install Git)

Most of this module covers how to install and configure git on your own machine. While you are welcome to do so, you will likely instead be completing your coursework using one of Bowdoin's Linux servers (accessed remotely over SSH). In this case, git is already installed. However, you still need to run a couple of one-time configuration commands to set up your git account. From the machine on which you will be working (which might be, e.g., hopper, turing, dover, or foxcroft), run the following three commands to set your username, email, and default editor (of course, substitute your actual name and Bowdoin email address):
```
git config --global user.name 'Jane Doe'
git config --global user.email 'jdoe@bowdoin.edu'
git config --global core.editor 'nano'
```
If you would prefer to use another editor (e.g., vim), you can set that as well. You can always come back and change these settings later.
Watch the final Git help section. You can skip everything else in this module (unless you need to install git on your own machine).

Module 3 (Getting Started)

For coursework, you often won't be creating your own repositories, and will instead be working with existing repositories cloned from GitHub. However, for the sake of learning git, follow along with the videos and create your own local repository to work with.
Go through Initialize a repository, Your first commit, and View the commit log. You can skip the other sections (Where Git files are stored and Write a commit message).
The videos use a graphical (i.e., non-terminal based) editor to create and edit text files. Since you are likely working remotely over SSH, you will instead need to use a command-line editor (such as nano) to create and edit files. Refer back to the Unix Crash Course if you need a refresher on using a command-line editor. It's a good idea to have two SSH windows open: one for running your git commands and the other for running your editor.

Module 4 (Git Concepts and Architecture)

Go through The three trees and Git workflows. You can skip the last two sections (Hash values (SHA-1) and The HEAD pointer).
The most important conceptual idea here is the idea of three separate trees (the working copy, staging index, and main repository). Make sure you understand this distinction and how the three trees are used.

Module 5 (Make Changes to Files)

This module covers the most important git commands. Go through the whole thing.
In the Delete files and Move and rename files section, the GUI is used for several common tasks (e.g., renaming a file, deleting a file, creating a directory). Remember that you can do all of these tasks directly from the command line using mkdir (make a new directory), mv (move or rename files), and rm (remove files - be careful!). As before, the Unix Crash Course (or the man pages) can give you more details.
Towards the end, the videos use the git mv and git rm commands -- these function very similarly to mv and rm (by design) but are distinct programs, and the former are only used in the context of a git repository.

Module 6 (Use Git with a Real Project)

Watch the Stage and commit shortcut section, which shows you a useful command that will save you time. You can skip the rest of this module, which is mostly more examples of previous commands in the context of a larger project.

Module 7 (Undo Changes)

Go through the first two sections (Undo working directory changes and Unstage files). You can skip the rest.
The examples in the videos use git checkout -- <file>... to discard working directory changes and git reset HEAD <file>... to unstage files. Recent versions of git have added a new git restore command that is easier to use and can handle both scenarios. The basic syntax of git restore is as follows:
To discard changes in the working directory:
```
git restore <file>...
```
To unstage files:
```
git restore --staged <file>...
```
This usage is likely easier to remember than the versions of git checkout and git reset demonstrated in the videos.

Module 8 (Ignore Files)

Go through the first two sections (Use .gitignore files and Ideas on what to ignore). You can skip the rest.

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:

clone: Create a local copy of a remote repository. Like the git init command, this command results in a new git repository on your local machine, but clone will download the data from a URL (e.g., on GitHub). The basic command syntax is as follows:
```
git clone [URL]
```
So, for example, you might run something like this (using the actual URL of a GitHub repository):
```
git clone https://github.com/some-organization/some-repo-name
```
The above example (if the URL was valid) would create a new directory named some-repo-name (which is the cloned repository) in the current directory (you can rename it to whatever you want if desired). Inside will be whatever files were downloaded from the remote repository. Remember that cloning (like initializing a new repository) is generally a one-time step. Once you have a cloned (i.e., local) copy of the repository, you will be working from within that directory and do not need to clone the remote repository again (unless you delete the local copy, etc).
push: Apply commits from your local repository to the remote repository (i.e., push your updates to GitHub). As you make commits to your local repository, your local repository will gradually diverge from the remote repository (since you are only applying the changes to your local repository). Since only the remote repository is available to others, you will periodically want to sync up the remote repository, as such:
```
git push
```
In the context of submitting an assignment, you might have a GitHub repository accessible by you and your professor. In order for your professor to view your completed work, you will need to run git push to push your completed local files to GitHub. However, it's also a good idea to run git push on a regular basis, as this will ensure that an up-to-date copy of your repository exists on GitHub's servers and will not be inadvertently lost or deleted.
pull: Retrieve and apply commits made to the remote repository that have not been applied to your local repository. This operation is essentially git pull in the opposite direction, and uses the same syntax:
```
git pull
```
For a repository that you are editing by yourself, you are unlikely to need git pull with much frequency, since your local repository should rarely be lacking any commits made to the remote repository. However, an example where you might need to pull is if your professor updates starter files in the repository or adds new feedback files. In these cases, you would need to run git pull to see the new or updated files in your local repository. Executing git pull before each work session is a good idea as a matter of course to make sure that you aren't missing anything from the remote 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.

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)

Branching is a powerful and widely used feature of git, but you are unlikely to make much conscious use of it as a beginner. However, working with remote repositories (such as on GitHub) involves implicit use of branching, and having a basic understanding of branching will be useful. Watch the first section only (Branching overview) to get a basic sense of what branches are and why they're useful.

Module 6 (Set Up a Remote)

Go through the first section (Local and remote repositories) to get a better sense of how git is actually managing the communication with a remote repository. Don't worry too much about the details of branching and merging in here; just focus on the big picture.
Next, go through Clone a remote repository (you can skip the intervening sections), which probably matches your typical usage in classes (i.e., cloning remote repositories that are already created for you). As before, don't worry too much about the branching details.

Module 7 (Collaborate with a Remote)

Go through the first three sections (Push changes to a remote repository, Fetch changes from a remote, and Merge in fetched changes). The big ideas in here are the git fetch and git merge commands, which you probably have never explicitly used, but are actually the two subcomponents of the git pull command that you've been using regularly. Again, try not to get bogged down in all the branching details.

Module 4 (Merge Branches)

Go back to Module 4 and go through the Merge conflicts section, which walks through the problem of dealing with conflicting commits. Note that the video sets up a merge conflict with a single user modifying multiple branches of the project. The more likely scenario in which you would encounter a merge conflict is when you fetch remote changes that a group member made, and then merge the updated remote branch with your local branch containing your own (conflicting) changes. That sequence of events may sound complicated, but it's actually just what running git pull does (remember, pulling is a fetch plus a merge)!
Now, go through the Resolve merge conflicts section, which walks through what to do when you get a merge conflict. The process would be the same in the multi-user scenario outlined above.
Finally, go through Strategies to reduce conflicts, which contains some best practices for collaboration to try to avoid merge conflicts whenever possible.

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 January 2023.

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