WARNING: This documentation may contain unreleased changes. See rubydoc.info/gems/teachers_pet for the version of this README corresponding to the latest release.
Command line tool to help teachers use GitHub in their classrooms.
Each class is an 'organization' on GitHub. This allows the instructors (GitHub organization Owners) to create, push, pull, and administer all repositories. This achieves two goals:
- Instructors can push code starter code to all students
- Instructors can easily browse/pull student code at any time during the assignment to assist in questions, check on progress
Each student is given a team in the organization. The team name is the same as the student's GitHub username.
Install Ruby 1.9.3+, then run
gem install teachers_pet
If you've used this tool before, get the newest version using
gem update teachers_pet
To use the latest-and-greatest code from this repository, see the instructions in CONTRIBUTING.md.
- Create an organization (you will be an owner by default). The organization should reflect the name of your course. See the classroom guide for more info.
- Have each student/instructor create GitHub accounts.
- Create a
studentsfile (you can use an alternate filename and specify with the
--studentsoption if you like)
- Individual assignments: one username per line
- Group assignments: one team per line in the format
teamName username username username
- Add the GitHub username of all instructors to an
Owners.csvfile (one per line)
Run the following:
teachers_pet create_student_teams ... teachers_pet add_to_team --members Owners.csv ...
teachers_pet create_repos ... teachers_pet push_files ... # Multiple times: teachers_pet open_issue ... # Then, after the assignment is due, teachers_pet clone_repos ...
The scripts will ask for your GitHub password in order to run. If you have two factor authentication (2FA) enabled, create a personal access token (replace
github.com with your host for GitHub Enterprise):
Once created, specify the token using the
--token option, or if you add the
TEACHERS_PET_GITHUB_TOKEN environment variable to your
.bash_profile (or equivalent – example below), it will be picked up by
# replace YOUR_TOKEN_HERE below echo "\n\nexport TEACHERS_PET_GITHUB_TOKEN=YOUR_TOKEN_HERE" >> ~/.bash_profile source ~/.bash_profile
To learn the options for each action, run
teachers_pet help # or teachers_pet help COMMAND
Giving others access
You may need to give other people access to various repositories using teams – the
add_to_team command can help do this in bulk.
When using the sandboxing setup, you will need to create the repositories for the students. For each assignment, use the
create_repos action to create a repository for each student. The repositories are technically created per team, but if you use
create_student_teams first, then there will be one team per student.
If you need to grab the list of users who have forked a particular repository – e.g. to use with another command – you can run the
forks command, and the results will be written to a file.
Give collaborator access to everyone who has forked your repository using
add_collaborators. Mostly useful for GitHub demonstrations, where usernames can quickly be collected via
forks, and then the students can be quickly given access to a repository.
Pushing starter files
When creating repositories for students, you will often want to include boilerplate files. After running
create_repos, create a canonical copy of the starter files (e.g.
Makefiles, etc.) in a repository. From the local clone of the repository, use the
push_files action to place that code in the repositories for each student. This works by creating a Git remote for each student repository, and doing a
git push to each one.
create_repos, instructors can open issues in student repos as a way to list requirements of the assignment, goals, or instructions for patching, using the
Clone repositories for grading
When grading, use the
clone_repos command to clone all the repositories in the organization that match the username-repository naming scheme that is generated when
create_repos is run.
Merge all open pull requests
When running a GitHub workshop, it's nice to be able to merge a bunch of pull requests on a particular repository all at once.
merge_pull_requests will handle this for you.