CLI documentation¶

A CLI tool for administrating large amounts of git repositories on GitHub and GitLab instances. Read the docs at: https://repobee.readthedocs.io

Loaded plugins: distmanager-3.8.0, pluginmanager-3.8.0

usage: repobee [-h] [-v] [-c CONFIG_FILE] [-p PLUG | --no-plugins]
               {repos,teams,issues,reviews,config,plugin,manage} ...

Positional Arguments¶

category: Possible choices: repos, teams, issues, reviews, config, plugin, manage

Named Arguments¶

-v, --version

display version info

-c, --config-file

Specify path to the config file to use.

-p, --plug

Specify the name of a plugin to use.

--no-plugins

Disable plugins.

Default: False

Sub-commands:¶

repos¶

Manage repositories.

repobee repos [-h] {setup,update,clone,migrate} ...

Positional Arguments¶

action: Possible choices: setup, update, clone, migrate

Sub-commands:¶

setup¶

Setup student repositories based on master repositories. This command performs three primary actions: sets up the student teams, creates one student repository for each master repository and finally pushes the master repo files to the corresponding student repos. It is perfectly safe to run this command several times, as any previously performed step will simply be skipped.

repobee repos setup [-h] -u USER -o ORG_NAME --bu BASE_URL -t TOKEN [--tb]
                    [-q] (--sf STUDENTS_FILE | -s STUDENTS [STUDENTS ...])
                    [--to TEMPLATE_ORG_NAME] -a ASSIGNMENTS [ASSIGNMENTS ...]
                    [--hook-results-file HOOK_RESULTS_FILE]
                    [--allow-local-templates]

Named Arguments¶

--sf, --students-file

path to a list of student usernames or groups of students

-s, --students

One or more whitespace separated student usernames.

-a, --assignments

one or more names of assignments

--allow-local-templates

allow the use of template repos in the current working directory

Default: False

platform arguments¶

Arguments related to the platform (e.g. GitHub or GitLab)

-u, --user: your username
-o, --org-name: name of the target organization
--bu, --base-url: Base url to a platform API. Must be HTTPS. For example, with github.com, the base url is https://api.github.com, and with GitHub enterprise, the url is https://<ENTERPRISE_HOST>/api/v3
-t, --token: access token for the platform instance
--to, --template-org-name: name of the organization containing the template repos (defaults to the same value as -o|–org-name)

debug arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

alpha arguments¶

Arguments that are currently being trialed in alpha, and may change without further notice

--hook-results-file: path to a .json file to store results from plugin hooks in

update¶

Push changes from master repos to student repos. If the –issue option is provided, the specified issue is opened in any repo to which pushes fail (because the students have pushed something already).

repobee repos update [-h] -u USER -o ORG_NAME --bu BASE_URL -t TOKEN [--tb]
                     [-q] (--sf STUDENTS_FILE | -s STUDENTS [STUDENTS ...])
                     [--to TEMPLATE_ORG_NAME] -a ASSIGNMENTS [ASSIGNMENTS ...]
                     [--allow-local-templates] [-i ISSUE]

Named Arguments¶

--sf, --students-file

path to a list of student usernames or groups of students

-s, --students

One or more whitespace separated student usernames.

-a, --assignments

one or more names of assignments

--allow-local-templates

allow the use of template repos in the current working directory

Default: False

-i, --issue

path to issue file to open in repos to which pushes fail (NOTE: first line is assumed to be the title)

platform arguments¶

Arguments related to the platform (e.g. GitHub or GitLab)

-u, --user: your username
-o, --org-name: name of the target organization
--bu, --base-url: Base url to a platform API. Must be HTTPS. For example, with github.com, the base url is https://api.github.com, and with GitHub enterprise, the url is https://<ENTERPRISE_HOST>/api/v3
-t, --token: access token for the platform instance
--to, --template-org-name: name of the organization containing the template repos (defaults to the same value as -o|–org-name)

debug arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

clone¶

Clone student repos asynchronously in bulk.

repobee repos clone [-h] -u USER -o ORG_NAME --bu BASE_URL -t TOKEN [--tb]
                    [-q] (--sf STUDENTS_FILE | -s STUDENTS [STUDENTS ...])
                    (-a ASSIGNMENTS [ASSIGNMENTS ...] | --discover-repos)
                    [--hook-results-file HOOK_RESULTS_FILE] [--update-local]
                    [--dl {flat,by-team}]

