{"id":42883980,"url":"https://github.com/raul-izquierdo/roster","last_synced_at":"2026-02-20T20:03:30.794Z","repository":{"id":309578100,"uuid":"1036800901","full_name":"raul-izquierdo/roster","owner":"raul-izquierdo","description":"Helps to update the roster when the students enroll or change groups","archived":false,"fork":false,"pushed_at":"2026-02-19T12:44:07.000Z","size":164,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-19T16:45:01.323Z","etag":null,"topics":["github-classroom"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raul-izquierdo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-12T15:48:31.000Z","updated_at":"2026-02-19T12:44:10.000Z","dependencies_parsed_at":"2025-08-12T18:13:34.776Z","dependency_job_id":"c4db258f-cca3-43a5-8108-8e31c7087ae3","html_url":"https://github.com/raul-izquierdo/roster","commit_stats":null,"previous_names":["raul-izquierdo/roster"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/raul-izquierdo/roster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raul-izquierdo%2Froster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raul-izquierdo%2Froster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raul-izquierdo%2Froster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raul-izquierdo%2Froster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raul-izquierdo","download_url":"https://codeload.github.com/raul-izquierdo/roster/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raul-izquierdo%2Froster/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29662591,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T19:49:36.704Z","status":"ssl_error","status_checked_at":"2026-02-20T19:44:05.372Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github-classroom"],"created_at":"2026-01-30T14:45:09.239Z","updated_at":"2026-02-20T20:03:30.789Z","avatar_url":"https://github.com/raul-izquierdo.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Roster\n\n## Objective\n\nThis tool helps you manage your GitHub Classroom roster by identifying students who need to be added, removed, or whose groups have 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.\n\u003e **NOTE:** Although this tool can be used **independently**, it is part of a toolkit for managing classes with GitHub Classroom. It is recommended to **first read** the [main repository](https://github.com/raul-izquierdo/classroom-tools) to get an overview of the project and understand how this tool fits in.\n\n## Use Cases\n\n### Creating a Roster\n\nWhen you first create a classroom, you need to add all your students to the roster. This tool can help you generate the list of students to add.\n\nThe required steps are:\n- Obtain a list of students enrolled in your course and their lab groups. How you obtain this list depends on your institution. Once you have it, you can provide it to the tool in [various formats](#student-file-formats) (Excel, SIES, CSV, etc.).\n- Typically, a teacher does not teach all the groups in a course. Create a group file to filter the output to include only students belonging to the teacher’s groups. Pass the name of this file with the flag `-s`. If that flag is not used, the file name is assumed to be `schedule.csv`. See [Groups File Format](#groups-file-format) for details.\n\nWith this information, you can run the tool to generate the list of students to add to your classroom roster. Here are examples with different student file formats:\n```bash\njava -jar roster.jar create -f sies alumnosMatriculados.xls\n```\n\n```bash\njava -jar roster.jar create -s mygroups.csv -f excel students.xls\n```\n\n```bash\njava -jar roster.jar create -s groups.csv -f csv students.txt\n```\n\nTo avoid having to repeat those arguments in every use of the tool, you can create an `.env` file in the current directory with the name and format of your students file:\n```bash\nSTUDENTS_FILE=\"alumnosMatriculados.xls\"\nSTUDENTS_FORMAT=\"sies\"\n```\n\nNow you can simply run:\n```bash\njava -jar roster.jar create\n```\n\nThe output will list the students to add to the roster along with **instructions** on how to do so. For example:\n\n```bash\n$ java -jar roster.jar create\n\n## Students to add to the roster\nInstructions:\n- Go to the Classroom page.\n- Click the 'Students' tab.\n- Click the 'Add Students' button.\n- Select and copy all the lines below at once, then paste them into the 'Create your roster manually' text area.\n\nIzquierdo Castanedo, Raúl (01)\nGonzález Pérez, Juan (i02)\n...\n```\n\nRemember that GitHub Classroom does not provide an API to manage the roster, so you must apply these changes manually through the web interface.\n\n### Updating a Roster\n\nWhen the semester is underway, students may add or drop the course, or change their lab groups. This tool can help you identify these changes by comparing your current list of enrolled students with the existing classroom roster.\n\nTo update an existing roster, you need:\n- An **updated** version of the enrolled students.\n- The **existing** classroom roster exported from GitHub Classroom. See [Obtaining the Roster file](https://github.com/raul-izquierdo/classroom-tools#obtaining-the-roster-file) for instructions on how to obtain this file. If you keep the name generated by GitHub Classroom, you don't need to specify it, as the default name is `classroom_roster.csv`.\n\nWith this information, you can run the tool to generate a list of students to add, remove, or whose groups have changed.\n```bash\njava -jar roster.jar update -r classroom_roster.csv -s schedule.csv -f sies alumnosMatriculados.xls\n```\n\nOr, using the `.env` file mentioned earlier and the default names for the roster and groups files, just run:\n```bash\njava -jar roster.jar update\n```\n\nExample output for the **update** command, which includes instructions to apply the changes manually:\n\n```bash\n$ java -jar roster.jar update\n\n## Students to add to the roster\n\nInstructions:\n- Go to the Classroom page.\n- Click the 'Students' tab.\n- Click the 'Update Students' button.\n- Select and copy all the lines below at once, then paste them into the 'Create your roster manually' text area.\n\nIzquierdo Castanedo, Raúl (01)\nGonzález Pérez, Juan (i02)\n\n## Students to remove from the roster\n\nInstructions:\n- Go to the Classroom page.\n- Click the 'Students' tab.\n- For each of the following lines:\n\t- Find the student with that roster ID and click the \"trash\" icon.\n\nRodríguez, María (01)\nGómez, Ana (i01)\n\n## Students who have changed groups\n\nInstructions:\n- Go to the Classroom page.\n- Click the 'Students' tab.\n- For each of the following lines:\n\t- Find the student using the old roster ID (shown on the left side of the arrow) and click the \"pen\" icon.\n\t- Replace the old roster ID with the new one (shown on the right side of the arrow).\n\nGonzález, Juan (02) ---\u003e González Pérez, Juan (03)\nValles, Pedro (i01) ---\u003e Valle, Pedro (i02)\nRamírez, Lucía (01) ---\u003e Ramírez, Lucía (02)\n```\n\n## Usage\n\nThe JAR can be downloaded from the [releases page](https://github.com/raul-izquierdo/roster/releases).\n\nSyntax:\n\n```bash\njava -jar roster.jar \u003ccommand\u003e [OPTIONS] [\u003cstudents-file\u003e]\n```\n\nCommands:\n- **create** — prints the students to add to the roster\n- **update** — prints students to add, remove, or whose groups have changed since the last roster update\n\nOptions:\n- **students-file**: The file containing the students.\n- **-f \u003cformat\u003e**: The format of the students file. Supported: \"excel\", \"csv\", \"sies\". See [Student File Formats](#student-file-formats) for details.\n- **-r \u003croster.csv\u003e**: The roster CSV exported from GitHub Classroom (used only with the 'update' command). (default: \"classroom_roster.csv\"). See [Obtaining the Roster file](https://github.com/raul-izquierdo/classroom-tools#obtaining-the-roster-file) for instructions on how to obtain this file.\n- **-s \u003cgroups.txt\u003e**: A file with the teacher’s groups. (default: \"schedule.csv\") See [Groups File Format](#groups-file-format) for details.\n- **-h, --help**: Show help.\n\n## Student File Formats\n\nThe method for obtaining the list of students depends on the institution. To be flexible enough to accommodate different scenarios, this tool supports three student file formats: **sies**, **csv**, and **excel**. The format can be specified with the `-f` option.\n\n### SIES Format\n\nThis format is generated by the SIES information system (University of Oviedo). This format is only available for teachers at that university. In this case, the tool is used as follows:\n\n```bash\njava -jar roster.jar create -f sies alumnosMatriculados.xls\n```\n\nThe groups will be created by extracting the group information from the file, removing the prefix and any language indication. For example, the following group names will be transformed as follows:\n- \"Prácticas de Laboratorio-01\" -\u003e \"01\"\n- \"Prácticas de Laboratorio-Inglés-02\" -\u003e \"i02\"\n\n### CSV Format\n\nThis is a generic format that can be generated from any system. You can create it manually or export it from Excel or any other spreadsheet program.\n\nThe CSV file must have two columns (with no header row):\n- Student name. There is no required format, but it is recommended to use \"Last Name, First Name\" to facilitate sorting.\n- Group. Likewise, there is no required format, but it is recommended to use a simple format such as \"01\", \"english-02\", \"i02\", etc.\n\nExample:\n\n```csv\n\"Izquierdo Castanedo, Raúl\", group01\n\"González, Juan\", english_group_02\n\"Alonso, Mariano\", group01\n\"Rodríguez, Javier\", group02\n```\n**NOTE:** Remember to **use quotes** around names that **contain commas** or special characters.\n\nWith this file, you can run the tool as follows:\n\n```bash\njava -jar roster.jar create -f csv students.csv\n```\n\n### Excel Format\n\nThis format must be **exactly the same** as the CSV format:\n- The first two columns of the Excel file must contain the student name and their group.\n- The first row must not be a header row.\n\nTo run the tool with an Excel file, use:\n\n```bash\njava -jar roster.jar create -f excel students.xls\n```\n\n## Groups File Format\n\nThis file contains the groups taught by the teacher. If all the groups are taught by the same teacher, simply add all the groups to this file.\n\nThe groups file is a simple text file with one group per line. The group names must match those in the students file.\n\n```csv\n01\n02\ni01\n```\n\nCSV files with more than one column are allowed, but only the first column is considered. In fact, if `roster.jar` is going to be used along with the rest of the tools in [classroom-tools](https://github.com/raul-izquierdo/classroom-tools), it is recommended to use the same `schedule.csv` file used in the [solutions](https://github.com/raul-izquierdo/solutions#schedule-file-format) tool:\n\n```csv\n01, monday, 10:00\n02, tuesday, 11:00\ni01, wednesday, 12:00\n```\n\nOnce you have this file, you can use it with both the `create` and `update` commands using the `-s` flag:\n\n```bash\njava -jar roster.jar create -s mygroups.txt -f sies alumnosMatriculados.xls\n```\n\nIf no groups file is provided, the name `schedule.csv` is used by default.\n\n## Exit Codes\n\nThe exit codes indicate the result of the command execution:\n\n- **0**: No changes proposed. The roster is up to date.\n- **1**: Changes were proposed. The user should review the output and apply the changes manually.\n- **2**: An error occurred.\n\n## License\n\nSee `LICENSE`.\nCopyright (c) 2025 Raul Izquierdo Castanedo\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraul-izquierdo%2Froster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraul-izquierdo%2Froster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraul-izquierdo%2Froster/lists"}