pkgcheck scan - scan targets for QA issues¶

Synopsis¶

pkgcheck scan [--config CONFIG_FILE] [-r REPO] [-R REPORTER]
              [--format FORMAT_STR] [-h] [--debug] [-q] [-v]
              [--color BOOLEAN] [-f FILTER] [-j JOBS] [-t TASKS]
              [--cache CACHE] [--cache-dir CACHE_DIR] [--exit [ITEM]]
              [--net] [-C CHECKSET] [-s SCOPE] [-c CHECK] [-k KEYWORD]
              [-a ARCH] [--commits [tree-ish] | --staged [tree-ish]]
              [--git-remote REMOTE] [--glsa-dir GLSA_DIR]
              [--timeout TIMEOUT] [--user-agent USER_AGENT]
              [--source-arches ARCH] [-p PROFILE] [--stable-only]
              [--stabletime DAYS]
              [--reset-caching-per {version,package,category}]
              [TARGET ...]

Positional Arguments¶

TARGET¶: if not given, scan the repo. If given, limit scans to pkgs matching extended atom syntax. If no packaages match, no scans are ran

Config Options¶

--config CONFIG_FILE¶

Load custom pkgcheck 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’.

Repo Options¶

-r, --repo REPO¶: target repo

Reporter Options¶

-R, --reporter REPORTER¶

Select a reporter to use for output.

Use pkgcheck show --reporters to see available options.

--format FORMAT_STR¶

Custom format string used to format output by FormatReporter.

Supports python format string syntax where result object attribute names surrounded by curly braces are replaced with their values (if they exist).

For example, --format '{category}/{package}/{package}-{version}.ebuild will output ebuild paths in the target repo for results relating to specific ebuild versions. If a result is for the generic package (or a higher scope), no output will be produced for that result.

Furthermore, no output will be produced if a result object is missing any requested attribute expansion in the format string. In other words, --format {foo} will never produce any output because no result has the foo attribute.

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.

Main Options¶

-f, --filter FILTER¶

Support limiting targeted packages for scanning using a chosen filter.

If the ‘latest’ argument is used, only the latest package per slot of both VCS and non-VCS types will be scanned. This can either be specified individually in which case the filter will be applied globally to all checks or it can be applied to specific checksets, checks, or keywords using the syntax ‘latest:ObjName’ which would apply the filter to the keyword, check, or checkset named ObjName (in that order of precedence).

By default, some checks have filtering enabled, e.g. various network-related checks are filtered to avoid redundant or unnecessary server requests. In order to forcibly disable all filtering use the ‘no’ argument.

-j, --jobs JOBS¶: Number of checks to run in parallel, defaults to using all available processors.

-t, --tasks TASKS¶: Number of asynchronous tasks to run concurrently (defaults to 5 * CPU count).

--cache CACHE¶

All cache types are enabled by default, this option explicitly sets which caches will be generated and used during scanning.

To enable only certain cache types, specify them in a comma-separated list, e.g. --cache git,profiles will enable both the git and profiles caches.

To disable specific cache types prefix them with -. Note that when starting the argument list with a disabled value an equals sign must be used, e.g. --cache=-git, otherwise the disabled argument is treated as an option.

In order to disable all cache usage, it’s easiest to use --cache no instead of explicitly listing all disabled cache types.

When disabled, no caches will be saved to disk and results requiring caches (e.g. git-related checks) will be skipped.

--cache-dir CACHE_DIR¶: directory to use for storing cache files

--exit [ITEM]¶

Comma-separated list of checksets, checks, or keywords to enable and disable that trigger an exit status failure. Checkset and check arguments expand into their respective keyword sets.

If no arguments or only disabled arguments are passed, enabled arguments are the set of error level keywords.

To specify disabled keywords prefix them with -. Also, the special arguments of error, warning, style, and info correspond to the related keyword groups.

Check Selection¶

--net¶: enable checks that require network access

-C, --checksets CHECKSET¶

Comma-separated list of checksets to enable and disable for scanning.

The special argument of all corresponds to the list of all checks. Therefore, to forcibly enable all checks use -C all.

All network-related checks (which are disabled by default) can be enabled using -C net. This allows for easily running only network checks without having to explicitly list them.

-s, --scopes SCOPE¶

Comma-separated list of scopes to enable and disable for scanning. Any scopes specified in this fashion will affect the checks that get run. For example, running pkgcheck with only the repo scope enabled will cause only repo-level checks to run.

Available scopes: git, profiles, eclass, repo, cat, pkg, ver

-c, --checks CHECK¶

Comma-separated list of checks to enable and disable for scanning. Any checks specified in this fashion will be the only checks that get run, skipping any disabled checks.

To disable checks prefix them with -. Note that when starting the argument list with a disabled check an equals sign must be used, e.g. -c=-check, otherwise the disabled check argument is treated as an option.

Additive arguments are also supported using the prefix + that adds to the default set of enabled checks. This is useful in order to enable optional checks in addition to the default set.

Use pkgcheck show --checks see all available checks.

-k, --keywords KEYWORD¶

Comma-separated list of keywords to enable and disable for scanning. Any keywords specified in this fashion will be the only keywords that get reported, skipping any disabled keywords.

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

The special arguments of error, warning, style, and info correspond to the related keyword groups. For example, to only scan for errors use -k error.

Use pkgcheck show --keywords to see available options.

Plugin Options¶

--glsa-dir GLSA_DIR¶: custom glsa directory

--source-arches ARCH¶

Comma separated list of arches to compare against for lagging stabilization.

The default arches are all stable arches (unless –arches is specified).

--stable-only¶: If enabled, for each slot, only consider redundant versions with stable keywords. This is useful for cases of cleanup after successful stabilization.

--stabletime DAYS¶: An integer number of days before a package version is flagged by StableRequestCheck. Defaults to 30 days.

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.

Network¶

--timeout TIMEOUT¶: timeout used for network checks

--user-agent USER_AGENT¶: custom user agent spoofing

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.

Query Caching¶

--reset-caching-per {version,package,category}¶: control how often the cache is cleared (version, package or category)