pquery¶

Synopsis¶

pquery [-h] [–version] [–debug] [-q] [-v] [–color BOOLEAN] [–config CONFIG_PATH] [–domain DOMAIN] [–raw] [–unfiltered] [–virtuals {only,disable}] [-r REPO | -E | -B | -I | -A] [–all] [–has-use has_use] [–license license] [–live] [–non-live] [–revdep REVDEP] [–revdep-pkgs REVDEP_PKGS] [–restrict-revdep restrict_revdep] [–restrict-revdep-pkgs restrict_revdep_pkgs] [-S description] [–eapi eapi] [–owns owns] [–owns-re owns_re] [–maintainer maintainer] [–maintainer-name maintainer_name] [–maintainer-email maintainer_email] [–environment-re environment_re] [–pkgset pkgset] [-u] [-1] [-a] [–cpv] [-R] [–slot] [-n | –min | –max] [–blame] [–size] [–contents] [–highlight-dep HIGHLIGHT_DEP] [–print-revdep PRINT_REVDEP] [-F format] [–attr attribute] [–force-attr attribute] [–one-attr attribute | –force-one-attr attribute] [TARGET …]

Description¶

pquery is used to extract various kinds of information about either installed or uninstalled packages. From an overall usage standpoint it is similar to equery, but it can do things equery cannot do and is a bit more flexible.

What pquery does is select packages from one or more repos that match a boolean combination of restrictions, then print selected information about those packages. It is important to understand that the information printing and repo selection options are almost completely separate from the restriction options. The only exception to that is that restrictions on contents automatically select the vdb (installed packages) repo, since running them on source repos makes no sense.

Base Options¶

-h, --help

Show this help message and exit. To get more information see the related man page.

--version

Show this program’s version information and exit.

When running from within a git repo or a version installed from git the latest commit hash and date will be shown.

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

Config Options¶

--config CONFIG_PATH

The path to a custom pkgcore config file or portage config directory can be given to override loading the default system config.

Alternatively, an argument of ‘false’ or ‘no’ will skip loading the system config entirely if one exists.

--domain DOMAIN

custom pkgcore domain to use for this operation

Repository Matching Options¶

options controlling which repos to inspect

--raw

Disable configuration filtering that forces raw dependencies to be used, rather than the dependencies rendered via your USE configuration. Primarily useful for people who need to look under the hood- ebuild devs, PM tool authors, etc. Note this option ignores –domain if is specified.

--unfiltered

Disable all package filtering mechanisms such as ACCEPT_KEYWORDS, ACCEPT_LICENSE, and package.mask.

--virtuals {only,disable}

This option requires one of two arguments, either ‘only’ or ‘disable’, which causes only virtuals to be matched or disables virtuals matching entirely, respectively.

By default, virtuals are included during matching.

-r REPO, --repo REPO

Select the repo to search in for matches. This includes all the configured repos in repos.conf as well as the special keywords binpkg, provided, and vdb that search the configured binary package repo, package.provided, and installed packages, respectively.

By default, all configured repos except the vdb will be searched when this option isn’t specified.

-E, --ebuild-repos

Search within all ebuild repos, all non-ebuild repos are skipped.

-B, --binary-repos

Search within all binary repos, all non-binary repos are skipped.

-I, --installed

Search within installed packages (alias for ‘–repo vdb’).

-A, --all-repos

Search all available repos including the vdb.

Package Matching Options¶

Each option specifies a restriction packages must match. Specifying the same option twice means “or” unless stated otherwise. Specifying multiple types of restrictions means “and” unless stated otherwise.

TARGET: extended atom matching of pkgs
--all: Match all packages which is equivalent to “pquery *”. Note that if no query options are specified, this option is enabled.
--has-use has_use: exact string match on a USE flag
--license license: exact match on a license
--live: match packages which are have PROPERTIES=”live”
--non-live: match packages which are don’t have PROPERTIES=”live”
--revdep REVDEP: An alias for ‘–restrict-revdep atom –print-revdep atom’, but note that –print-revdep is slow so use –restrict-revdep if you just need a list.
--revdep-pkgs REVDEP_PKGS: An alias for ‘–restrict-revdep-pkgs atom –print-revdep atom’, but note that –print-revdep is slow so use –restrict-revdep if you just need a list.
--restrict-revdep restrict_revdep: dependency on an atom
--restrict-revdep-pkgs restrict_revdep_pkgs: dependency on pkgs that match a specific atom
-S description, --description description: regexp search on description and longdescription
--eapi eapi: match packages using a given EAPI
--owns owns: exact match on an owned file/dir
--owns-re owns_re: like “owns” but using a regexp for matching
--maintainer maintainer: regex to search for maintainers
--maintainer-name maintainer_name: comma-separated list of maintainer name regexes to search for
--maintainer-email maintainer_email: comma-separated list of maintainer email regexes to search for
--environment-re environment_re: regexp search of lines in environment.bz2
--pkgset pkgset: find packages that match the given package set (world for example)
-u, --upgrade: match installed packages without best slotted version

Output Options¶

-1, --first

stop when first match is found

-a, --atom

Output valid package atoms, e.g. =cat/pkg-3 instead of cat/pkg-3.

