Git and GitLab

This semester, you’ll be using some immensely useful industry tools to submit your assignments.

Git
An open source, distributed version control system that allows programmers to track changes made to source files and share those changes with collaborators. It was created by Linus Torvalds (the Linux guy) and has become hugely popular in the last several years.
GitLab
An open source web application that makes it a bit easier for programmers to collaborate on programming projects. GitLab lets users create repositories (projects) on a central server. Users can then push their code to GitLab using git. From there, users can clone their code to other machines, push up new changes, etc. You could think of it (kind of) like Dropbox – GitLab is a central place to store your code.

In addition to storing code, GitLab has many features to help users collaborate with others. Users can share projects with other users, giving them the ability to push/pull code to/from the project. There are also bug tracking utilities, code review tools, and much more.

If that sounds scary, it really isn’t. This semester, you will need to be able to do these few things with git and GitLab:

  • Browse GitLab’s website
  • Retrieve (clone) assignment code from GitLab Projects that have been assigned to you.
  • Record (commit) changes that you made to assignment code.
  • Upload (push) the changes you made to GitLab.

That’s it! When you push your code to GitLab, the instructor will be able to access your code for grading.

As the semester progresses, Git will seem less and less scary. It is an incredibly useful tool.

I will be using the regular Git command line interface (CLI). If you choose to use a graphical desktop client for Git (e.g., Source Tree, GitHub Desktop, etc.), you’re on your own. Don’t ask me for help with such nonsense.


Warning

Do not blindly copy/paste Git commands from the Internet and run them. That’s generally good advice for any commands/code you might find on the Internet. Make sure you understand what a command does before you run it. Not all advice on StackOverflow is good advice.


Configure Git

Before we get into the thick of it, you should configure git on your development machine.

Tell Git who you are

  1. Open up a new Bash shell (e.g., connect to a Linux machine with PuTTY)
  2. Run the following commands to tell Git who you are

    # Use your name
    git config --global user.name "John Doe"
    
    # Use your email address
    git config --global user.email johndoe@example.com
    

If you don’t configure git, it will complain and complain whenever you try to commit changes.

Tell Git to use your Favorite Editor

  1. Open up a new Bash shell (e.g., connect to a Linux machine with PuTTY)
  2. Use git config to tell Git to use your favorite editor.

    # In this case, we're telling git that we want to use jpico
    git config --global core.editor jpico
    

If you don’t tell Git to use a specific editor, it will default to JOE (joe). Not to be confused with Joe.

Create an SSH Key (optional)

Setting up an SSH key with GitLab is a convenient (and secure) way to push/pull/clone code without typing your password over and over. Briefly, an SSH key comes in two pieces: a public key and a private key. By adding your public key to your GitLab account, Git will be able to use your private key to securely communicate with GitLab. No need for a password!1

It boils down to a couple of steps:

  1. Generate an SSH key pair (i.e. public key and matching private key) if you don’t have one.
  2. Copy your public key into your clipboard.
  3. Add your public key to GitLab
    1. Go to https://git-classes.mst.edu/profile/keys
    2. Click “Add SSH Key”
    3. Paste your public key in there

For more detailed instructions on key generation, refer to GitLab’s documentation on creating an ssh key.


The Assignment Workflow

Here’s the breakdown of the assignment workflow:

  1. Homework Announced
    • The assignment specifications and any related materials are posted online.
    • You are granted access to a GitLab project containing starter code.
  2. Work on it
    • Clone the repository from GitLab
    • Work on the assignment
      • Commit changes periodically
      • Push changes to GitLab for safe keeping
  3. Turn it in
    • Push any unpushed commits to GitLab
    • Make sure that your reflection.md is present, and it contains any submission comments you wish to make.
    • Log into GitLab’s website and verify that your files look OK.

That’s it!

Step 1: Homework Announced

Your GitLab Projects

Throughout the semester, you will be assigned multiple homework assignments. For each assignment, you will be granted access to a git repository on GitLab, which will contain any starter code necessary for the assignment. Only you and the instructor will be able to see the contents of the project or even see that it exists in GitLab.

You will be granted developer permissions to your repositories. This will allow you to view the project and push changes to it.

Getting the Code (git clone)

