Minimal intro to git as used in this course

Nothing to hand in. Just make sure you know this stuff.

Goals

• Start using git
• Learn how to clone a git repository
• Learn about git's status, add, commit, pull, and push subcommands

git is a version control system that is free and open source, and extremely widely used among software developers world-wide. In brief, version control systems provide a kind of "track changes" service that supports systematic backup, recovery of previous work, collaboration between people on shared documents, etc.

In CS338, we will use git to enable us to collaborate in the sense that you can submit various versions of your code and other documents, and I can see your work and provide feedback. On those occasions when you collaborate with a classmate on an assignment, git will also enable you to share code and maintain a central shared copy of your code.

This document describes simple steps for the git operations you are most likely to use in this class. It is not intended to be an introduction to the concepts behind version control, git, or GitHub. For a more thorough introduction, try out one of the many git tutorials on the internet. This one, for example, looks pretty simple and helpful to me.

Assumption: Unix command line

Starting now, I'm assuming your working computer includes a Unix command-line environment. If you're working on Linux or macOS, then this is automatically true. If you're working on Windows, you can install Windows Subsystem for Linux (WSL).

Getting WSL to work smoothly with Windows is harder than getting a Unix terminal going on Linux or macOS, but once you're set up, they're all pretty much equivalent. Here are some instructions about WSL that I had my CS257 students follow last fall. Search that whole page for "WSL" to see more tidbits. You can also watch a video I made 2 years ago about setting up your development environment—here's a link to the WSL part.

Resources

If you want to dig deeper than this document goes, see our resources page for some of the videos and links I provide my CS257 classes to help them get up and running with Unix and git.

0. Overview of workflow

1. Create a GitHub repository
2. Get a clone of the repository onto your computer.
3. Add new files or modify existing files. That is, do some work.
4. Prepare to commit your changes to the repository by including the files whose changes you want to commit in the staging area
5. Perform the commit
6. Push the changes to github.com
7. If you have more work to do, go to step 3.

1. Create a GitHub repository

• If you don't yet have a GitHub account, create one. (I strongly urge you to create an account name that you would feel comfortable putting on a resume, since most of our students include their GitHub links when applying for internships and jobs.)
• Login to your GitHub account. It will probably drop you into your Profile page, so click on the GitHub logo in the upper left to go to the main GitHub page once you're logged in.
• Click on the big green New button in the upper left, and then:
  • Repository name = cs338
  • Public
  • Add a README file (don't worry about its contents yet—it's just good practice to have a README file for each repository, and you can add suitable descriptive text later)
  • Add .gitignore (I usually select the Python template for this class, since we'll do a bunch of Python coding)
  • If you wish, you can choose a license—I like the MIT license, but that's up to you. Don't know anything about software licenses? Pick None or MIT for now.
• Click on the green Create Repository button.

2. Get a clone of your repository on your computer

A git repository is essentially a folder full of subfolders and files, plus information about the history of changes that have occurred over time as files have been added, edited, moved, renamed, deleted, etc. To use a git repository, you need to clone (that is, copy) it onto your computer. You can do this using either a GUI git client or the git command-line client.

Once you have created your repository, you can go to github.com and see the new repository in the "your repositories" section of the page (on the left). Click on the link to your new repository and poke around a little bit.

Now, to obtain a clone of your repo onto your own computer, do one of the following.

• Option 1: use the command-line git command. In my opinion, the simplest approach to cloning your repository, is to go to your repository's home page and:

  • click on the big green Code button, select HTTPS, and then copy the link underneath (which should be something like https://github.com/YOURGITHUBNAME/cs338)
  • Open a Unix terminal on your computer ("Terminal" on macOS, "Windows Subsystem for Linux" on Windows)
  • cd to wherever you want to put your clone. If you're on Windows Subsystem for Linux, cd to your Desktop (or your Documents folder, or wherever) like this:
    cd /mnt/c/Users/YOUR_WINDOWS_USER_NAME/Desktop
    Note that this assumes your files are on your C: drive. If you're using, say, D:, then this cd command should start with "cd /mnt/d/...".
  • Execute:
    git clone THE_LINK_YOU_JUST_COPIED

  I encourage you to get familiar with the command-line operation of git, even if for day-to-day work you use a GUI git client (e.g. Option 2 below). Sometimes, you won't have access to a GUI client. Also, most tutorials and Stack Overflow discussions of git use the command line.

• Option 2: use GitHub Desktop. Install GitHub Desktop and follow the cloning instructions in its documentation.

Whichever git client you choose, once you have cloned your repository, you should end up with a folder named the same thing as your repository (e.g. "cs338") on your computer. Initially, this folder will contain only a subfolder named ".git", a README.md file, and (if you included them when you created the repository) a .gitignore file and a LICENSE file.

NOTE: for the remainder of this document, I will assume you're using the command-line git command. To do equivalent operations on a GUI client, check the client's documentation.

3. Do some work

You can create new directories (e.g. "mkdir basic-authentication for one of your early assignments) and new files and store them as appropriate inside your repository.

When you create new folders or files, execute:

This tells git that you want it to track the new file in this repository. Note that simply adding a file to the folder isn't enough to make git keep track of the file; you also have to perform the "git add" operation.

4. Prepare to commit your changes

Once you have done a little work on files in a repository, it's time to tell git that you want to save those changes in its timeline of your work. This is called committing your changes, and a single batch of changes is called a commit.

Suppose you want to include a particular file's changes in your up-coming commit. Then you need to stage the file (also known as adding the file to the staging area).

Here's what I do when I'm ready to commit.

• git status [this shows you which files are already staged, and which files are changed but not staged]
• git add name-of-file [this stages the file]
• repeat as needed to stage all the files you want included in the commit

5. Commit your changes

• git commit -m "a descriptive log message"

Make your log message descriptive. Like "first draft of basic-authentication.pdf" or "repaired a bug in our exponentiation function".

6. Push your changes to GitHub

• git pull (if you're working alone, this should do nothing, but establishing the habit of doing "git pull" before "git push" is very important to avoid messing up your repository when you're in a collaboration)
• git push (this sends your changes up to github.com, so I and your collaborators can see them)
• Go to GitHub and check to see whether your changes have appeared there. (You may need to reload your repository's web page, of course.)