Named Arguments¶

--sf, --students-file

path to a list of student usernames or groups of students

-s, --students

One or more whitespace separated student usernames.

-a, --assignments

one or more names of assignments

--discover-repos

discover all repositories for the specified students (NOTE: expensive in terms of API calls)

Default: False

--update-local

attempt to update local student repositories, stashing any unstaged changes (beta feature)

Default: False

--dl, --directory-layout

Possible choices: flat, by-team

how to arrange cloned repositories

Default: by-team

platform arguments¶

Arguments related to the platform (e.g. GitHub or GitLab)

-u, --user: your username
-o, --org-name: name of the target organization
--bu, --base-url: Base url to a platform API. Must be HTTPS. For example, with github.com, the base url is https://api.github.com, and with GitHub enterprise, the url is https://<ENTERPRISE_HOST>/api/v3
-t, --token: access token for the platform instance

debug arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

alpha arguments¶

Arguments that are currently being trialed in alpha, and may change without further notice

--hook-results-file: path to a .json file to store results from plugin hooks in

migrate¶

Migrate repositories into the target organization. The repos must be local on disk to be migrated. Note that migrated repos will be private.

repobee repos migrate [-h] -a ASSIGNMENTS [ASSIGNMENTS ...] -u USER -o
                      ORG_NAME --bu BASE_URL -t TOKEN [--tb] [-q]
                      [--allow-local-templates]

Named Arguments¶

-a, --assignments

one or more names of assignments

--allow-local-templates

allow the use of template repos in the current working directory

Default: False

platform arguments¶

Arguments related to the platform (e.g. GitHub or GitLab)

-u, --user: your username
-o, --org-name: name of the target organization
--bu, --base-url: Base url to a platform API. Must be HTTPS. For example, with github.com, the base url is https://api.github.com, and with GitHub enterprise, the url is https://<ENTERPRISE_HOST>/api/v3
-t, --token: access token for the platform instance

debug arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

teams¶

Manage teams.

repobee teams [-h] {create} ...

Positional Arguments¶

action: Possible choices: create

Sub-commands:¶

create¶

Only create student teams. This is intended for when you want to use RepoBee for management, but don’t want to dictate the names of your student’s repositories. The setup command performs this step automatically, so there is never a need to run both this command AND setup.

repobee teams create [-h] -u USER -o ORG_NAME --bu BASE_URL -t TOKEN [--tb]
                     [-q] (--sf STUDENTS_FILE | -s STUDENTS [STUDENTS ...])

Named Arguments¶

--sf, --students-file: path to a list of student usernames or groups of students
-s, --students: One or more whitespace separated student usernames.

platform arguments¶

Arguments related to the platform (e.g. GitHub or GitLab)

-u, --user: your username
-o, --org-name: name of the target organization
--bu, --base-url: Base url to a platform API. Must be HTTPS. For example, with github.com, the base url is https://api.github.com, and with GitHub enterprise, the url is https://<ENTERPRISE_HOST>/api/v3
-t, --token: access token for the platform instance

debug arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

issues¶

Manage issues.

repobee issues [-h] {open,close,list} ...

Positional Arguments¶

action: Possible choices: open, close, list

Sub-commands:¶

open¶

Open issues in student repositories. For each master repository specified, the student list is traversed. For every student repo found, the issue specified by the –issue option is opened. NOTE: The first line of the issue file is assumed to be the issue title!

repobee issues open [-h] -u USER -o ORG_NAME --bu BASE_URL -t TOKEN [--tb]
                    [-q] (--sf STUDENTS_FILE | -s STUDENTS [STUDENTS ...]) -a
                    ASSIGNMENTS [ASSIGNMENTS ...]
                    (-i ISSUE | --hook-results-file HOOK_RESULTS_FILE)

Named Arguments¶

--sf, --students-file: path to a list of student usernames or groups of students
-s, --students: One or more whitespace separated student usernames.
-a, --assignments: one or more names of assignments
-i, --issue: path to an issue file (NOTE: first line is assumed to be the title)
--hook-results-file: path to a hook result JSON file with issues to open

platform arguments¶

Arguments related to the platform (e.g. GitHub or GitLab)

-u, --user: your username
-o, --org-name: name of the target organization
--bu, --base-url: Base url to a platform API. Must be HTTPS. For example, with github.com, the base url is https://api.github.com, and with GitHub enterprise, the url is https://<ENTERPRISE_HOST>/api/v3
-t, --token: access token for the platform instance

debug arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

close¶

Close issues in student repos based on a regex. For each master repository specified, the student list is traversed. For every student repo found, any open issues matching the –title-regex are closed.

repobee issues close [-h] -u USER -o ORG_NAME --bu BASE_URL -t TOKEN [--tb]
                     [-q] (--sf STUDENTS_FILE | -s STUDENTS [STUDENTS ...])
                     (-a ASSIGNMENTS [ASSIGNMENTS ...] | --discover-repos) -r
                     TITLE_REGEX

Named Arguments¶

--sf, --students-file

path to a list of student usernames or groups of students

-s, --students

One or more whitespace separated student usernames.

-a, --assignments

one or more names of assignments

--discover-repos

discover all repositories for the specified students (NOTE: expensive in terms of API calls)

Default: False

-r, --title-regex

regex to filter issues by

platform arguments¶

Arguments related to the platform (e.g. GitHub or GitLab)

-u, --user: your username
-o, --org-name: name of the target organization
--bu, --base-url: Base url to a platform API. Must be HTTPS. For example, with github.com, the base url is https://api.github.com, and with GitHub enterprise, the url is https://<ENTERPRISE_HOST>/api/v3
-t, --token: access token for the platform instance

debug arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

list¶

List issues in student repos.

repobee issues list [-h] -u USER -o ORG_NAME --bu BASE_URL -t TOKEN [--tb]
                    [-q] (--sf STUDENTS_FILE | -s STUDENTS [STUDENTS ...])
                    (-a ASSIGNMENTS [ASSIGNMENTS ...] | --discover-repos)
                    [--hook-results-file HOOK_RESULTS_FILE]
                    [--double-blind-key KEY] [-r TITLE_REGEX] [-b]
                    [--author AUTHOR] [--open | --closed | --all]

Named Arguments¶

--sf, --students-file

path to a list of student usernames or groups of students

-s, --students

One or more whitespace separated student usernames.

-a, --assignments

one or more names of assignments

--discover-repos

discover all repositories for the specified students (NOTE: expensive in terms of API calls)

Default: False

-r, --title-regex

regex to filter issues by

-b, --show-body

show the body of the issue, alongside the default info

Default: False

--author

only show issues by this author

--open

list open issues (default)

Default: IssueState.OPEN

--closed

list closed issues

Default: IssueState.OPEN

--all

list all issues (open and closed)

Default: IssueState.OPEN

platform arguments¶

Arguments related to the platform (e.g. GitHub or GitLab)

-u, --user: your username
-o, --org-name: name of the target organization
--bu, --base-url: Base url to a platform API. Must be HTTPS. For example, with github.com, the base url is https://api.github.com, and with GitHub enterprise, the url is https://<ENTERPRISE_HOST>/api/v3
-t, --token: access token for the platform instance

debug arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

alpha arguments¶

Arguments that are currently being trialed in alpha, and may change without further notice

--hook-results-file: path to a .json file to store results from plugin hooks in
--double-blind-key: key (any string) to use for double-blind peer review(alpha feature)

reviews¶

Manage peer reviews.

repobee reviews [-h] {assign,check,end} ...

Positional Arguments¶

action: Possible choices: assign, check, end

Sub-commands:¶

assign¶

For each student repo, create a review team with read access named <student-repo-name>-review and randomly assign other students to it. All students are assigned to the same amount of review teams, as specified by –num-reviews. Note that –num-reviews must be strictly less than the amount of students. Note that review allocation strategy may be altered by plugins.

repobee reviews assign [-h] -u USER -o ORG_NAME --bu BASE_URL -t TOKEN [--tb]
                       [-q] (--sf STUDENTS_FILE | -s STUDENTS [STUDENTS ...])
                       -a ASSIGNMENTS [ASSIGNMENTS ...]
                       [--double-blind-key KEY] [-n N] [-i ISSUE]

Named Arguments¶

--sf, --students-file

path to a list of student usernames or groups of students

-s, --students

One or more whitespace separated student usernames.

-a, --assignments

one or more names of assignments

-n, --num-reviews

assign each student to review n repos, n < amount of students

Default: 1

-i, --issue

path to an issue file with review instructions to open in student repos (NOTE: first line is assumed to be the title)

platform arguments¶

Arguments related to the platform (e.g. GitHub or GitLab)

-u, --user: your username
-o, --org-name: name of the target organization
--bu, --base-url: Base url to a platform API. Must be HTTPS. For example, with github.com, the base url is https://api.github.com, and with GitHub enterprise, the url is https://<ENTERPRISE_HOST>/api/v3
-t, --token: access token for the platform instance

debug arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

alpha arguments¶

Arguments that are currently being trialed in alpha, and may change without further notice

--double-blind-key: key (any string) to use for double-blind peer review(alpha feature)

check¶

Check which students have opened review review issues in their assigned repos. As it is possible for students to leave the peer review teams on their own, the command checks that each student is assigned to the expected amound of teams. There is currently no way to check if students have been swapped around, so using this command fow grading purposes is not recommended.

repobee reviews check [-h] -u USER -o ORG_NAME --bu BASE_URL -t TOKEN [--tb]
                      [-q] (--sf STUDENTS_FILE | -s STUDENTS [STUDENTS ...])
                      -a ASSIGNMENTS [ASSIGNMENTS ...]
                      [--double-blind-key KEY] -n N -r TITLE_REGEX

Named Arguments¶

--sf, --students-file: path to a list of student usernames or groups of students
-s, --students: One or more whitespace separated student usernames.
-a, --assignments: one or more names of assignments
-n, --num-reviews: the expected amount of reviews each student should be assigned, used to check for team tampering
-r, --title-regex: issues matching this regex will count as review issues.

platform arguments¶

Arguments related to the platform (e.g. GitHub or GitLab)

-u, --user: your username
-o, --org-name: name of the target organization
--bu, --base-url: Base url to a platform API. Must be HTTPS. For example, with github.com, the base url is https://api.github.com, and with GitHub enterprise, the url is https://<ENTERPRISE_HOST>/api/v3
-t, --token: access token for the platform instance

debug arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

alpha arguments¶

Arguments that are currently being trialed in alpha, and may change without further notice

--double-blind-key: key (any string) to use for double-blind peer review(alpha feature)

end¶

Delete review allocations assigned with assign-reviews. This is a destructive action, as the allocations for reviews are irreversibly deleted. The purpose of this command is to revoke the reviewers’ read access to reviewed repos, and to clean up the allocations (i.e. deleting the review teams when using GitHub, or groups when using GitLab). It will however not do anything with the review issues. You can NOT run check-reviews after end-reviews, as the former needs the allocations to function properly. Use this command only when reviews are done.

repobee reviews end [-h] -u USER -o ORG_NAME --bu BASE_URL -t TOKEN [--tb]
                    [-q] (--sf STUDENTS_FILE | -s STUDENTS [STUDENTS ...]) -a
                    ASSIGNMENTS [ASSIGNMENTS ...] [--double-blind-key KEY]

Named Arguments¶

--sf, --students-file: path to a list of student usernames or groups of students
-s, --students: One or more whitespace separated student usernames.
-a, --assignments: one or more names of assignments

platform arguments¶

Arguments related to the platform (e.g. GitHub or GitLab)

-u, --user: your username
-o, --org-name: name of the target organization
--bu, --base-url: Base url to a platform API. Must be HTTPS. For example, with github.com, the base url is https://api.github.com, and with GitHub enterprise, the url is https://<ENTERPRISE_HOST>/api/v3
-t, --token: access token for the platform instance

debug arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

alpha arguments¶

Arguments that are currently being trialed in alpha, and may change without further notice

--double-blind-key: key (any string) to use for double-blind peer review(alpha feature)

config¶

Configure RepoBee.

repobee config [-h] {show,verify,wizard} ...

Positional Arguments¶

action: Possible choices: show, verify, wizard

