PKGDEV(1)

NAME
pkgdev - Wrapper for running commandline scripts.

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

link https://docs.python.org/3/using/cmdline.html#cmdoption-version'--version link'
    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 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' 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 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, 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 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 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 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 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 [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:

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

AUTHOR
Tim Harder <radhermit@gmail.com>, Arthur Zamarin <arthurzam@gentoo.org>

COPYRIGHT
2021-2022, pkgdev contributors