Let’s say you’re ready to start a new assignment. The first thing you have to do is retrieve your starter code from GitLab. Here is a step-by-step procedure for doing this:

  1. Log in to https://git-classes.mst.edu
  2. Navigate to the project that you want retrieve
  3. Copy your repository’s URL from the text box in the middle of the page (beneath the assignment name)
    • Clone over HTTPS (easiest)
      1. Select “HTTPS” from the dropdown next to the text box
      2. Highlight and copy the URL to your clipboard
        • It will begin with https://git-classes.mst.edu/2017-FS-CS-2001 and end with .git
    • Clone over SSH (if you have SSH keys configured with your GitLab profile)
      1. Select “SSH” from the dropdown next to the text box
      2. Highlight and copy the URL to your clipboard
        • It will begin with git@git-classes.mst.edu:2017-FS-CS-2001 and end with .git
  4. Open up a new Bash shell (e.g., connect to a campus Linux machine with PuTTY)
  5. Navigate to the directory where you would like to download your repository (using the cd command)
  6. Clone your repository using Git
    • The command is git clone <repository URL from step 3>
    • For example, git clone https://git-classes.mst.edu/2017-FS-CS-2001/2017fs-b-01-mwwcp2.git

That’s it! Now you’ve cloned your repository down, and you’re ready to get started.

Resources

Step 2: Work on it

Assuming you’ve cloned your code (as described above), then it’s time to start working on your assignment.

Committing Code (git commit)

As far as working on the files go, there’s nothing special you have to do. Edit them, compile them, have fun with them. When you’re ready to commit (take a snapshot of) your code, you’ll need to interact with git.

  1. Run git status to see which files are staged, modified, or untracked.
    • staged files2 will be included in the next commit.
    • modified files have been modified, but they haven’t been staged for commit.
    • untracked files are unfamiliar to git. They exist in the folder, but git isn’t paying any attention to changes made to them.
  2. Stage all changes that you want to commit
    • Stage files by using the git add command
    • For example: git add main.cpp
  3. Run git status again to make sure that the correct files are staged for commit.
  4. Run git commit
    • This will create a snapshot – recording the staged changes
  5. Enter a meaningful commit message in the commit editor. Then save and close it.

Now your changes have been committed!

Commit Resources

Looking through your Repository (git status, git log)

There are a couple of commands that come in handy for viewing the state of your repository:

git status
View the current state of files. What has changed? What’s new in the repository?
git log
Shows a timeline of commits. See a history of changes made to a repository
Inspection Resources

Pushing your Commits (git push)

After you’ve committed something, you can push it to GitLab with git push.

  1. Run git push
    • If you cloned over HTTPS, Git will ask for your username and password. Those are the same as the ones you use to log into GitLab.
  2. Check GitLab to ensure your code looks as expected.
    • This step isn’t strictly required. However, if you’re not used to working with Git, it is in your best interest to ensure your code looks right. We’re going to grade what’s in GitLab after all.
Push Resources

Step 3: Turn it in

Once you’re all done with your assignment, and you’re happy with your work:

  1. Create a file called reflection.md and write a couple paragraphs as described in the section below.
  2. Add the file to your repository (git add) and commit the new file (git commit).
  3. Push all your new commits to GitLab (git push).
  4. Check that reflection.md is present on the GitLab website and that your code looks the way you want it to.

Collection and Grading

Repository Snapshots

Periodically, we will snapshot all CS 2001 repositories. There are three times that are of interest to you:

  • Once shortly after an assignment’s original submission deadline.
  • Once roughly 24 hours after an assignment’s original submission deadline.
  • Once roughly 48 hours after an assignment’s original submission deadline.

Which commit gets graded?

For each snapshot starting with the earliest, we will ask the following questions about your repository:

  • Did we find a valid submission in an older snapshot?
    • No – Was the latest commit to the master branch authored by the student AND does reflection.md exist?
      • YesThis is a valid submission. It is ready for grading!
      • No – Skip and check next snapshot.
    • Yes – Ignore it. I already have a submission from this student.

If no valid submission was found for any snapshot, then you didn’t turn it in. That’s a zero.

Checking your Submission

Log into GitLab and look at the files in your project.

  1. Make sure reflection.md is there.
  2. Check that your latest changes are present.

What if I want to submit late?

If you refer to the steps above, you’ll notice that we’ll grade your first snapshot that contains a reflection.md. If you want to submit late, simply ensure that your repository doesn’t contain a reflection.md before we take a snapshot.

What if you’ve already started working on your reflection.md? You have a couple of options:

  1. Remove it using git rm, commit the file removal, and push that commit to GitLab
  2. Rename reflection.md to something else, commit the rename, and push that commit to GitLab.

Make sure you check GitLab before the snapshot deadline! If there’s a reflection.md when we take a snapshot, we’re going to assume you want your assignment to be graded.


