From Gentoo Wiki
Jump to:navigation Jump to:search

pkgcheck is a pkgcore-based QA utility for ebuild repos.



root #emerge --ask dev-util/pkgcheck


Upstream's documentation describes the config file format and locations.

For example, a configuration file for the current user:

FILE ~/.config/pkgcheck/pkgcheck.conf
# Enable PerlCheck to the default list of checks (it's not enabled by default upstream)
checks = +PerlCheck
# Disable two noisy keywords (checks)
keywords = -UnstableOnly,-PotentialStable

# Enable network checks when scanning in the 'gentoo' repository with a timeout of 15 seocnds
# Examples: check for HOMEPAGE which 404s, or for a HTTP -> HTTPS redirect
net =
timeout = 15


The upstream repository covers usage briefly.

pkgcheck has the following subcommands:

  • pkgcheck scan - this is the most common command needed: scans the current directory (can take arguments instead) for QA issues
    • pkgcheck scan --net - enables checks that require network access (can fail if scanning lots of packages).
    • pkgcheck scan --commits - same as pkgcheck scan but restricted to changes in local unpushed commits. Enables additional checks which require more context (like commit message format/length, pushing straight-to-stable, etc).
  • pkgcheck show - this lists all possible results (try pkgcheck show --checks etc to find things to disable or change severity of locally if desired)


The most common pattern is to enter a repository, navigate to a package (using sys-kernel/gentoo-sources as an example), and run pkgcheck scan, like so:

user $cd ~/git/gentoo/sys-kernel/gentoo-sources
user $pkgcheck scan
  DroppedKeywords: version 5.18.11: m68k

To scan packages per maintainer, one could try:

user $cd ~/git/gentoo
user $git grep -l "" */*/metadata.xml | cut -d/ -f1-2 | pkgcheck scan -
  PythonCompatUpdate: version 1.0.9-r3: PYTHON_COMPAT update available: python3_11
  StableRequest: version 1.0.9-r4: slot(0) no change in 45 days for unstable keywords: [ ~amd64, ~arm, ~arm64, ~hppa, ~ppc, ~ppc64, ~sparc, ~x86 ]

  PythonCompatUpdate: version 0.2.0: PYTHON_COMPAT update available: python3_11

Or to specifically only check for packages which may be due a stabilization request:

user $cd ~/git/gentoo
user $git grep -l "" */*/metadata.xml | cut -d/ -f1-2 | pkgcheck scan -k StableRequest -
  StableRequest: version 1.0.9-r4: slot(0) no change in 45 days for unstable keywords: [ ~amd64, ~arm, ~arm64, ~hppa, ~ppc, ~ppc64, ~sparc, ~x86 ]


error: repos.conf: default repo 'gentoo' is undefined or invalid

See bug #730502. This is caused by having a /etc/portage/repos.conf defined without mentioning the gentoo repository.

If /etc/portage/repos.conf is a directory:

root #cp /usr/share/portage/config/repos.conf /etc/portage/repos.conf/gentoo.conf

Alternatively, if it's a file:

root #cat /usr/share/portage/config/repos.conf >> /etc/portage/repos.conf

failed retrieving origin/HEAD commit hash for git repo

See the upstream documentation on git support.

Run git remote set-head origin master.

See also

  • Standard git workflow — describing a modern git workflow for contributing to Gentoo, with pkgcheck and pkgdev
  • Gentoo git workflow — outlines some rules and best-practices regarding the typical workflow for ebuild developers using git.
  • pkgdev — a collection of tools for Gentoo development.
  • Repoman — a Python program used to enforce a minimal level of quality assurance in ebuilds and related metadata added to ebuild repositories.

External resources