This will guide you through understanding how we will be using Git & GitHub for this course.
- Learning Git
- Setting up GitHub
- Setting up Git
- Getting Newly Released Homework
- Submitting Your Homework
- Word of Caution
The motivation for using Git and GitHub for ComS 342 has two parts.
The first part is a convenience factor for the instrutor and TAs. Not surprisingly, BlackBoard isn't the most friendly for assignments dealing with code. With Git, we can very easily clone all your solution repositories and pull in changes as you add to them. Since we make heavy use of unit testing in this course, we are able to automate things which really helps us as well.
GitHub acts as a collection point for Git repositories. It makes it easy to collaborate and host code all while using Git either in a GUI or on the command line. It also has a very powerful API that we've made use to make our jobs easier.
Secondly, we wish for you to get as much out of this course as possible. In addition to learning about programming languages, there isn't a single more powerful tool for programmers that can be learned than a version control system.
There are numerous guides on using Git that are available. They range from being interactive ones to just text ones. Find one that works and experiment; making mistakes and fixing them is a great way to learn. Here is a link to resources that GitHub suggests: https://help.github.com/articles/what-are-other-good-resources-for-learning-git-and-github
Setting Up GitHub
Assuming you have a solid enough understanding of Git, it's time to get started with GitHub.
If you don't already have an account, sign up for one here: https://github.com/join.
Next you need to join the GitHub Organization that we've created for the course: ComS342-ISU
To join it, go to the ComS 342 Registration page and click the Sign in with GitHub button.
This application uses OAuth and it will take you to GitHub where you will have to give your permission to join it.
Enter your NetID and you'll be automatically added to the organization and will have a repository created for you.
If for whatever reason you can't join the organization, contact Josh Davis, firstname.lastname@example.org and let him know.
You should now be apart of the ComS 342 Organization and should have access to a few different repositories.
You should also now have a repository setup just for your homework solutions. This should be located in the ComS342-ISU organization and be called
This is what you'll setup in the next section to allow you to write your homework answers and submit them.
If the above didn't work, contact one of the TAs to help you out.
Setting Up Git
You should have Git installed and have joined the ComS342-ISU organization from the previous section.
The first thing we have to do is to clone the current homework repository by issuing the following commands onto the command line:
$ git clone email@example.com:ComS342-ISU/homework.git
This will make a complete replica of the homework repository locally. Now we are going to change it to point to your personal repository that was created for you in the previous section.
If you get an error that looks like:
Cloning into 'homework'... Permission denied (publickey). fatal: Could not read from remote repository.
More likely the cause is that you just haven't finished setting up your GitHub account. You just need to setup an SSH key to allow pushing and pulling over SSH.
Change your working path to your newly cloned repository:
$ cd homework/
By default the remote called
originis set to the location that you cloned the repository from. You should see the following:
$ git remote -v origin firstname.lastname@example.org:ComS342-ISU/homework.git (fetch) origin email@example.com:ComS342-ISU/homework.git (push)
We don't want that remote to be the origin, instead, we want to change it to point to your repository. To do that, issue the following command:
$ git remote rename origin upstream
And now you should see the following:
$ git remote -v upstream firstname.lastname@example.org:ComS342-ISU/homework.git (fetch) upstream email@example.com:ComS342-ISU/homework.git (push)
Lastly we need to give your repository a new
originsince it is lacking one. Issue the following but substituting your GitHub username in place:
$ git remote add origin firstname.lastname@example.org:ComS342-ISU/hw-answers-<NetID>.git
But substitute in your own NetID of course.
If you have an error that looks like the following:
Could not rename config section 'remote.[old name]' to 'remote.[new name]'
Or this error:
fatal: remote origin already exists.
This appears to happen to some depending on the version of Git they are using. To fix it, just issue the following command:
$ git remote set-url origin email@example.com:ComS342-ISU/hw-answers-<NetID>.git
For reference, your final
git remote -vshould look like following when its setup correctly:
$ git remote -v upstream firstname.lastname@example.org:ComS342-ISU/homework.git (fetch) upstream email@example.com:ComS342-ISU/homework.git (push) origin firstname.lastname@example.org:ComS342-ISU/hw-answers-<NetID>.git (fetch) origin email@example.com:ComS342-ISU/hw-answers-<NetID>.git (push)
Let's test it out by doing a push of your master branch to GitHub by issuing the following:
$ git push -u origin master
You should see something like the following:
Counting objects: 5, done. Delta compression using up to 4 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 294 bytes | 0 bytes/s, done. Total 3 (delta 2), reused 0 (delta 0) To firstname.lastname@example.org:ComS342-ISU/hw-answers-joshuad.git f726472..545a4f0 master -> master
That last command was a bit special and only needs to be ran the first time to setup the remote tracking branches. Now we should be able to just run
git pushwithout the arguments. Try it and you should get the following:
$ git push Everything up-to-date
If you don't know Git that well, this probably seemed very arcane. Just keep using Git and you'll keep understanding more and more.
Getting Newly Released Homework
Pulling in homeworks that are released or previous homework solutions should be easy just so long as you set up your repository based on the instructions from the last section.
All new homework and previous homework solutions will be posted to the homeworks repository in the class organization.
Check it periodically as well as BlackBoard's announcements for updates on when the new homeworks are released.
Once a homework is released, pulling in the changes should be fairly simple:
$ git pull upstream master
OR if you wish to be more explicit, you can
fetchfirst and then
$ git fetch upstream $ git merge upstream/master
If you've followed the instructions in each homework, you should have no merge conflicts and everything should be peachy.
Submitting Your Homework
The submission of your homework should be done by the date and time the homework is due.
The criteria for your homework being submitted on time is that your code must be pushed by the date and time. This means that if one of the TAs or the instructor were to open up GitHub, they would be able to see your solutions on the GitHub web page.
Just because your code has been commited on your local machine, that doens't mean that it has been submitted; it needs to be on GitHub.
Here are a few guideline steps for a process of submitting your solutions:
Look at your current repository status.
$ git status
Add your solutions (if they aren't already added and commited).
$ git add my-solutions/
Commit your solutions.
$ git commit
Enter your commit message and then save and exit.
This is the most important part: push your solutions to GitHub.
$ git push origin master
git pushfor short.
The last thing that we strongly recommend you do is to go to the ComS342-ISU organization page on GitHub to make sure that we can see your solutions.
Just navigate to your repository and check that your latest commits are on GitHub.
The go and eat some cinnamon rolls; you've finished the homework assignment.
Word of Caution
Git is a distributed version control system. This means everything operates
offline until a
git pull or
git push. This is a great feature.
The bad thing is that you may forget to
git push your changes. This is why we
strongly, strongly suggest that you check GitHub to be sure that what you
want us to see matches up with what you expect.
If at any point you need help with setting all this up. Feel free to reach out to one of the TAs or instructor. Their contact information can be found in the syllabus.