The Reflection File: reflection.md

We need a way to know:

  1. That you’re done with your assignment.
  2. How the assignment went.

Every assignment you do for CPL will require that you write a reflection.md file that contains a short summary of your experience with the assignment. This should be the very last thing that is added to your repository.

Why?

If reflection.md exists in your repository, we will assume you are done with this assignment. If reflection.md does not exist in your repository, we will assume that you are still working on this assignment, and you are not ready to turn it in.

Some facts about reflection.md:

  • Assignment repositories do not come with a reflection.md. If you are ready to turn in your assignment, you must…
    1. Create a file in the root of your repository called reflection.md
    2. Use git add to track the file
    3. Commit the file addition
    4. Push the commit that adds reflection.md to GitLab.
  • A poorly written or blank reflection.md will severely hurt your grade.

What should a reflection.md look like?

That depends!

After we read your reflection.md, we want to know some or all of the following:

  • What parts of the assignment were challenging for you?
  • What parts of the assignment were easy for you?
  • How did you overcome challenges?
  • What made the easy parts so easy?
  • What do you feel you learned by completing the assignment?

Your reflection.md should be a reflection on your experience completing the assignment. As you write your reflection.md for an assignment, think about your experience from beginning to end. Think about things that were easy, things that were hard, skills you may need to improve, and skills that you did improve. You don’t have to blow our minds with insight, but we expect to see some thoughtful discussion about your experience.

We also intend to use the reflection.mds to help us understand where students are struggling. That way, we can use this information to better prepare you for future assignments and tests.

What should a reflection.md not look like?

So, we’ve given you a bunch of “do” items. Here’s what we don’t want to see:

  • General complaining about the assignment
    • We want concrete details that we can use to improve assignments in the future.
  • Vague statements about general topics
    • Again, we need concrete information. “It was hard” or “I liked it” doesn’t help us.
  • Hateful or nasty language
    • You can be professional, even if you’re frustrated.
  • Glib rambling, literal nonsense, or language copy-pasted from a previous assignment
    • Show some pride in your work. We take these seriously.

If your reflection.md exhibits too many of the items listed above, you will lose credit. That’s a shame, because these are nearly free3 points.

Your reflection.md should be professional in tone and written in coherent English. It isn’t an essay. In total, your reflection.md should be around 100 to 150 words in length. If you feel your write-up should be longer than that, you’re welcome to do so. Of course, if you have enough feelings to warrant writing an epic essay, we should probably have a conversation in person, too.

An Example

Here’s a modestly lengthy reflection.md we fabricated for an old CS 2001 assignment. It gives us a pretty solid impression of how this fictional person’s assignment went.

Python 1: A Safe Cracker tool for Carmen Sandiego
-------------------------------------------------

Starting this assignment was a challenge for me, as this was my first
experience picking up and completing code that I didn't write
myself. I understood the looping constructs, although it took some
time to get used to Python's for-each loop.

The program was frustrating to test, since I had to type in the inputs
over and over... I felt like I was in CS 1570 again. It would be cool
if we had a way to automate the testing.

Overall, the program wasn't too difficult to complete. The topics we
didn't cover in class were covered by the posted assignment
resources. I did do some additional googling for `argparse`, but that
was mostly for my own entertainment.

TL;DR

  1. No. Not TL;DR. Go read the thing.
  2. A reflection.md should be a well thought-out reflection of your experience completing an assignment.
  3. Your reflection.md should be between 100 and 150 words in length.
  4. It is your responsibility to create and add a reflection.md file to your repository.
  5. You’re welcome to format your file using Markdown.

Other Tips

  • Be sure to push all your committed code by the deadline. I cannot verify the submission time unless you pushed it.
  • Don’t forget to create and commit reflection.md to indicate that your submission is ready.
  • Don’t share projects with others. Assignments are an individual effort.
  • If you don’t push anything to your repository before the final deadline, we won’t grade it. We’re not going to grade Mike’s code.
  • You will not be able to force push to master.
  • I don’t care if you work on other branches, but I will only look for submissions on master.

Helpful Resources

These are some nice resources for learning more about Git:

If you see mentions of BitBucket or GitHub around, they’re just web applications like GitLab. Same basic idea, created different people.

  1. Unless you put a password on your private key. Then you have to type in that password to unlock your private key. 

  2. Yeah, yeah, you can stage parts of files. Don’t worry about that for now. 

  3. That’s free as in $0.00, no money down, take ‘em here they are, FREE points.