Command-line Interface

This section contains an overview of command-line applications shipped with this package.

devtool

Commands that interact directly with GitLab.

Commands defined here are supposed to interact with gitlab, and add/modify/remove resources on it directly.

To avoid repetitive asking, create a configuration file as indicated at Automated GitLab interaction section of the user guide.

devtool [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

badges

Create stock badges for a project repository.

devtool badges [OPTIONS] PACKAGE

Options

--update-readme, --no-update-readme

Whether to update badges in the readme or not.

-d, --dry-run, --no-dry-run

Only goes through the actions, but does not execute them (combine with the verbosity flags - e.g. -vvv) to enable printing to help you understand what will be done

-s, --server <server>

The documentation server. Default value is https://www.idiap.ch/software/{group}

-v, --verbose

Increase the verbosity level from 0 (only error and critical) messages will be displayed, to 1 (like 0, but adds warnings), 2 (like 1, but adds info messags), and 3 (like 2, but also adds debugging messages) by adding the –verbose option as often as desired (e.g. ‘-vvv’ for debug).

Default:

0

Arguments

PACKAGE

Required argument

Examples:

1. Creates (by replacing) all existing badges in a gitlab project (software/idiap-devtools):

   devtool gitlab badges software/idiap-devtools
   

Note

This command also affects the README.md file.

changelog

Generate changelog file for package(s) from the Gitlab server.

This script generates changelogs for either a single package or multiple packages, depending on the value of TARGET. The changelog (in markdown format) is written to the output file CHANGELOG.

There are two modes of operation: you may provide the package name in the format <gitlab-group>/<package-name>. Or, optionally, provide an existing file containing a list of packages that will be iterated on.

For each package, we will contact the Gitlab server and create a changelog using merge-requests (default), tags or commits since a given date. If a starting date is not passed, we’ll use the date of the last tagged value or the date of the first commit, if no tags are available in the package.

devtool changelog [OPTIONS] TARGET...

Options

-o, --output <output>

-m, --mode <mode>

Changes the way we produce the changelog. By default, uses the text in every merge request (mode “mrs”). To use tag annotations, use mode “tags”. If you use “commits” as mode, we use the text in commits to produce the changelog

Default:

mrs

Options:

mrs | tags | commits

-s, --since <since>

A starting date in any format accepted by dateutil.parser.parse() (see https://dateutil.readthedocs.io/en/stable/parser.html) from which you want to generate the changelog. If not set, the package’slast release date will be used

-v, --verbose

Increase the verbosity level from 0 (only error and critical) messages will be displayed, to 1 (like 0, but adds warnings), 2 (like 1, but adds info messags), and 3 (like 2, but also adds debugging messages) by adding the –verbose option as often as desired (e.g. ‘-vvv’ for debug).

Default:

0

Arguments

TARGET

Required argument(s)

Examples:

1. Generates the changelog for a single package using merge requests, outputs results to a file named changelog.md, in markdown format:

   devtool gitlab changelog -vv group/package.xyz -o changelog.md
   

2. The same as above, but dumps the changelog to stdout instead of a file:

   devtool gitlab changelog -vv group/package.xyz
   

3. Generates the changelog for a single package looking at commits (not merge requests):

   devtool gitlab changelog -vv --mode=commits group/package.xyz
   

4. Generates the changelog for a single package looking at merge requests starting from a given date of January 1, 2016:

   devtool gitlab changelog -vv --mode=mrs --since=2016-01-01 group/package.xyz
   

5. Generates the changelog for a set of packages, listed one per line in a text file:

   devtool gitlab changelog -vv --mode=mrs --since=2016-01-01 group/package.xyz
   

getpath

Download files and directories from gitlab.

Files are downloaded and stored. Directories are recursed and fully downloaded to the client.

devtool getpath [OPTIONS] PACKAGE PATH [OUTPUT]

Options

-r, --ref <ref>

Download path from the provided git reference (may be a branch, tag or commit hash). If not set, then use the default package branch as reference to download.

-v, --verbose

Increase the verbosity level from 0 (only error and critical) messages will be displayed, to 1 (like 0, but adds warnings), 2 (like 1, but adds info messags), and 3 (like 2, but also adds debugging messages) by adding the –verbose option as often as desired (e.g. ‘-vvv’ for debug).

Default:

0

Arguments

PACKAGE

Required argument

PATH

Required argument

OUTPUT

Optional argument

Examples:

1. Get the directory gitlab (and eventual sub-directories) from software/dev-profile:

   devtool getpath software/dev-profile gitlab
   

jobs

List jobs on a given runner identified by description.

devtool jobs [OPTIONS] [TAGS]...

Options

-s, --status <status>

The status of jobs we are searching for - one of “running”, “success”, “failed” or “canceled”

Default:

running

Options:

running | success | failed | canceled

-v, --verbose

Increase the verbosity level from 0 (only error and critical) messages will be displayed, to 1 (like 0, but adds warnings), 2 (like 1, but adds info messags), and 3 (like 2, but also adds debugging messages) by adding the –verbose option as often as desired (e.g. ‘-vvv’ for debug).

Default:

0

Arguments

TAGS

Optional argument(s)

Examples:

1. List running jobs on any runners with tag “bob” (default):

   devtool gitlab jobs -vv
   

2. List running jobs on a runner with tag “macos”:

   devtool gitlab jobs -vv macos
   

3. List running jobs on a runner with tag “macos” and “foo”:

   devtool gitlab jobs -vv macos foo
   

lasttag

Return the last tag information on a given PACKAGE.

devtool lasttag [OPTIONS] PACKAGE

Options

-v, --verbose

Increase the verbosity level from 0 (only error and critical) messages will be displayed, to 1 (like 0, but adds warnings), 2 (like 1, but adds info messags), and 3 (like 2, but also adds debugging messages) by adding the –verbose option as often as desired (e.g. ‘-vvv’ for debug).

Default:

0

Arguments

PACKAGE

Required argument

Examples:

1. Get the last tag information of the software/clapp package:

   devtool gitlab lasttag software/clapp
   

2. Get the last tag information of the beat/beat.core package:

   devtool gitlab lasttag beat/beat.core
   

release

Tags packages on GitLab from an input CHANGELOG in markdown format.

By using a CHANGELOG file as an input (e.g. that can be generated with the changelog command), this script goes through all packages listed (and in order):

• Modifies pyproject.toml with the new release number

• Sets-up the README links to point to the correct pipeline and documentation for the package

• Commits, tags and pushes the git project adding the changelog description for the GitLab release page

• Waits for the pipeline launched by the previous step to end

• Bumps the package version again, to the next beta patch

• Re-modifies the README to point to the “latest” documentation and pipeline versions

• Re-commits and pushes the whole with the option [ci skip].

The changelog is expected to have the following structure:

# group-name/package-name: ``major``|``minor``|``patch``

  Description of changes in group-name/package-name

# group-name/package-name-2: ``major``|``minor``|``patch``

  Description of changes in group-name/package-name-2

The headings, each, correspond to package names, followed by a colon (:), and then one of the following keywords: major, minor, or patch, indicating which part of the version number will be bumped during the release procedure (N.B.: following semantic version numbering).

An indented piece of text marks the release notes for the package to be tagged, in any amount of detail. The description of a single package is suffixed by another package heading, or the end of the file.

You may use GitLab-flavoured markdown (GLFM) to refer to closed issues or merge requests. Alternatively, use the command changelog to auto-generate the description for your release.

devtool release [OPTIONS] CHANGELOG

Options

-d, --dry-run, --no-dry-run

Only goes through the actions, but does not execute them (combine with the verbosity flags - e.g. -vvv) to enable printing to help you understand what will be done

-v, --verbose

Increase the verbosity level from 0 (only error and critical) messages will be displayed, to 1 (like 0, but adds warnings), 2 (like 1, but adds info messags), and 3 (like 2, but also adds debugging messages) by adding the –verbose option as often as desired (e.g. ‘-vvv’ for debug).

Default:

0

Arguments

CHANGELOG

Required argument

Examples:

1. Runs the release procedure for all packages listed in changelog.md:

   devtool gitlab release -vv changelog.md
   

   Tip

   In case of errors, just edit the changelog file to remove packages already released before relaunching the application.

2. The option --dry-run can be used to let the script print what it would do instead of actually doing it:

   devtool gitlab release -vv --dry-run changelog.md
   

runners

Commands for handling runners.

devtool runners [OPTIONS] COMMAND [ARGS]...

disable

Disables runners on whole gitlab groups or single projects.

You may provide project names (like “group/project”), whole groups, files containing list of projects to load or omit the last argument, in which case all projects using this runner will be affected.

devtool runners disable [OPTIONS] NAME [TARGETS]...

Options

-d, --dry-run, --no-dry-run

Only goes through the actions, but does not execute them (combine with the verbosity flags - e.g. -vvv) to enable printing to help you understand what will be done

-v, --verbose

Increase the verbosity level from 0 (only error and critical) messages will be displayed, to 1 (like 0, but adds warnings), 2 (like 1, but adds info messags), and 3 (like 2, but also adds debugging messages) by adding the –verbose option as often as desired (e.g. ‘-vvv’ for debug).

Default:

0

Arguments

NAME

Required argument

TARGETS

Optional argument(s)

Examples:

1. Disables the runner with description “macmini” in project software/clapp and software/auto-intersphinx:

   devtool gitlab runners disable -vv macmini software/clapp software/auto-intersphinx
   

1. Disables the runner with description “macmini” for all projects in group software:

   devtool gitlab runners disable -vv macmini software
   

2. Disables the runner with description “macpro” on all projects it is associated to. Notice this command effectively deletes the runner from the gitlab instance:

   devtool gitlab runners disable -vv pro
   

enable

Enable runners on whole gitlab groups or single projects.

You may provide project names (like “group/project”), whole groups, and files containing list of projects to enable at certain runner at.

devtool runners enable [OPTIONS] NAME TARGETS...

Options

-g, --group, --no-group

If set, consider the the provided name as a group name

-d, --dry-run, --no-dry-run

Only goes through the actions, but does not execute them (combine with the verbosity flags - e.g. -vvv) to enable printing to help you understand what will be done

-v, --verbose

Increase the verbosity level from 0 (only error and critical) messages will be displayed, to 1 (like 0, but adds warnings), 2 (like 1, but adds info messags), and 3 (like 2, but also adds debugging messages) by adding the –verbose option as often as desired (e.g. ‘-vvv’ for debug).

Default:

0

Arguments

NAME

Required argument

TARGETS

Required argument(s)

Examples:

1. Enables the runner with description “linux-srv01” on all projects inside groups “group1” and “group2”:

   devtool gitlab runners enable --group -vv linux-srv01 group1 group2
   

2. Enables the runner with description “linux-srv02” on a specific project:

   devtool gitlab runners enable -vv linux-srv02 group1/my-project
   

list

List projects a runner is associated to.

devtool runners list [OPTIONS] NAME

Options

-v, --verbose

Increase the verbosity level from 0 (only error and critical) messages will be displayed, to 1 (like 0, but adds warnings), 2 (like 1, but adds info messags), and 3 (like 2, but also adds debugging messages) by adding the –verbose option as often as desired (e.g. ‘-vvv’ for debug).

Default:

0

Arguments

NAME

Required argument

Examples:

1. Lists all projects a runner is associated to:

   devtool gitlab runners list -vv macmini
   

settings

Update project settings.

devtool settings [OPTIONS] PROJECTS...

Options

-a, --avatar <avatar>

Set this to update the project icon (avatar)

-D, --description <description>

Set this to update the project description

-g, --group, --no-group

If set, consider the the provided name as a group name

-A, --archive, --unarchive

Set this to archive or unarchive a project

-d, --dry-run, --no-dry-run

Only goes through the actions, but does not execute them (combine with the verbosity flags - e.g. -vvv) to enable printing to help you understand what will be done

-v, --verbose

Increase the verbosity level from 0 (only error and critical) messages will be displayed, to 1 (like 0, but adds warnings), 2 (like 1, but adds info messags), and 3 (like 2, but also adds debugging messages) by adding the –verbose option as often as desired (e.g. ‘-vvv’ for debug).

Default:

0

Arguments

PROJECTS

Required argument(s)

Examples:

1. List settings in a gitlab project (software/idiap-devtools):

2. Simulates an update to the project description: