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 fromhttps://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 ARCH, --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’ usepkgcheck 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 PROFILE, --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
, anddeprecated
correspond to the lists of stable, development, experimental, and deprecated profiles, respectively. Therefore, to only scan all stable profiles pass thestable
argument to –profiles. Additionally the keywordall
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 BUG
add Bug tag for a given Gentoo or upstream bug
-c CLOSES[:RESOLUTION], --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 NAME:VALUE, --tag NAME:VALUE
add commit tag
-n, --dry-run
Perform all actions without creating a commit.
-s [BOOLEAN], --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 [BOOLEAN], --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 thegit commit
command. This option enables to override the default behavior or the behavior defined bysign-commits = true
inmetadata/layout.conf
file.-d DISTDIR, --distdir DISTDIR
Use a specified target directory for downloads instead of the configured DISTDIR.
-m MSG, --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 FILE, --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 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 [DAYS], --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 BUGS, --bug BUGS, --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
andgentoo-dev-announce
). The user should manually set the Reply-to field for the message to be accepted bygentoo-dev-announce
.For spawning the preferred email composer, the
xdg-email
tool fromx11-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 [BOOLEAN], --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 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 ARCH
select arches to display
Target Options¶
-r REPO, --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 NAME, --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 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 NUMBER, --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 TARGET [TARGET ...], --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: