This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Divekit CLI

Complete reference of all available Divekit CLI commands

1 - divekit install

The ‘install’ command downloads and installs any required dependencies for the Divekit CLI or your project environment.

Installs the divekit CLI and the required modules.

Example

$ divekit install

Installing divekit in home directory...
[√] divekit installed in home directory
[√] divekit executable added to PATH

2 - divekit init

The ‘init’ command sets up a new Divekit project environment, generating the necessary configuration files with sensible defaults.

[!WARNING] Not yet implemented

Initializes a new Divekit origin repository by creating the necessary configuration files.
(npm init and git init provide the expected functionality)

Example

$ divekit init

This utility will walk you through creating the
necessary configuration files to turn this current
folder into an `origin` Divekit repository.

It only covers the most common items, and tries to
guess sensible defaults.

Press ^C at any time to quit.

? Repository name: ST2-{{now "2006"}}-{{uuid}}
? Distribution [milestone]:  test
? Use default structure [Y/n]: n
? Repository target   group id: 234567
? Repository test     group id: 345678
? Repository members csv [members.csv]:  ./../members.csv

Repository configuration created at `./.divekit_norepo/distribution/test/`

$ ls -a .divekit_norepo/distribution/test/
repositoryConfig.json

3 - divekit doctor

The ‘doctor’ command checks your system environment, verifies prerequisites, and detects common configuration issues to ensure the CLI is functioning properly.

[!WARNING] was originally called divekit init and should be renamed, because other functionality might be expected due to git init and npm init.

divekit doctor is an in-depth diagnosis of the entire environment. It provides a comprehensive analysis and detailed information about potential issues. It is a kind of “first-aid tool” that offers concrete solutions or even automatically fixes problems.

Flutter uses flutter doctor for similar functionality, so divekit doctor could be appropriate.

[!NOTE] Works, only token verification is still missing.

divekit doctor (some checks failed)

$ divekit doctor

System:
[√] git available
[√] npm available
[√] Modules installed
    • 'Automated Repo Setup' available
    • 'Repo Editor' available
[X] Token not found
    • Please provide a GitLab API token via `divekit doctor --glpat <YOUR_TOKEN>`
    • You can create a new token at https://gitlab.git.nrw/-/user_settings/personal_access_tokens?name=git.nrw/divekit&scopes=api

Origin:
[√] Config available and valid
[√] No orphan variables found
[√] No hardcoded variations found

Distribution:
• supervisor:
    [√] All remotes are reachable
    [√] All NoChange files are equal to local files
• students:
    [!] No remotes found
        • Run `divekit distribute --distribution students` to distribute the repositories

divekit doctor (all checks passed)

$ divekit doctor

System:
[√] git available
[√] npm available
[√] Modules installed
    • 'Automated Repo Setup' available
    • 'Repo Editor' available
[√] Token is valid and has the necessary permissions

Origin:
[√] Config available and valid
[√] No orphan variables found
[√] No hardcoded variations found

Distribution:
• supervisor:
    [√] All remotes are reachable
    [√] All NoChange files are equal to local files
• students:
    [√] All remotes are reachable
    [√] All NoChange files are equal to local files

divekit doctor list

List all available checks with short explanations:

$ divekit doctor list

You can call single checks or check groups by calling
`$ divekit doctor check <comma-separated-dot-notated-paths>`

Example:
`$ divekit doctor check system.token
[√] Token is valid and has the necessary permissions
`

system    - checks all children
  git     - checks if `git` is accessible
  npm     - checks if `npm` is accessible
  modules - checks if module dependencies are accessible
  token   - checks if the token is accessible and valid

origin                 - checks all children
  config               - checks if the origin config is valid
  orphan_variables     - checks if orphan variable names were found
  hardcoded_variations - checks if hardcoded variations were found

distribution           - checks all children
  <distribution_name>  - checks all children
    remotes_reachable  - checks if all configured remotes are reachable
    no_change_files    - checks if files not to be changed were changed

divekit doctor check

execute specific checks:

$ divekit doctor check system.token
[√] Token is valid and has the necessary permissions

$ divekit doctor check origin.config
[√] Config is available and valid

$ divekit doctor check system.token,origin.config
System:
  [√] Token is valid and has the necessary permissions
Origin:
  [√] Config is available and valid

4 - divekit distribute

The ‘distribute’ command creates multiple repositories on GitLab based on the configurations in .divekit.

[!WARNING] was originally called divekit setup and was renamed because setup sounds like local preparation and not like distribution across multiple repositories.

Creates multiple repositories on GitLab based on the configurations in repositoryConfig.json.

