Notice: We have released a web based tool for teachers. teachers_pet will remain availble, but we recommend teachers use Classroom for GitHub instead.
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_petIf you've used this tool before, get the newest version using
gem update teachers_petTo use the latest-and-greatest code from this repository, see the instructions in CONTRIBUTING.md.
...when using the sandboxing method with private repositories:
-
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 teachers_pet.
# replace YOUR_TOKEN_HERE below
echo "\n\nexport TEACHERS_PET_GITHUB_TOKEN=YOUR_TOKEN_HERE" >> ~/.bash_profile
source ~/.bash_profileTo learn the options for each action, run
teachers_pet help
# or
teachers_pet help COMMANDYou 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.
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. .gitignore, 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.
After running 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 open_issue command.
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.
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.