EQUERY

Section: (1)
Updated: 0.4.2-r1
Page Index

NAME

equery - Gentoo Package Query Tool

SYNOPSIS

equery [global-options] module [local-options]

DESCRIPTION

Equery is a collection of modules for querying the state of Gentoo packages, files and USE flags.

GLOBAL OPTIONS

-h, --help: Output a help message.
-q, --quiet: Be less verbose where possible. In some modules, this option can increase the output speed.
-C, --no-color: Do not colorize output.
-N, --no-pipe: Turn off automatic pipe detection. Use this option if you do not want equery to detect if the output is being directed to the screen or to another program and adjust color and verbosity accordingly.
-V, --version: Display Gentoolkit's version. Please include this in all bug reports. (see BUGS below)

MODULES

Equery uses a system of modules. Each module has both a long and short name. The list below uses the notation "module (m)", where m is the short name and module is the long name.

You can view the help message for a specific module by using -h, --help as either a global option (after equery and before the module name) or as a local option (after the module name).

belongs(b)[OPTIONS]FILE

List the package that owns FILE.

Note: Normally, only one package will own FILE. If multiple packages own the same file it should be reported. (see BUGS below)

R LOCAL OPTIONS :

-f, --full-regex: The supplied query is a regular expression.
-e, --early-out: Stop when the first match is found. This is generally a safe optimization when searching for the owner of a single file.
-n, --name-only: Do not print the version.

R EXAMPLES :

: equery belongs --early-out /usr/bin/euse
Find out what package installed a certain command.
: emerge -p $(equery -q belongs -nf '^/usr/bin/g?vim.*')
Tell emerge to reinstall or update any package that installed a file matching a regular expression.

changes(c)[OPTIONS]PKG

Display the Gentoo ChangeLog entry for the latest installable version of PKG.

R LOCAL OPTIONS :

-l, --latest: Display only the latest ChangeLog entry. It's not uncommon for changes to be prepended to the ChangeLog without a version header if the changes did not require a version bump. Use this option to display such entries.
-f, --full: Display the full ChangeLog.
Hint: Try piping (|) the output to a pager, like 'less'.
--limit=NUM: Limit the NUM of entries displayed. Use this option in conjunction with --full. --limit=3 would display the three latest entries.
--from=VER: Set which VER to display from. Using this option by itself is equivalent to passing changes a ranged package atom, e.g., '>=foo/bar-1.5'. It can be used in conjunction with --to to request a more complex range of entries.
--to=VER: Set which VER to display to. (See --from)

R EXAMPLES :

: equery changes portage
Display the Gentoo ChangeLog entry for the latest installable version of Portage.
: equery changes '=sys-apps/portage-2.1.6*'
Use Portage's atom syntax. (See man 5 ebuild)
: equery changes portage --from=2.2_rc1 --to=2.2
Display any ChangeLog entry within a range of versions.

check(k)[OPTIONS]PKG

Check timestamps and MD5 sums for files owned by PKG, where PKG is an installed package.

R LOCAL OPTIONS :

-f, --full-regex: The supplied query is a regular expression.
-o, --only-failures: Only display packages which don't pass all checks.

R EXAMPLES :

: equery check --only-failures '*'
Verify timestamps and MD5 sums for all installed packages and show only packages which fail checks.
: equery check 'dev-python/*' dev-lang/python
Verify every installed package in the dev-python category, and Python itself.

depends(d)[OPTIONS]PKG

List all packages that depend on PKG.

R LOCAL OPTIONS :

-a, --all-packages: Include dependencies that are not installed. This can take a while.
-D, --indirect: Search for both direct and indirect dependencies.
--depth=NUM: Limit the indirect dependency tree to a depth of NUM. --depth=0 is equivalent to not using --indirect.

R EXAMPLES :

: equery depends --indirect xulrunner
Figure out why a package got installed on your system.

depgraph(g)[OPTIONS]PKG

Display a direct dependency graph for every matching version of PKG. A dependency graph is an indented tree showing the relationship between packages and their dependencies.

R LOCAL OPTIONS :

