Using Git and GitHub

Why Use Source Version Control?

Why Use Source Version Control?

A source code repository might seem a bit like the shared folders that are provided by services like Dropbox, Box, or Google Drive. You can save files and folders and share them with other users in various ways Some of these tools even track allow you to undo and redo changes and see how files have changed over time. These are useful tools, and a great way to collaborate with others in a variety of different scenarios. So it’s normal to wonder: what’s different about source version control?

Compared to tools like Dropbox, source version control provides programmers with several important advantages.

Versioning Entire Projects

Versioning Entire Projects

First, version control systems track the version of all the files in each repository, rather than individual files separately. Programming frequently involves making a set of changes to a group of files that together accomplish something—like fixing a bug or adding a new feature. So when you commit your work using Git, it remembers the state of all the files in your repository at that time. This allows you to compare what your project looked like at different times, and undo an entire set of changes that might have caused a problem.

Note that this also means that Git does not track all the changes you save to a file. Unless you commit your changes, they are not saved to your repository. This may seem like an annoyance—after all, systems like Dropbox will sync your files every time you save them.

But when programming this turns out to be a huge advantage. Let’s say you save a version of Foo.java to test—but it contains errors. Now if you are using Dropbox, everyone has that broken version of the file. But if you are using Git, you can test your code, notice the errors, and fix them before committing.

A Git commit is really their equivalent of the save operation. Regardless of whether you save your files in Android Studio or any other way, you have to add commit them to your repository before it will save and remember them.

Commit Message

Commit Message

Version control systems also allow you to add your own notes to each commit. This is called a commit message. Commit messages should summarize what changes are included in the new version of the project. Good commit messages are extremely helpful to other developers that are trying to understand how the code is evolving. All version control systems have ways to view the list of version with their commit messages. This can be useful when you want to see how things have changed, or back up and use an older version of a project where some feature was working that isn’t any more.

Merging Changes

Merging Changes

Second, version control systems help you merge changes made concurrently by different developers—even to the same file. Say that Foo.java has 1000 lines. Alice makes a change at the top of the file. Concurrently, Bob makes a change to the bottom of the file. Systems like Dropbox will typically force you to address this conflict by choosing either Alice’s version of the file or Bob’s. But version control systems can frequently automatically merge non-overlapping changes to source code files—allowing you to choose to combine the changes from Alice with the changes from Bob. When you are working in large teams on large software projects, this capability is extremely handy.

Introduction to Git and GitHub

Introduction to Git and GitHub

Basic Principles

Basic Principles

Git organizes your files into a repository. A repository can contain any number of files organized any way you like. A single repository usually contains all of the code used by a single project. For CS 124, you will use a single repository for the machine project.

Git stores a copy of your repository on your local machine. But to submit and to backup your work, you are going to push your changes to the GitHub Git hosting service. So first we have to create a GitHub account and configure Android Studio to use it.

Joining GitHub

Joining GitHub

Joining GitHub is simple! If you don’t already have an account, head to this page to sign up. It’s quick, free, and painless.

If you already have an account, just keep using it for your CS 124 assignments. Note that there is also no requirement that you identify yourself as a CS 124 or even as an Illinois student with GitHub to submit your CS 124 assignments. We’ll discuss how to identify yourself your submissions later. However, if you add your @illinois.edu email to your profile as your primary email address, it will improve integration with our official grading system.

CS 124 Git Workflow

CS 124 Git Workflow

Almost all of your interaction with Git this semester will be through two powerful interfaces: Android Studio and GitHub. Let’s walk through a typical submission workflow to get a sense for how you will normally be using Git.

Cloning the MP Starter Code

Cloning the MP Starter Code

To begin the MP you will use a special link to clone a Git repository on GitHub. That repository contains starter code that we provide for each assignment, including completed portions of the assignment and testing suites. Cloning a Git repository on GitHub makes a copy of it that you now have permission to modify.

It is straightforward to start a new Android Studio project Using an existing GitHub repository—either one you created or one that was created for you when you accepted our MP invitation link. Simply choose the “Check out project from Version Control” option in the main Android Studio menu and then select “Git”.

Paste the link that you obtain when you choose “Clone or download” at the GitHub page for your project. If you have not yet added your GitHub credentials to Android Studio, it will ask you to do that. At that point Android Studio will download the code from GitHub to your local machine and allow you to begin making and testing your changes.

Identifying Yourself

