Introduction to Git and GitHub

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.

Version control systems also allow you to add your own notes to each commit. This is called a comment. Comments should summarize what changes are included in the new version of the project. Good comments 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 comments. 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.

Second, version control systems help you merge changes made 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.

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 125, you will use a single repository for each MP 1.

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.

Before you can use Git with Android Studio you may need to install the underlying Git tool itself. We suggest you follow the first two steps of this tutorial to install Git and integrate it with Android Studio.

Note that you do not need to install a GUI for Git—or the GitHub Desktop application. We’re going to use Android Studio’s excellent built-in Git interface. So once you’ve installed Git you can move on.

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 125 assignments. Note that there is also no requirement that you identify yourself as a CS 125 or even as an Illinois student with GitHub to submit your CS 125 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.

To begin each MP 2 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. It should look like https://github.com/cs125-illinois-students/MP0-Spring2019-username.git, where username is your GitHub username.

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.

Note that you should never use the "Download ZIP" or "Open in Desktop" options on GitHub. These will result in an incorrect project setup that is hard to fix.

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 email.txt. In Android Studio you’ll need to switch to the project view to locate this file. Enter your @illinois.edu email address into that file on a single line.

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

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

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. Given that committing is essentially saving your changes, this have given rise to memes like the one on the right.

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:

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. However, 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.

For CS 125 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.

Except around deadlines, MP grading usually completes quite quickly. In most cases you’ll see your latest submission show up on the MP grades page within a few minutes. However, if you submit right before a deadline, you may need to wait longer—maybe even several hours. Note that there is no need to reload the page: it will update automatically.

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