-A, --no-atom: Do not show the dependency atom that match the package.
-U, --no-useflags: Do not show USE flags.
-l, --linear: Do not format the graph by indenting dependencies. This option will print the recursion depth in square brackets before the package name for easier viewing in narrow terminals.
--depth=NUM: Limit the dependency graph to a depth of NUM. --depth=0 means no maximum depth. Default depth is set to 1.

R EXAMPLES :

: equery depgraph --depth=0 portage
View a full tree of all direct and indirect compile-time, run-time, and post-merge dependencies for a package.

files(f)[OPTIONS]PKG

List files and directories installed by PKG.

R LOCAL OPTIONS :

-m, --md5sum: Include the file's MD5 sum in the output.
-s, --timestamp: Include the file's timestamp in the output.
-t, --type: Include the file type in the output.
--tree: Display files in a tree format. This option turns off all other local options.
-f, --filter=RULES: Filter output by file type.
: RULES
A comma-separated list (no spaces); choose from:
dir, obj, sym, dev, path, conf, cmd, doc, man, info

R EXAMPLES :

: equery files --tree vlc
View a file tree of all files installed by a package.
: equery files --filter=cmd vlc
Find out where a package installed its executables.

has(a)[OPTIONS]KEY

VALUE List all installed packages that have a given PKG match.

Note: KEY is case sensitive. Also has does not currently have the ability to inteligently compare values dependending on the type of information being looked up. It performs a simple string match. It can only list which packages have the matching VALUE as given on the command line. It is a general purpose lookup for most information available via portage's dbapi.aux_get() function. Warning the quality of the results printed is dependant on the quality of the search (given the limited comparison method) and the recorded data available in the vardb. (See EXAMPLES)

R LOCAL OPTIONS :

-I, --exclude-installed: Exclude installed packages from being output.
-o, --overlay-tree: Include package from overlays in the search path.
-p, --portage-tree: Include all packages from the Portage tree in the search path. Use this option to search through all standard Gentoo packages, including those that are not installed.
-F, --format=TMPL: Customize the output format of the matched packages using the template string TMPL. See the --format option for list below for a description of the TMPL argument.

R OUTPUT :

(See OUTPUT for list below)

R EXAMPLES :

: equery has SLOT 2.4
View all installed Gentoo packages that have a recorded SLOT = "2.4".
: equery has repository sunrise
View all installed Gentoo packages that were recorded to be installed from ebuilds from the "sunrise" overlay.
: equery has EAPI 2
View all installed Gentoo packages that were installed with ebuilds with a recorded EAPI of "2".

hasuse(h)[OPTIONS]USE

List all installed packages that have a given PKG flag.

Note: hasuse does not currently have the ability to display if packages are built with the given USE flag or not. It can only list which packages have the flag as an option. (See EXAMPLES)

R LOCAL OPTIONS :

-I, --exclude-installed: Exclude installed packages from being output.
-o, --overlay-tree: Include package from overlays in the search path.
-p, --portage-tree: Include all packages from the Portage tree in the search path. Use this option to search through all standard Gentoo packages, including those that are not installed.
-F, --format=TMPL: Customize the output format of the matched packages using the template string TMPL. See the --format option for list below for a description of the TMPL argument.

R OUTPUT :

(See OUTPUT for list below)

R EXAMPLES :

: equery hasuse -pI perl
View all Gentoo packages that have the "perl" USE flag, exluding installed packages.
: USE="perl"; for PKG in $(equery -q hasuse $USE); do echo $PKG: $(equery -q uses $PKG |grep $USE); done
This Bash one-liner uses hasuse to find a list of packages that have a certain USE flag, and uses to check whether the flag is enabled or disabled. Modify USE="perl" to change the query.

list(l)[OPTIONS]PKG

List installed versions of PKG or all packages matching the query pattern.

R LOCAL OPTIONS :

-d, --duplicates

List only packages with more than one version installed.

-f, --full-regex

The supplied query is a regular expression.

-m, --mask-reason

Print the reason why a package was masked.

-I, --exclude-installed

Exclude installed packages from being output.

-o, --overlay-tree

Include package from overlays in the search path.

-p, --portage-tree

Include all packages from the Portage tree in the search path. Use this option to search through all standard Gentoo packages, including those that are not installed.

-F, --format=TMPL

Customize the output format of the matched packages using the template string TMPL. TMPL can contain the following placeholders:

$cp - Contains the category and the package name only (e.g 'app-portage/gentoolkit').
$cpv - Contains the category, the package name and the full version (e.g. 'app-portage/gentoolkit-0.3.0_rc10-r1').
$category - Contains just the category (e.g. 'app-portage').
$name - Contains just the package name (e.g. 'gentoolkit').
$version - Contains the package version (without the revision) (e.g. '0.3.0_rc10').
$revision - Contains the package revision (e.g. 'r1').
$fullversion - Contains the package version including its revision (e.g. '0.3.0_rc10-r1').
$slot - Contains the package's slot.
$repo - Contains the name of the package's repository (e.g. 'gentoo').
$mask - The Mask-status field (~M-??), see OUTPUT below for an explanation.
$mask2 - Contains a verbose description of the packages masking status.
$location - The Location field (IPO-), see OUTPUT below for an explanation.

Apart from the above placeholders the template string can contain arbitrary text as desired. Similar to bash variables, curly braces can be used to disambiguate the variable names from the enclosing text.

R OUTPUT :

$ equery list binutils
* Searching for binutils ...
[I--] [??] sys-devel/binutils-2.18-r1:i686-pc-linux-gnu-2.18
[IP-] [ ~] sys-devel/binutils-2.19.1-r1:i686-pc-linux-gnu-2.19.1

: Location field ([IPO-]):
The first field shows the location and install status of the package. It consists of three letters in square brackets. I indicates the package is currently installed. P indicates the package is available in the Portage tree. O indicates the package is available in at least one overlay. - is a place holder and has no meaning. [I-O] would mean that the package is installed and available from an overlay, but not available from the Portage tree.
: Mask-status field ([ ~M-??]):
The second field shows the mask status of the package. Empty brackets indicate that the package is unmasked. A ~ means the package is masked by keyword, e.g., you are running a stable system and the package is marked testing). M means hard masked, e.g., the package maintainer has determined the package is unfit for widespread usage. - means arch masked, e.g., you are running an amd64 system, but this package only works on x86. Lastly, ?? only occurs when the location field is [I--]. Together, they indicate that the package was installed from the Portage tree or an overlay, but has since been removed from that tree; therefore equery can not determine a mask status for it.
: Package name:
The third field is the full package name and version.
: Slot:
The fourth field, after the colon, is the package's slot. 0 is the default slot. To find all packages with multiple slots installed, use --duplicates.

Note: Because it takes extra processing time to determine the location, mask status and slot, you can speed up output by passing the --quiet global option to equery when you don't care about the extra information.

Note: Additionally, when using --quiet, if no matches are found, instead of printing an error, the equery list module will return with an exit value of 3.

R EXAMPLES :

: equery list '*'
List all installed packages. This is equivalent to 'equery list' in Gentoolkit versions prior to 0.3.0.
: equery list -op mozilla-firefox
List all available versions of the package exactly matching 'mozilla-firefox'. This is equivalent to 'equery list --exact-name -o -p mozilla-firefox' in Gentoolkit versions prior to 0.3.0.
: equery list '*zilla*'
List all packages that contain (fuzzy match) 'zilla'. This is equivalent to 'equery list zilla' in Gentoolkit versions prior to 0.3.0.
: equery list 'www-client/*'
List all packages in the category www-client. This is equivalent to 'equery list --category=www-client' in Gentoolkit versions prior to 0.3.0.
: equery list --duplicates '*'
List all packages with more than one version installed. This is equivalent to 'equery list --duplicates' in Gentoolkit versions prior to 0.3.0.
: equery list -F '$cp:$slot' '*'
Get a list of slotted atoms for all installed packages.
: equery list -po -F '[$location] [$mask] $cpv:$slot [$repo]' '*'
Show all packages in the default (verbose) output format but also include their repository name.

meta(m)[OPTIONS]PKG

Display metadata about PKG.