Identifying Yourself

Before you can run the local autograder or receive credit for a submission, you must identify yourself. This links your @illinois.edu identify to your repository so that you can receive credit for your work.

In the root directory of each project you will submit, there is a file called ID.txt. In Android Studio you’ll need to switch to the project view to locate this file. Enter your project unique ID into that file.

Note that it is critical that you do this properly. If you enter an incorrect ID you will not receive credit for your work. If you enter the ID of another student, we will investigate your submission for plagiarism and potentially file a FAIR violation.

Running the Autograder

Running the Autograder

As you complete each assignment, you’ll want to track your progress and get a sense of how you are doing. To aid with that process, we’ve provided an autograder that you can run as many times as you like. Each time, it estimates the score that you’d earn on the assignment.

Please note that the autograder only provides an estimate of your score. While we have tried as hard as possible to make the autograder run similarly on your machine and in official grading, it is impossible to ensure identical behavior. You may also modify the test suites which will cause the autograder to behave differently. So use the autograder to estimate your score as you go—but be sure to submit and view your official score before the assignment deadline.

Committing (Saving) Your Work

Committing (Saving) Your Work

Version control systems only save the change you have made when you tell them to. This is called a commit, and the process called committing.

Once you commit a version of a file, Git will remember its committed contents forever—even if you change or delete it the file. So you should get into the habit of committing early and often. Here are some good times to commit your code:

• You just started a project—make sure to record it in its initial state!
• You just finished writing a function—that way you can always get back to that version if you make changes later.
• You just passed one test case—make sure that Git remembers what worked forever!
• You are about to take a break or go to bed.
• The MP deadline is in thirty minutes—or in five minutes!

Get in the habit now of committing your code regularly. Version control systems are very efficient at storing commits, and so the overhead of performing them is small. Better to have things saved than to want desperately to get back to a previous version or remember how you did something and not have it committed.

Note that most version control systems will require you to tell them the first time you want to add a new file to a project. Once you do this once, that file will be tracked in the future—but there is an initial step that you may sometimes miss. Android Studio is good about reminding you about this, as long as you don’t disable those reminders.

Android Studio has a convenient interface for committing changes, adding commit messages, pushing to GitHub, and generally tracking the state of your repository.

Pushing and Submitting Your Work

Pushing and Submitting Your Work

For CS 124 you submit your work by pushing it to GitHub. We will grade each version of your MP that you push and provide you with the best score modulo penalties and other score calculations.

You must push to GitHub for us to grade your work on the MP. Don’t consider yourself done with a checkpoint until you see the score that you think that you have earned on the official grading page. If more than a few minutes go by after you push and you still don’t see your grade on the grades page, begin the troubleshooting steps described below.

Troubleshooting the Submission Process

Troubleshooting the Submission Process

Except around deadlines, MP grading usually completes quite quickly. In most cases you’ll see your latest submission show up on the official grading page within a few minutes. However, if you submit right before a deadline, you may need to wait longer—maybe even several hours.

If you don’t find your commit there here are some common problems:

1. You forgot to push your work. This is a common mistake. You committed your work, but didn’t push it to GitHub. Try pushing again by selecting push under the “VCS → Git” Android Studio menu. If you have already pushed your work this will do nothing, but if you have not it will actually submit your changes for grading.
2. Your submission isn’t graded yet. If you submitted right before a deadline, you may need to wait several hours for grading to complete. As a reminder, you can and should use our local autograder to estimate your score as you work. Don’t submit until you are confident that you have earned the score that you are aiming for.
3. Your commit is there, it just didn’t get the score you thought it would. We put your best commit at the top of the list. If you newer commit doesn’t score as well, it will end up below your best commit, meaning that you might miss it. And when two best commits earn the same score we place the oldest on top, not the newest.
4. You didn’t enter your ID correctly into the ID.txt file. This is probably the most common problem. If you don’t enter your unique ID correctly we have no way to know that it’s you! So double- and triple-check that your email is correct.
5. You’re pushing the the wrong repository. You should be pushing to a repository in the cs124-illinois-students organization. If you’ve somehow created another repository on GitHub, remove it immediately once you’ve pushed to the correct repository. It can put you at serious risk for committing an academic integrity violation.

How to Learn More

How to Learn More

As usual the internet is the best way to find out more about anything related to technology. There are great Git tutorials out there that you can find on Google. And feel free to ask questions on the forum.