[!NOTE] Only partially functional - style still different

  • Only creates repos with members
    • no test repos
    • no overview
  • Members are assigned directly
  • Members are checked but simply ignored

Beispiel Ablauf

$ divekit distribute

? Found several distributions. Please choose one:
[ ] local
[x] supervisor
[ ] student

Checking members:
[√] 2 user available 
[X] 3 users not found:
    - ada
    - charles
    - jobs

Would create 2 repository with name "ST2-2024-{uuid}" and assign 2 members.

? Continue? [Y/n]: y

Creating main repositories at #234567:
[██████████████████████████████████████████████████] 100% (2/2)

Creating test repositories at #345678:
[██████████████████████████████████████████████████] 100% (2/2)

Assigning members:
[███████████████████████████                         ] 50% (1/2)

5 - divekit patch

The ‘patch’ command allows you to update files inside the distributed repositories.

Patch one or several files in all the repos of a certain distribution of the origin repo

Usage:
  divekit patch [flags] [files...]

Flags:
  -d, --distribution string   name of the repo-distribution to patch
  -h, --help                  help for patch

e.g.:

$ divekit patch --distribution "supervisor" E2WhateverTests.java pom.xml

example of divekit patch command

Example Flow (first draft)

$ divekit patch --distribution "supervisor" E2WhateverTests.java pom.xml 

? Please type your commit message [Patch applied on 2024-10-04 08:42]: make some tests optional

Following repositories will be updated:
[√] (215x) supervisor::ST2-2024-{uuid}
[√] (215x) supervisor::ST2-2024-{uuid}-test

? Continue? [Y/n]: y

Updating repositories:
[███████████                                ] 42% (90/215)

$ divekit patch E2WhateverTests.java pom.xml 

? Found several distributions. Please choose one:
[x] local
[ ] supervisor
[ ] student

Following repositories will be updated:
[√] (215x) local::ST2-2024-{uuid}
[√] (215x) local::ST2-2024-{uuid}-test

? Continue? [Y/n]: y

Updating repositories:
[███████████                                ] 42% (90/215)

6 - divekit overview

The ‘overview’ command allows you to.
$ divekit overview --distribution students

Using:
- {DIVEKIT_HOME}/members/divekit-members-8125814e-01da-42dd-8be3-29df5dcd760e.json

Serving on http://localhost:8080

Opening browser...

Depending on how the current overview file is used, the html could be created dynamically.

…or it could be stored as html and/or markdown in the origin repo, next to the files that store the members.

7 - divekit config

The ‘config’ command manages CLI configuration settings, similar to ‘git config’, allowing you to customize the CLI behavior.
$ divekit config

Usage:
  divekit config <command> <flags>

Available Commands:
    list         List configuration values
    get          Get configuration values
    set          Set configuration values
    unset        Unset configuration values

Flags:
    -h, --help   help for config
    -g, --global use global configuration

Examples

Listing all configuration values

divekit config list

You can get single values by calling
`$ divekit config get <dot-notated-path>`

Example:
`$ divekit config get origin.remotes.name

STM2-{{uuid}}
`

origin        - the origin configuration
  version     - the version of the origin configuration
  remotes     - information about the distributed remotes
    name      - the name of the remote with template variables
    groupIds  - the group IDs of the remote with template variables
      main    - the main group ID
      test    - the test group ID
  membersPath - the path to the members file

Importing members from a CSV file

divekit config set origin.membersPath --import /path/to/members.csv

This command imports the members from the specified CSV file. The CSV should contain usernames (e.g., campusIDs) in the first column.

Import latecomers from a CSV file

divekit config set origin.membersPath --import /path/to/members.csv

Import and overwrite existing members

divekit config set origin.membersPath --import /path/to/members.csv --replace

Adding individual members

divekit config set origin.membersPath --add john.doe,jane.smith

This command adds two new members (John Doe and Jane Smith) to the existing list of members.

Adding a group of members

divekit config set origin.membersPath --add-groups team-a:alice.jones,bob.wilson

This command adds a new group named “team-a” with two members (Alice Jones and Bob Wilson).

Distributing repositories for latecomers

divekit distribute

This command distributes repositories for members who were added after the initial distribution.
(--sync, --refresh, or just no flags if we know which ones are missing)

8 - divekit update

The ‘update’ command checks for new versions of the CLI and applies updates as necessary.

checks for a newer version and starts an update

Example Process

$ divekit update -y

Checking for updates...
Current version: 0.0.1
Latest version: 0.0.2

Downloading update...
Applying update...
Update applied successfully

New version: 0.0.2

$ divekit update -y

Checking for updates...
Current version: 0.0.2
Latest version: 0.0.2

Already up to date