pkgdev

Synopsis

pkgdev [-h] [–version] [–debug] [-q] [-v] [–color BOOLEAN] {bugs,commit,manifest,mask,push,showkw,tatt} …

Base Options

-h, --help

show this help message and exit

--version

show this program’s version info and exit

--debug

enable debugging checks

-q, --quiet

suppress non-error messages

-v, --verbose

show verbose output

--color BOOLEAN

enable/disable color support

Subcommands

pkgdev bugs - Automatic bugs filer

Synopsis

pkgdev bugs [–config CONFIG_FILE] [–domain DOMAIN] [-h] [–debug] [–color BOOLEAN] [–api-key TOKEN] [–dot DOT] [–edit-graph] [–auto-cc-arches EMAIL] [–find-by-maintainer EMAIL] [–projects] [–filter-stablereqs] [–blocks BUG] [-s | -k] [-a ARCH] [–commits [tree-ish] | –staged [tree-ish]] [–git-remote REMOTE] [-p PROFILE] [–stabletime DAYS] [target …]

Positional Arguments

target

extended atom matching of packages

Options

--api-key TOKEN

The Bugzilla API key to use for authentication. WARNING: using this option will expose your API key to other users of the same system. Consider instead saving your API key in a file named ~/.bugzrc in an INI format like so:

[default]
key = <your API key>

Another supported option is to save your API key in a file named ~/.bugz_token.

--dot DOT

path file where to save the graph in dot format

--edit-graph

When this argument is passed, pkgdev will open the graph in the editor (either $VISUAL or $EDITOR) before filing bugs. The graph is represented in TOML format. After saving and exiting the editor, the tool would use the graph from the file to file bugs.

--auto-cc-arches EMAIL

Comma separated list of email addresses, for which automatically add CC-ARCHES if one of the maintainers matches the email address. If the package is maintainer-needed, always add CC-ARCHES.

--find-by-maintainer EMAIL

Comma separated list of email addresses, for which pkgdev will collect all packages maintained by.

Note that this flag requires to go over all packages in the repository to find matches, which can be slow (between 1 to 3 seconds).

--projects

Include packages maintained by projects, whose members include the emails of maintainers passed to --find-by-maintainer.

Note that this flag requires to fetch the projects.xml file from https://api.gentoo.org.

--filter-stablereqs

Filter targets passed to pkgdev (command line, stabilization groups, maintainer search, stdin) for packages with active StableRequest result.

--blocks BUG

Collection of bug ids which should be blocked by newly created bugs. Only bugs created for passed targets would be blockers, excluding other bugs which were created as dependencies.

-s, --stablereq

File stable request bugs

-k, --keywording

File rekeywording bugs

--stabletime DAYS

An integer number of days before a package version is flagged by StableRequestCheck. Defaults to 30 days.

Config Options

--config CONFIG_FILE

Load custom pkgdev scan settings from a given file.

Note that custom user settings override all other system and repo-level settings.

It’s also possible to disable all types of settings loading by specifying an argument of ‘false’ or ‘no’.

--domain DOMAIN

custom pkgcore domain to use for this operation

Base Options

-h, --help

Show this help message and exit. To get more information see the related man page.

--debug

Enable debug checks and show verbose debug output.

--color BOOLEAN

Toggle colored output support. This can be used to forcibly enable color support when piping output or other situations where stdout is not a tty.

Arches

-a, --arches ARCH

Comma separated list of arches to enable and disable.

To specify disabled arches prefix them with ‘-’. Note that when starting the argument list with a disabled arch an equals sign must be used, e.g. -a=-arch, otherwise the disabled arch argument is treated as an option.

By default all repo defined arches are used; however, stable-related checks (e.g. UnstableOnly) default to the set of arches having stable profiles in the target repo.

Git

Git repo support for various checks.

Pkgcheck can create virtual package repos from a given git repo’s history in order to provide more info for checks relating to stable requests, outdated blockers, or local commits. These virtual repos are cached and updated every run if new commits are detected.

Git repos must have a supported config in order to work properly. Specifically, pkgcheck assumes that the origin branch exists and tracks upstream.

Additionally, the origin/HEAD ref must exist. If it doesn’t, running git remote set-head origin master or similar for other branches will create it.

You can override the default git remote used for all git comparison using --git-remote.

--commits [tree-ish]

Targets are determined from the committed changes compared to a given reference that defaults to the repo’s origin.

For example, to scan all the packages that have been changed in the current branch compared to the branch named ‘old’ use pkgcheck scan --commits old. For two separate branches named ‘old’ and ‘new’ use pkgcheck scan --commits old..new.

--staged [tree-ish]

Targets are determined using all staged changes for the git repo. Unstaged changes and untracked files are ignored by temporarily stashing them during the scanning process.

--git-remote REMOTE

The git remote to be used for all operations by pkgcheck. The default value, and the recommended value is origin, but you can use any valid git remote name.

Profiles

-p, --profiles PROFILE

Comma separated list of profiles to enable and disable for scanning. Any profiles specified in this fashion will be the only profiles that get scanned, skipping any disabled profiles. In addition, if no profiles are explicitly enabled, all profiles defined in the target repo’s profiles.desc file will be scanned except those marked as experimental (exp).

To specify disabled profiles prefix them with - which removes the from the list of profiles to be considered. Note that when starting the argument list with a disabled profile an equals sign must be used, e.g. -p=-path/to/profile, otherwise the disabled profile argument is treated as an option.

The special keywords of stable, dev, exp, and deprecated correspond to the lists of stable, development, experimental, and deprecated profiles, respectively. Therefore, to only scan all stable profiles pass the stable argument to –profiles. Additionally the keyword all can be used to scan all defined profiles in the target repo.

pkgdev commit - create git commit

Synopsis

pkgdev commit [–config CONFIG_FILE] [–domain DOMAIN] [-h] [–debug] [-q] [-v] [–color BOOLEAN] [-b BUG] [-c CLOSES[:RESOLUTION]] [-T NAME:VALUE] [-n] [-s [BOOLEAN]] [-A [BOOLEAN]] [–mangle [BOOLEAN]] [–signoff [BOOLEAN]] [–gpg-sign | –no-gpg-sign] [-d DISTDIR] [-m MSG | -M FILE] [-e] [-u | -a]

Config Options

--config CONFIG_FILE

Load custom pkgdev scan settings from a given file.

Note that custom user settings override all other system and repo-level settings.

It’s also possible to disable all types of settings loading by specifying an argument of ‘false’ or ‘no’.

--domain DOMAIN

custom pkgcore domain to use for this operation

Base Options

-h, --help

Show this help message and exit. To get more information see the related man page.

--debug

Enable debug checks and show verbose debug output.

-q, --quiet

Suppress non-error, informational messages.

-v, --verbose

Increase the verbosity of various output.

--color BOOLEAN

Toggle colored output support. This can be used to forcibly enable color support when piping output or other situations where stdout is not a tty.

Commit Options

-b, --bug BUG

add Bug tag for a given Gentoo or upstream bug

-c, --closes CLOSES[:RESOLUTION]

Indicate that a bug or PR may be closed. The optional resolution string for Gentoo’s Bugzilla describes what happened to a bug. It is case-insensitive and must be one of FIXED, OBSOLETE or PKGREMOVED.

-T, --tag NAME:VALUE

add commit tag

-n, --dry-run

Perform all actions without creating a commit.

-s, --scan [BOOLEAN]

By default, pkgdev commit doesn’t scan for QA errors. This option enables using pkgcheck to scan the staged changes for issues, erroring out if any failures are found.

-A, --ask [BOOLEAN]

When running with the -s/–scan option enabled, pkgdev commit will ask for confirmation before creating a commit if it detects failure results.

--mangle [BOOLEAN]

File mangling automatically modifies the content of relevant staged files including updating copyright headers and fixing EOF newlines.

This is performed by default for the gentoo repo, but can be forcibly disabled or enabled as required.

--signoff [BOOLEAN]

Add a Signed-off-by trailer by the committer at the end of the commit log message.

For committing to the Gentoo repository, under GLEP-76, the committer shall certify agreement to the Certificate of Origin by adding Signed-off-by line containing the committer’s legal name.

--gpg-sign, --no-gpg-sign

Pass --gpg-sign or --no-gpg-sign to the git commit command. This option enables to override the default behavior or the behavior defined by sign-commits = true in metadata/layout.conf file.