meta reads a file called metadata.xml which must be included with all Portage tree packages. meta does not read ebuilds, so it can only return version independent metadata. Since until now there had not been an easy way for users to view metadata.xml, and because package maintainers are only required to fill out a very small portion of the file, there are still many packages without detailed metadata available. For more information about metadata.xml, see:
https://devmanual.gentoo.org/ebuild-writing/misc-files/metadata/index.html

R LOCAL OPTIONS :

-d, --description: Show an extended package description.
-H, --herd: Show the herd(s) for the package. When not piping and not passing --quiet as a global option, also show the herd's email address. (shown by default)
-k, --keywords: Show keywords for all matching versions. keywords does not list all keywords for all versions. Instead, it filters the list to make it easier to spot versions that need bumping or are okay to remove from the tree. It filters by slot. For example:
Keywords: 1.35.0-r3:0:
Keywords: 1.35.0-r5:0: amd64 hppa ppc x86 ~alpha ~arm ~ia64 ~mips ~ppc64 ~s390 ~sh ~sparc
In this output from equery meta boost, -r5 is the highest available version in slot 0, so all keywords are listed. The actual keywords for -r3 are "~amd64 ~hppa ~ppc ~x86", but since a higher version in the same slot has the same or more stable keywording, they are filtered out. Arch mask keywords (-*) are always shown.
-m, --maintainer: Show the package maintainer(s) email address. If the metadata is available, also show the maitainer's name and/or job description. (shown by default)
-u, --useflags: Show per-package USE flag descriptions. Per-package USE flag descriptions are sometimes added to metadata.xml if the affect of the USE flag is unusual, or if the USE flag is rare enough to be undefined in the global definition file. equery uses now displays these same local descriptions as well, so this option is left in meta for completeness only.
-U, --upstream: Show information about the package's upstream project, including the author's email, upstream bug tracker or upstream documentation. At the time of writing, most maintainers do not provide this information. (shown by default)
-x, --xml: Dump the plain XML file to the screen.

R EXAMPLES :

: equery meta gnucash
Show general information about maintainership, including herd, maintainer and upstream.
: equery meta --description app-misc/screen
See if the package maintainer has provided an extended description.
: equery -N meta -H gnome |grep -o --color=never '[^( ]*@gentoo.org'
Extract the herd's email address to let them know they're doing a great job. Remember, bug reports should go to bugs.gentoo.org. The above example will extract one or more emails if available, or return nothing if the herd is no-herd.

size(s)[OPTIONS]PKG

Print total size of files contained in a given PKG.

R LOCAL OPTIONS :

-b, --bytes: Report package size in bytes.
-f, --full-regex: The query is a regular expression.

R EXAMPLES :

: equery -q size 'www-client/*'
Get a one-line summary of the number of files and total size (in bytes) of those files for each installed package in a category.

uses(u)[OPTIONS]PKG

Display USE flag statuses and descriptions for a given PKG.

R LOCAL OPTIONS :

-a, --all: Display all package versions. Without this option, equery will choose the best available version.
-i, --ignore-linguas: Do not show the linguas USE flags

R EXAMPLES :

: equery uses app-misc/beagle
See which USE flags are enabled for a specific package.
: USE="perl"; for PKG in $(equery -q hasuse $USE); do echo $PKG: $(equery -q uses $PKG |grep $USE); done
This Bash one-liner uses hasuse to find a list of packages that have a certain USE flag, and uses to check whether the flag is enabled or disabled. Modify USE="perl" to change the query.

which(w)[OPTIONS]PKG

Display the path to the ebuild that would be used by Portage with the current configuration.

R LOCAL OPTIONS :

-m, --include-masked: Return the path to the hightest version ebuild available.
-e, --ebuild: Print the contents of the ebuild

R EXAMPLES :

: equery which -e xorg-server
View the most recent installable ebuild.

BUGS

Submit bug reports to http://bugs.gentoo.org.

AUTHORS

Karl Trygve Kalleberg <karltk@gentoo.org>, 2003
Katerina Barone-Adesi <katerinab@gmail.com>, 2004
Douglas Anderson <douglasjanderson@gmail.com>, 2009