I originally wrote this for the ACSE mailing list several years ago. This is an updated version of that post with some extra resources. It also looks at how I have been using git/github for my classes over the past few years.
Using git and github for your classes
git is the open source distributed revision control system created for managing the code needed for the Linux project. It lets you create a history of all the code of your project. You can send git repository around as zip files if you like.
github is a company that creates a nice place for you to put these repositories into the cloud so that you can much more easily sync and share these repositories without having to set up servers or send around giant zip files. It also provides things like access control, issue tracking, wikis, activity graphs and so on. Very handy.
As this post is long, I’ll start with some links for quick reference on where to find/get stuff. After that I have a section specifically for dealing with github and git itself.
Dan Shiffman’s git/github videos: https://www.youtube.com/playlist?list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV
David Humphrey’s git/github talk at fsoss 2015 (note sound gets better about 1 min into video): https://www.youtube.com/watch?v=VKArpO69cIw
My workshops for showing students how git works via github: https://github.com/cathyatseneca/gitworkshop-s17/wiki
github education (get free/discounted pricing for private repos on personal accounts or orgs here): https://education.github.com
github classroom: helps with managing access to starter repos for your students (I haven’t really tried this yet) : https://classroom.github.com/
bash scripts I wrote to create/clone/delete repos for your students under your organization. See readme on how to use it: https://github.com/cathyatseneca/CourseRepoScripts
github has 2 types of accounts: individual and organization.
As a teacher, will need to make for yourself an individual account. You will also need to make 1 or more organization account. Any individual account can belong to zero or more organizations. For myself, I have quite a few different organization accounts. One for each of my courses and one for my research group. All accounts and organizations are free to create. The difference between an organization account and an individual account is the type of controls you have to manage collaborators and repositories.
Under each account/organization are a number of repositories (repos). Each repository on github consists of a code repository (source code and its history), a wiki, an issue tracker, project organizer and graphical data related to the repository (analytics). Furthermore you can even use github to host client side webpages. Think of a repo as a place to put code and all things you want to see about that code in one place. It’s geared for people to work together on large code bases. Each repository can be either public or private. public means that the repository is fully accessible by anyone in the world. private means that the access is restricted.
You can use github for free without any extra work providing you are ok with the repositories being completely open (public). This means that all code, issues, wiki’s everything is open to the world. However, you may not want this for yourself or your student’s work. github charges for collaboration on private repos.
github makes money by essentially charging for privacy so under normal circumstances they would charge some amount for private repositories. You can see their pricing plans here: https://github.com/pricing
This is where github education comes in. You can request github for a discount if your personal or organization is used for academic purposes. Depending on the situation they may grant it for free (all my course organizations for example) or for a discount.
Typically they will want info about your school, number of students and so on. They will also want you to use your official school email on the account/org you are requesting a discount on. So make sure you make your account with that email.
Aside from you setting up an account, your students must each individually create a github account. The students can ask github for their own private repositories also through education.github.com but this is not necessary as the private repos can be created under your organization and you can simply grant access to your students. Creating private repos under your organizations means that you can maintain admin control over them. For example, we are suppose to keep eletronic work around for 1 year from end of course so having admin control means I determine when a repo is deleted.
Using Github for Hosting Course Material
I have found github to be a great place for me to host course material for my class. The way I do this is I create a repo for the course I’m teaching. Any example source code is simply added to the repo. Students can clone the repo to get the source code as it was intended (ie formatted like actual code) or they can view it online. github automatically syntax highlights all code in repo.
I use the wiki to set up links to course documents (addenda’s, assignments, links to resources, links to course notes etc. For larger documents (like course notes) I create links to them from the wiki (as a complete aside, I love gitbook.com for notes… write it once using markdown, get a web site /pdf/mobi and epub version of the notes).
For me, I opening up my course material to the world is not an issue so I typically keep this repository public but if you wish to restrict access, make the repository as private to your organization and grant only members of your organization access. You can also use the issue tracker as a discussion board for your students. If your students watch the repo they will get notified of changes to it. Here is a link to one of my course repos: https://github.com/seneca-btp500/btp500-f17
Accepting Student Work Through Github
Accepting work through github typically involves creating repositories for your students and granting appropriate access. You can then clone all their repositories to your computer once they have pushed up their work and go through their work on your local computer. NOTE: git generally does not deal well with binaries. Get your students to not push up any of their binary files (like .exe, .obj, .png etc.). binaries tend to bloat the repo and make it much slower to clone.
One change that github made over the years that you need to be very careful about is the default repository permission of the organization. It use to be that the default permission was none. At some time in the point in time, github changed it to Read. This means that every member can read every private repo in the organization. Thus if you provide a bunch of private repos to your students for their individual homework (ie each student has their own), those repos would end up being visible to every other student in the org. You can change this default permission to none in settings.
github classroom is not something I’m familiar with. I used a very early version of it and it has likely changed by now. With it, you can create a repository and then send a link out to your students. When they click the link it sets up their repos automatically under your organization. This is probably the easiest way for you to create repos for your students. The claim is that you do not need to collect your student’s github ids… my problem (at least with the early version) was not so much as getting the ids but associating a github id with a student’s real name. However, perhaps an easy way to deal with this would be to have your student modify the readme so that their name is in it. I’ll try it out next term and update this post again.
Creating Repos/Teams for Your Students Manually
Once you have created your organization, you can go to your organization settings and create teams. A team consist of 1 or more individual. As the administrator of the organization you will be able to see all the repos so if you forget to add yourself its no big deal. Each team also has different access permissions. Typically I would set up a student team for write access but not admin access. If you are only planning on doing group work then set up each team so that all members are part of that group. If you plan to do individual work or a mix of team and individual work then you will want to set up a team for each student.
Once you have the teams set, you can then create private repositories. You can initialize them with an empty readme (or push some code up by following the instructions). In any case once you have created those repos, you can give access to 1 or more “teams” by hitting the collaborator button in the settings tab.
Only teams with access to a particular private repos can see that repo. So its a great way for groups to all contribute to a project because you can limit who sees what. As a teacher, if each student actually submits their own stuff (and not email around and have one person do it) you can actually see their commits down to the line they put in through the blame button.
For those of you who can run bash scripts I wrote some scripts that can automate the creation/cloning/deletion of repositories for an organization. You can gather info from your students with a google form then download the data as a csv file. Modify the script according to the comments. Then run them.
Getting students to unlearn the code collaboration method they had been working with for years is a definite challenge. Putting in some best practices may be a good idea. Here is something I wrote up for the students in my research team to help them do this:
To ensure that we are not going to step all over each others code, these are the steps we will use when putting code into the repository:
- All commits should be accompanied by an issue. If there is no issue for your commit, please make one first!
- All commits should be put into a branch matching the issue number. Thus, if the problem the code is solving is described in issue 2, then the branch should be named issue2
- before pushing your code to github make sure you merge in the most recent code on master to your branch and resolve any conflicts
- push your code into the remote issue branch (if you want to work off your own fork then thats fine but issue branch on your fork)
- submit a pull request for the code that you have submitted but DO NOT merge that code yourself.
- assign someone else to review your pull request
- if you are assigned a pull request, test out the pull request on your local machine BEFORE accepting it. Do not just click the button. If there are any problems, comment and let the submitter know and have them fix it. If all goes well accept the pull request to merge into master
There are other methods out there… but you probably will need to invest some time to teach whatever that method is.
About git and git clients
git is the revision control system that github is built on. To get the most out of github, it is a good idea to learn at least some basics of git.
Dan Shiffman has some pretty nice videos on both git and github: https://www.youtube.com/playlist?list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV
My colleague David Humphrey’s did a git/github talk at fsoss 2015 (note sound gets better about 1 min into video). It talks about some of the more advance features of git and might give a better sense of what git is all about: https://www.youtube.com/watch?v=VKArpO69cIw
My workshops for showing students how git works via github (I got the idea from the Dan Shiffman videos). Essentially the first activity introduces git terminology using the github UI. The second activity does the same thing as activity one but on the command line. Activity 3….needs a bit of work: https://github.com/cathyatseneca/gitworkshop-s17/wiki
As git was built for handling code for the linux project, it is part of all linux distributions so if you are running linux, you already have git installed (unless it is a really really old linux release). For OSX git is installed as part of command line tools for xcode (type git in the terminal command prompt to see if its installed). For windows, you can download it from: http://git-scm.com/downloads
The above are command line tools for using git… and this is all you need locally for git and github.
Everyone tells me that gui’s are awesome… so github does provide some fancy gui clients for git (https://help.github.com/articles/set-up-git
Tortoise git is what one of my student use to swear by… so that may be worth looking at (http://code.google.com/p/tortoisegit/)
I tend to prefer the command line myself so I can’t speak to either unfortunately.
Anyhow, hope this is useful to others trying to figure this out. Let me know what would make this even more useful for you