Roster

Objective

This tool helps you manage your GitHub Classroom roster by identifying students who need to be added, removed, or whose group has changed, based on a list of enrolled students. Since GitHub does not provide an API for roster management, you must apply these changes manually through the GitHub Classroom web interface.

NOTE: This application is part of a toolkit for managing classes with GitHub Classroom. It is recommended to first read the main repository to get an overview of the project and understand how this tool fits in.

Use Cases

First, obtain a list of students enrolled in your course and their lab groups. How you get this list depends on your institution. Once you have it, you can provide it to the tool in various formats (Excel, text, CSV, etc.).

The application provides two commands:

• create — prints a list of students to add to the classroom roster.
• update — compares your student list with the existing roster and prints students to add, remove, or whose group has changed.

# Create a roster from a student file (prints students to add)
java -jar roster.jar create -s schedule.csv -f sies alumnosMatriculados.xls

# Update an existing roster (prints additions, removals, and changes)
java -jar roster.jar update  -r classroom_roster.csv -s schedule.csv -f sies alumnosMatriculados.xls

The previous examples show the default values of the options. So they can be simplified to:

java -jar roster.jar create

java -jar roster.jar update

Example output for the update command applied to a list of students stored in CSV format in the file alumnos.txt:

$ java -jar roster.jar update -r classroom_roster.csv -f csv alumnos.txt

## Students to add to the roster

Instructions:
- Go to the Classroom page.
- Click the 'Students' tab.
- Click the 'Update Students' button.
- Select and copy all the lines below at once, then paste them into the 'Create your roster manually' text area.

Izquierdo Castanedo, Raúl (01)
González Pérez, Juan (i02)

## Students to remove from the roster

Instructions:
- Go to the Classroom page.
- Click the 'Students' tab.
- For each of the following lines:
	- Find the student with that roster ID and click the "trash" icon.

Rodríguez, María (01)
Gómez, Ana (i01)

## Students who have changed groups

Instructions:
- Go to the Classroom page.
- Click the 'Students' tab.
- For each of the following lines:
	- Find the student using the old roster ID (shown on the left side of the arrow) and click the "pen" icon.
	- Replace the old roster ID with the new one (shown on the right side of the arrow).

González, Juan (02) ---> González Pérez, Juan (03)
Valles, Pedro (i01) ---> Valle, Pedro (i02)
Ramírez, Lucía (01) ---> Ramírez, Lucía (02)

Usage

The JAR can be downloaded from the releases page.

Syntax:

java -jar roster.jar <command> [OPTIONS] [<students-file>]

Commands:

• create — prints the students to add (based on the students file, optionally filtered by groups)
• update — prints students to add, remove, or whose group has changed (requires the roster CSV)

Options:

• students-file: The file containing the students and their groups. (default: "alumnosMatriculados.xls")
• -f : The format of the students file. Supported: "excel", "csv", "sies". (default: "sies"). See Student File Formats for details.
• -r <roster.csv>: The roster CSV exported from GitHub Classroom (used only with the 'update' command). (default: "classroom_roster.csv"). See Obtaining the Roster file for instructions on how to obtain this file.
• -s <groups.txt>: A file with the teacher’s groups. (default: "schedule.csv") See Groups File Format for details.
• -h, --help: Show help.

Student File Formats

This tool supports three student file formats: sies, csv, and excel. The format can be specified with the -f option.

SIES Format

This is the format generated by the SIES information system (University of Oviedo). It is only used by teachers at this university.

The groups are named removing the prefix and any language indication. For example:

• "Prácticas de Laboratorio-01" -> "01"
• "Prácticas de Laboratorio-Inglés-02" -> "i02"

CSV Format

The CSV file must have two columns (with no header row):

• Student name
• Group (any text identifying the group)

Example:

"Izquierdo Castanedo, Raúl", 01
"González, Juan", i02

NOTE: Remember to use quotes around names that contain commas or special characters.

Excel Format

This format is exactly the same as the CSV format (two columns, no header row).

Groups File Format

Usually, a teacher does not teach all the groups in a course. To filter the output to only include students belonging to the teacher’s groups, create a groups file. Only students in these groups will be included in the output.

If all the groups are taught by the same teacher, just add all the groups to this file.

The groups file is a simple text file with one group per line. The group names must match those in the students file.

01
02
i01

CSV files with more than one column are allowed, but only the first column is considered. In fact, it is recommended to use the same schedule.csv file used in the solutions tool:

01, monday, 10:00
02, tuesday, 11:00
i01, wednesday, 12:00

Once you have this file, you can use it with both the create and update commands using the -s flag:

java -jar roster.jar create -s mygroups.txt -f sies alumnosMatriculados.xls

If no groups file is provided, the file schedule.csv is used by default.

License

See LICENSE. Copyright (c) 2025 Raul Izquierdo Castanedo