-d, --distdir DISTDIR

Use a specified target directory for downloads instead of the configured DISTDIR.

-m, --message MSG

Use a given message as the commit message. If multiple -m options are specified, their values are concatenated as separate paragraphs.

Note that the first value will be used for the commit summary and if it’s empty then a generated summary will be used if available.

-M, --message-template FILE

Use content from the given file as a commit message template. The commit summary prefix ‘*: ‘ is automatically replaced by a generated prefix if one exists for the related staged changes.

-e, --edit

This option will ask git to open the commit message in an editor before commit. The git configuration is used to select the editor.

-u, --update

stage all changed files

-a, --all

stage all changed/new/removed files

pkgdev manifest - update package manifests

Synopsis

pkgdev manifest [–config CONFIG_FILE] [–domain DOMAIN] [-h] [–debug] [-q] [-v] [–color BOOLEAN] [-d DISTDIR] [-f] [-m] [–if-modified] [–ignore-fetch-restricted] [target …]

Positional Arguments

target

Packages matching any of these restrictions will have their manifest entries updated. If no target is specified a path restriction is created based on the current working directory. In other words, if pkgdev manifest is run within an ebuild’s directory, all the ebuilds within that directory will be manifested.

Config Options

--config CONFIG_FILE

Load custom pkgdev scan settings from a given file.

Note that custom user settings override all other system and repo-level settings.

It’s also possible to disable all types of settings loading by specifying an argument of ‘false’ or ‘no’.

--domain DOMAIN

custom pkgcore domain to use for this operation

Base Options

-h, --help

Show this help message and exit. To get more information see the related man page.

--debug

Enable debug checks and show verbose debug output.

-q, --quiet

Suppress non-error, informational messages.

-v, --verbose

Increase the verbosity of various output.

--color BOOLEAN

Toggle colored output support. This can be used to forcibly enable color support when piping output or other situations where stdout is not a tty.

Manifest Options

-d, --distdir DISTDIR

Use a specified target directory for downloads instead of the configured DISTDIR.

-f, --force

Force package manifest files to be rewritten. Note that this requires downloading all distfiles.

-m, --mirrors

Enable checking Gentoo mirrors first for distfiles. This is disabled by default because manifest generation is often performed when adding new ebuilds with distfiles that aren’t on Gentoo mirrors yet.

--if-modified

In addition to matching the specified restriction, restrict to targets which are marked as modified by git, including untracked files.

--ignore-fetch-restricted

Ignore attempting to update manifest entries for ebuilds which are fetch restricted.

pkgdev mask - mask packages

Synopsis

pkgdev mask [-h] [–debug] [-q] [-v] [–color BOOLEAN] [–api-key TOKEN] [-r [DAYS]] [-b BUGS] [–email] [–file-bug] [TARGET …]

Positional Arguments

TARGET

Packages matching any of these restrictions will have a mask entry in profiles/package.mask added for them. If no target is specified a path restriction is created based on the current working directory. In other words, if pkgdev mask is run within an ebuild’s directory, all the ebuilds within that directory will be masked.

Options

--api-key TOKEN

The Bugzilla API key to use for authentication. WARNING: using this option will expose your API key to other users of the same system. Consider instead saving your API key in a file named ~/.bugzrc in an INI format like so:

[default]
key = <your API key>

Another supported option is to save your API key in a file named ~/.bugz_token.

Base Options

-h, --help

Show this help message and exit. To get more information see the related man page.

--debug

Enable debug checks and show verbose debug output.

-q, --quiet

Suppress non-error, informational messages.

-v, --verbose

Increase the verbosity of various output.

--color BOOLEAN

Toggle colored output support. This can be used to forcibly enable color support when piping output or other situations where stdout is not a tty.

Mask Options

-r, --rites [DAYS]

Mark a mask entry for last rites. This defaults to 30 days until package removal but accepts an optional argument for the number of days.

-b, --bug, --bugs BUGS

Add a reference to a bug in the mask comment. May be specified multiple times to reference multiple bugs.

--email

Spawn user’s preferred email composer with a prepared email for sending a last rites message to Gentoo’s mailing list (gentoo-dev and gentoo-dev-announce). The user should manually set the Reply-to field for the message to be accepted by gentoo-dev-announce.

For spawning the preferred email composer, the xdg-email tool from x11-misc/xdg-utils package.

--file-bug

Files a last-rite bug for the masked package, which blocks listed reference bugs. PMASKED keyword is added all all referenced bugs.

pkgdev push - run QA checks on commits and push them

Synopsis

pkgdev push [–config CONFIG_FILE] [–domain DOMAIN] [-h] [–debug] [-q] [-v] [–color BOOLEAN] [-A [BOOLEAN]] [-n] [–pull]

Config Options

--config CONFIG_FILE

Load custom pkgdev scan settings from a given file.

Note that custom user settings override all other system and repo-level settings.

It’s also possible to disable all types of settings loading by specifying an argument of ‘false’ or ‘no’.

--domain DOMAIN

custom pkgcore domain to use for this operation

Base Options

-h, --help

Show this help message and exit. To get more information see the related man page.

--debug

Enable debug checks and show verbose debug output.

-q, --quiet

Suppress non-error, informational messages.

-v, --verbose

Increase the verbosity of various output.

--color BOOLEAN

Toggle colored output support. This can be used to forcibly enable color support when piping output or other situations where stdout is not a tty.

Push Options

-A, --ask [BOOLEAN]

confirm pushing commits with QA errors

-n, --dry-run

pretend to push the commits

--pull

run git pull –rebase before scanning

pkgdev showkw - show package keywords

Synopsis

pkgdev showkw [–config CONFIG_FILE] [–domain DOMAIN] [-h] [–debug] [-q] [-v] [–color BOOLEAN] [-f FORMAT] [-c] [-s] [-u] [-o] [-p] [-a ARCH] [-r REPO] [target …]

Positional Arguments

target

extended atom matching of packages

Config Options

--config CONFIG_FILE

Load custom pkgdev scan settings from a given file.

Note that custom user settings override all other system and repo-level settings.

It’s also possible to disable all types of settings loading by specifying an argument of ‘false’ or ‘no’.

--domain DOMAIN

custom pkgcore domain to use for this operation

Base Options

-h, --help

Show this help message and exit. To get more information see the related man page.

--debug

Enable debug checks and show verbose debug output.

-q, --quiet

Suppress non-error, informational messages.

-v, --verbose

Increase the verbosity of various output.

--color BOOLEAN

Toggle colored output support. This can be used to forcibly enable color support when piping output or other situations where stdout is not a tty.

Output Options

-f, --format FORMAT

Output table using specified tabular format (defaults to compressed, custom format).

Available formats: fancy_grid, fancy_outline, github, grid, html, jira, latex, latex_booktabs, latex_longtable, latex_raw, mediawiki, moinmoin, orgtbl, pipe, plain, presto, pretty, psql, rst, showkw, simple, textile, tsv, unsafehtml, youtrack

-c, --collapse

show collapsed list of arches

Arch Options

-s, --stable

show stable arches

-u, --unstable

show unstable arches

-o, --only-unstable

show arches that only have unstable keywords

-p, --prefix

show prefix and non-native arches

-a, --arch ARCH

select arches to display

Target Options

-r, --repo REPO

repo to query (defaults to all ebuild repos)

pkgdev tatt - package testing tool

Synopsis

pkgdev tatt [–config CONFIG_FILE] [–domain DOMAIN] [-h] [–debug] [–color BOOLEAN] [–api-key TOKEN] [-j NAME] [-b BUG] [-t] [-u NUMBER] [–ignore-prefixes IGNORE_PREFIXES] [–use-default | –use-random | –use-expand-random] [-p TARGET [TARGET …]] [-s | -k] [–template-file TEMPLATE_FILE] [–logs-dir LOGS_DIR] [–emerge-opts EMERGE_OPTS] [–extra-env-file ENV_FILE]

Options

--api-key TOKEN

The Bugzilla API key to use for authentication. WARNING: using this option will expose your API key to other users of the same system. Consider instead saving your API key in a file named ~/.bugzrc in an INI format like so:

[default]
key = <your API key>

Another supported option is to save your API key in a file named ~/.bugz_token.

-j, --job-name NAME

The job name to use for the job script and report. The name can use the variables {PN} (package name) and {BUGNO} (bug number) to created variable names.

-b, --bug BUG

Single bug to take package list from

Config Options

--config CONFIG_FILE

Load custom pkgdev scan settings from a given file.

Note that custom user settings override all other system and repo-level settings.

It’s also possible to disable all types of settings loading by specifying an argument of ‘false’ or ‘no’.

--domain DOMAIN

custom pkgcore domain to use for this operation

Base Options

-h, --help

Show this help message and exit. To get more information see the related man page.

--debug

Enable debug checks and show verbose debug output.

--color BOOLEAN

Toggle colored output support. This can be used to forcibly enable color support when piping output or other situations where stdout is not a tty.

Use Flags Options

-t, --test

Include a test run for packages which define src_test phase (in the ebuild or inherited from eclass).

-u, --use-combos NUMBER

Maximal number USE combinations to be tested

--ignore-prefixes IGNORE_PREFIXES

Comma separated USE flags prefixes that won’t be randomized. This is useful for USE flags such as python_targets_. Note that this doesn’t affect preference, but because of specific REQUIRED_USE will still be changed from defaults.

--use-default

Prefer to use default use flags configuration

--use-random

Turn on random use flags, with default USE_EXPAND

--use-expand-random

Turn on random use flags, including USE_EXPAND

Manual Packages Options

-p, --packages TARGET [TARGET ...]

extended atom matching of packages

-s, --stablereq

Test packages for stable keywording requests

-k, --keywording

Test packages for keywording requests

Template Options

--template-file TEMPLATE_FILE

Template file to use for the job script. The template file is a Jinja template file, which can use the following variables:

jobs

A list of jobs to be run. Each job is a tuple consisting of USE flags values, is a testing job, and the atom to build.

report_file

The path to the report file.

emerge_opts

Options to be passed to emerge invocations. Taken from --emerge-opts.

extra_env_files

A list of extra /etc/portage/env/ file names, to be added to package.env entry when testing the package. Taken from --extra-env-file.

log_dir

irectory to save build logs for failing tasks. Taken from --logs-dir.

cleanup_files

A list of files to be removed after the job script is done.

--logs-dir LOGS_DIR

Directory to save build logs for failing tasks

--emerge-opts EMERGE_OPTS

Space separated single argument, consisting og options to be passed to emerge invocations.

--extra-env-file ENV_FILE

Comma separated filenames under /etc/portage/env/, which will all be included in the package.env entry when testing the package.

Config file support

Config files are supported by most subcommands of pkgdev from any of three locations. Listed in order of increasing precedence these include the following:

• system config – /etc/pkgdev/pkgdev.conf

• user config – ${XDG_CONFIG_HOME}/pkgdev/pkgdev.conf

• user config – ~/.config/pkgdev/pkgdev.conf

• custom config – specified via the --config option

Any settings from a config file with higher precedence will override matching settings from a config file with a lower precedence, e.g. user settings override system settings. Note that command line options override any matching config file setting.

In terms of file structure, basic INI formatting is required and allows creating a default section (DEFAULT) for system-wide settings or repo-specific sections. The INI key-value pairs directly relate to the available long-options supported by the various prefixed by the subcommand name and their related values. To find all possible configuration options, run: pkgdev {subcommand} --help. See the following examples for config settings:

• Run pkgcheck scan before committing and asks for confirmation (instead of aborting) when creating commits with QA errors:

  [DEFAULT]
  commit.scan = true
  commit.ask = true
  

• Allow pushing commits with QA errors, but only for the ‘gentoo’ repository:

  [gentoo]
  push.ask = true
  

• Add Signed-off-by consenting to the Certificate of Origin to all commits:

  [DEFAULT]
  commit.signoff = true
  

• When committing, stage all files in current working directory (note that this option doesn’t expect value, therefore no value is defined post equal sign):

  [DEFAULT]
  commit.all =
  

• All previous config settings combined:

  [DEFAULT]
  commit.scan = true
  commit.ask = true
  commit.all =
  
  [gentoo]
  push.ask =
  

Reporting Bugs

Please submit an issue via github:

https://github.com/pkgcore/pkgdev/issues