Note that this option implies –cpv and has no effect if used with –no-version.

--cpv

Display output in the format of ‘category/package-version’ which is done by default, this option forces the output format if another output option (such as –contents) alters it.

-R

print the repo of the package

--slot

print the slot of the package

-n, --no-version

collapse multiple matching versions together

--min

show only the lowest version for each package

--max

show only the highest version for each package

--blame

shorthand for –attr maintainers

--size

display size of all files owned by the package

--contents

list files owned by the package

--highlight-dep HIGHLIGHT_DEP

highlight dependencies matching this atom

--print-revdep PRINT_REVDEP

print what condition(s) trigger a dep

-F format, --format format

Use the given format string to print package attributes. The format uses standard Python format string syntax (see Format Specification Mini-Language for details), with the all attributes of --attr.

--attr attribute

Print the given attribute’s value. This option can be specified multiple times.

Valid attributes: all, alldepends, allmetadata, bdepend, category, cbuild, chost, ctarget, defined_phases, depend, description, distfiles, eapi, environment, fetchables, files, fullver, homepage, idepend, inherited, iuse, keywords, license, longdescription, maintainers, package, path, pdepend, properties, raw_alldepends, raw_bdepend, raw_depend, raw_idepend, raw_pdepend, raw_rdepend, rdepend, repo, required_use, restrict, revision, slot, source_repository, subslot, uris, use, version

--force-attr attribute

Like –attr but accepts any string as attribute name instead: of only explicitly supported names.

--one-attr attribute

Print the given attribute’s value, while suppressing all other output. All attributes of --attr are accepted.

--force-one-attr attribute

like –one-attr but accepts any string as attribute name instead of only explicitly supported names

Usage¶

Another switch that could do with some extra explanation is --raw. Specifying --raw makes your configuration not affect the results. Example:

$ pquery --attr alldepends sys-apps/dbus --max -v
* sys-apps/dbus-0.62-r1
    description: A message bus system, a simple way for applications to talk
                 to each other
    homepage: http://dbus.freedesktop.org/
    depends: >=dev-libs/glib-2.6 || ( ( x11-libs/libXt x11-libs/libX11 )
                 virtual/x11 ) >=x11-libs/gtk+-2.6 >=dev-lang/python-2.4
                 >=dev-python/pyrex-0.9.3-r2 >=dev-libs/expat-1.95.8
                 dev-util/pkgconfig sys-devel/automake
                 >=sys-devel/autoconf-2.59 sys-devel/libtool
    rdepends: >=dev-libs/glib-2.6 || ( ( x11-libs/libXt x11-libs/libX11 )
                 virtual/x11 ) >=x11-libs/gtk+-2.6 >=dev-lang/python-2.4
                 >=dev-python/pyrex-0.9.3-r2 >=dev-libs/expat-1.95.8
    post_rdepends:

This is the highest unmasked package on the system. Also notice there are no references to USE flags or qt in the dependencies. That is because qt is not in USE for this configuration, so those dependencies do not apply.:

$ pquery --attr alldepends sys-apps/dbus --max -v --raw
* sys-apps/dbus-0.91
    description: Meta package for D-Bus
    homepage: http://dbus.freedesktop.org/
    depends:
    rdepends: >=sys-apps/dbus-core-0.91 python? (
                 >=dev-python/dbus-python-0.71 ) qt3? (
                 >=dev-libs/dbus-qt3-old-0.70 ) gtk? (
                 >=dev-libs/dbus-glib-0.71 ) !<sys-apps/dbus-0.91
    post_rdepends:

This version is in package.mask, and we can see the use-conditional flags now.

The --verbose or -v flag tries to print human-readable output (although some things like the formatting of depend strings need some improvement). Without -v the output is usually a single line per package in a hopefully machine-parseable format (usable in pipelines). There are some extras like --atom meant for shell pipeline use. If you have some useful shell pipeline in mind that pquery’s output could be better formatted for please open an issue.

Adding short options is planned but there are some features to add first (want most of the features in place to avoid name clashes).

Examples¶

Other tool	pquery	Comments
`equery belongs /bin/ls`	`pquery --owns /bin/ls`
`equery check`	not implemented (yet?)
`equery depends python`	`pquery -I --revdep dev-lang/python`	omitting `-I` makes it equivalent to `equery depends -a`
`equery depgraph`	not implemented (yet?)
`equery files python`	`pquery --contents python`	`--contents` is an output option, can be combined with any restriction
`equery hasuse python`	`pquery -I --has-use python`
`equery list python`	`pquery -I 'python'`	this is in ExtendedAtomSyntax
`equery size python`	`pquery --size python`
`equery uses python`	`pquery --attr use python`	less information, but is an output option so mixes with any restriction
`emerge -s python`	`pquery -vn 'python'`
`emerge -S python`	`pquery -vnS python`	searches through longdescription (from metadata.xml) too
no equivalent	`pquery --license GPL-2 -I`	list all installed GPL-2 packages
no equivalent	`pquery --maintainer radhermit`	list all packages that are maintained by radhermit

It can also do some things equery/emerge do not let you do, like restricting based on maintainer or herd and printing various other package attributes. See --help for those. If you miss a query open an issue.