PKGDEV(1)

NAME
pkgdev - collection of tools for Gentoo development

SYNOPSIS

pkgdev [-h] [--version] [--debug] [-q] [-v] [--color BOOLEAN] {commit,manifest,mask,push,showkw} ...

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 commit - create git commit

  Synopsis

pkgdev commit [--config CONFIG_FILE] [--domain DOMAIN] [-h] [--debug] [-q] [-v] [--color BOOLEAN] [-b BUG] [-c CLOSES] [-T NAME:VALUE] [-n] [-s [BOOLEAN]] [-A [BOOLEAN]] [--mangle [BOOLEAN]] [--signoff [BOOLEAN]] [-d DISTDIR] [-m MSG | -M FILE] [-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 sitations where stdout is not a tty.

  Commit Options

-b BUG, --bug BUG
    add Bug tag for a given Gentoo or upstream bug

-c CLOSES, --closes CLOSES
    add Closes tag for a given Gentoo bug or upstream PR URL

-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.

-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.

-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 sitations 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] [-r [DAYS]] [-b BUGS] [--email] [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.

  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 sitations 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
    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.

  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]

  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 sitations 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

  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 sitations 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)

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

COPYRIGHT
2021-2022, pkgdev contributors