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.
gitis the name of a VCS program that manages files within collections (called repositories). The
gitprogram itself should not be confused with GitHub, which is a website that hosts
gitrepositories 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,
gitcan 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.
gitspecifically. You can skip The history behind Git.
giton 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,
gitis already installed. However, you still need to run a couple of one-time configuration commands to set up your
gitaccount. From the machine on which you will be working (which might be, e.g.,
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 'email@example.com' 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.
giton your own machine).
git, follow along with the videos and create your own local repository to work with.
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
gitcommands and the other for running your editor.
gitcommands. Go through the whole thing.
mkdir(make a new directory),
mv(move or rename files), and
rm(remove files - be careful!). As before, the Unix Crash Course (or the
manpages) can give you more details.
git rmcommands -- these function very similarly to
rm(by design) but are distinct programs, and the former are only used in the context of a
git checkout -- <file>...to discard working directory changes and
git reset HEAD <file>...to unstage files. Recent versions of
githave added a new
git restorecommand that is easier to use and can handle both scenarios. The basic syntax of
git restoreis 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 resetdemonstrated in the videos.
gitrepository. 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
githost 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
git commands will be used to interact with the remote repository.
git initcommand, this command results in a new
gitrepository on your local machine, but
clonewill 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-nameThe 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).
git pushIn 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 pushto push your completed local files to GitHub. However, it's also a good idea to run
git pushon 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.
git pullin the opposite direction, and uses the same syntax:
git pullFor a repository that you are editing by yourself, you are unlikely to need
git pullwith 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 pullto see the new or updated files in your local repository. Executing
git pullbefore 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.
gitis 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.
clonecommand. 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 clonecommand. Having done so,
gitwill 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).
jdoe-keypair.puband private key like
jdoe-keypair.pem) inside the
.sshfolder in your home directory (i.e., the
~/.sshdirectory). Remember that this is the home directory on the machine from which you are running git commands (i.e., most likely
foxcroft). If you are working on
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
cat ~/.ssh/jdoe-keypair.pubPaste 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/configHaving 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
firstname.lastname@example.org/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
gitcommand that uses the key (most likely the initial
gitand 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
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, 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.
gitis 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.
git mergecommands, which you probably have never explicitly used, but are actually the two subcomponents of the
git pullcommand that you've been using regularly. Again, try not to get bogged down in all the branching details.
git pulldoes (remember, pulling is a fetch plus a merge)!