Sub-commands:¶

show¶

Show the contents of the configuration file. If no configuration file can be found, show the path where repobee expectes to find it.

repobee config show [-h] [--secrets] [--tb] [-q]

Named Arguments¶

--secrets

show secrets in the config file that are otherwise sanitized

Default: False

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

verify¶

Verify core settings by trying various API requests.

repobee config verify [-h] -u USER -o ORG_NAME --bu BASE_URL -t TOKEN [--tb]
                      [-q] [--to TEMPLATE_ORG_NAME] [--sf STUDENTS_FILE]

Named Arguments¶

--sf, --students-file: path to a list of student usernames or groups of students

platform arguments¶

Arguments related to the platform (e.g. GitHub or GitLab)

-u, --user: your username
-o, --org-name: name of the target organization
--bu, --base-url: Base url to a platform API. Must be HTTPS. For example, with github.com, the base url is https://api.github.com, and with GitHub enterprise, the url is https://<ENTERPRISE_HOST>/api/v3
-t, --token: access token for the platform instance
--to, --template-org-name: name of the organization containing the template repos (defaults to the same value as -o|–org-name)

debug arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

wizard¶

A configuration wizard that sets up the configuration file. Warns if there already is a configuration file, as it will be overwritten.

repobee config wizard [-h] [--tb] [-q]

Named Arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

plugin¶

Manage plugins.

repobee plugin [-h] {install,activate,uninstall,list} ...

Positional Arguments¶

action: Possible choices: install, activate, uninstall, list

Sub-commands:¶

install¶

Install a plugin. Running this command without options starts an interactive installer, where you can select plugin and version to install. Plugins can also be installed non-interactively with the (mutually exclusive) ‘–plugin-spec’ or ‘–local’ options.

repobee plugin install [-h] [--tb] [-q]
                       [--local LOCAL | --plugin-spec PLUGIN_SPEC | --git-url GIT_URL]

Named Arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

--local

path to a local plugin to install, either a single file or a plugin package

--plugin-spec

a plugin specifier on the form ‘<NAME>@<VERSION>’ (e.g. ‘junit4@v1.0.0’) to do a non-interactive install of an official plugin

--git-url

url to a Git repository to install a plugin from (e.g. ‘https://github.com/repobee/repobee-junit4.git’), optionally followed by a version specifier ‘@<VERSION>’ (e.g. ‘https://github.com/repobee/repobee-junit4.git@v1.0.0’)

activate¶

Activate and deactivate plugins. Running the command without options starts an interactive wizard for toggling the active-status of all installed plugins. Specifying the ‘–plugin-name’ option non-interactively toggles the active-status for a single plugin.

repobee plugin activate [-h] [--tb] [-q] [--plugin-name PLUGIN_NAME]

Named Arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

--plugin-name

a plugin to toggle activation status for (non-interactive)

uninstall¶

Uninstall a plugin. Running this command without options starts an interactive uninstall wizard. Running with the ‘–plugin-name’ option non-interactively uninstall the specified plugin.

repobee plugin uninstall [-h] [--tb] [-q] [--plugin-name PLUGIN_NAME]

Named Arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

--plugin-name

name of a plugin to uninstall (non-interactive)

list¶

List available plugins. Available plugins are fetched from https://repobee.org.

repobee plugin list [-h] [--tb] [-q] [--plugin-name PLUGIN_NAME]

Named Arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

--plugin-name

A plugin to list detailed info for.

manage¶

Manage the RepoBee installation.

repobee manage [-h] {upgrade} ...

Positional Arguments¶

action: Possible choices: upgrade

Sub-commands:¶

upgrade¶

Upgrade RepoBee to the latest version. You can also specify a specific version to install with the –version-spec option.

repobee manage upgrade [-h] [--tb] [-q] [--version-spec VERSION_SPEC]

Named Arguments¶

--tb, --traceback

show the full traceback of critical exceptions

Default: False

-q, --quiet

silence output (stacks up to 3 times: x1=only warnings and errors, x2=only errors, x3=complete and utter silence)

Default: 0

--version-spec

specify a version to install, as described here: https://pip.pypa.io/en/stable/reference/pip_install/#requirement-specifiers