pmerge¶

Synopsis¶

pmerge [-h] [–version] [–debug] [-q] [-v] [–color BOOLEAN] [–config CONFIG_PATH] [–domain DOMAIN] [-u | -d | -C | –clean | –list-sets] [-p] [-a] [-f] [-1] [-D] [-N] [-i] [–with-bdeps] [-O] [-o] [-n] [-b] [-k] [-K] [-S] [-e] [-x TARGET[,TARGET,…]] [–ignore-failures] [–force] [–preload-vdb-state] [–quiet-repo-display] [-F FORMATTER] [–pdb-intercept TARGET[,TARGET,…]] [–disable-resolver-target-sorting] [TARGET …]

Description¶

pmerge is the main command-line utility for merging and unmerging packages on a system. It provides an interface to install, update, and uninstall ebuilds from source or binary packages.

Portage Compatibility¶

With regards to portage compatibility, pmerge provides much of the same functionality that emerge(1) does. In general, it should be possible to use both pmerge and emerge on the same system in a sane fashion. For example, pmerge can be used to install packages and then emerge should be able to upgrade or uninstall them, or vice versa. Also, binary packages created using pmerge should be able to be installed properly using emerge. Any major compatibility issue that arises when trying to use both package managers is probably a bug and should be reported.

In terms of option naming, pmerge tries to remain somewhat compatible to portage so running pmerge -1av should work the same as emerge -1av when using portage. However, pmerge doesn’t implement nearly the same amount of options that portage provides so many of the more obscure ones are missing. In addition, pmerge defaults to a portage compatible output format that closely matches the default colors and output structure that portage uses.

Positional Arguments¶

TARGET

Various target arguments are supported including the following:

atom: An extended atom syntax is supported, see the related section in pkgcore(5).
package set: Used to define lists of packages, the syntax used for these is @pkgset. For example, the @system and @world package sets are supported.
extended globbing: Globbing package names or atoms allows for use cases such as 'far*' (merge every package starting with ‘far’), 'dev-python/*::gentoo' (merge every package in the dev-python category from the gentoo repo), or even ‘*’ (merge everything).

Also, the target ‘-’ allows targets to be read from standard input.

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

Operations¶

-u, --upgrade

Try to upgrade specified targets to the latest visible version. Note that altered package visibility due to keywording or masking can often hide the latest versions of packages, especially for stable configurations.

-d, --downgrade

Try to downgrade specified targets to a lower visible version compared to what’s currently installed.

Useful for reverting to the previously installed package version; however, note that the -O/–nodeps option is generally used with this otherwise lots of downgrades will be pulled into the resolved deptree.

-C, --unmerge

Target packages for unmerging from the system.

WARNING: This does not ask for user confirmation for any targets so it’s possible to quickly break a system.

--clean

Remove installed packages that aren’t referenced by any target packages or sets. This defaults to using the world and system sets if no targets are specified.

Use with caution, this option used incorrectly can render your system unusable. Note that this implies –deep.

--list-sets

display the list of available package sets

Resolver Options¶

-p, --pretend

Resolve package dependencies and display the results without performing any merges.

-a, --ask

Perform the dependency resolution, but ask for user confirmation before beginning the fetch/build/merge process. The choice defaults to yes so pressing the “Enter” key will trigger acceptance.

-f, --fetchonly

Only perform fetching of all targets from SRC_URI based on the current USE configuration.

-1, --oneshot

Build and merge packages normally, but do not add any targets to the world file. Note that this is forcibly enabled if a package set is specified.

-D, --deep

Force dependency resolution across the entire dependency tree for all specified targets.

-N, --newuse

Include installed packages with USE flag changes in the list of viable targets for rebuilding.

USE flag changes include flags being added, removed, enabled, or disabled with regards to a package. USE flag changes can occur via ebuild alterations, profile updates, or local configuration modifications.

Note that this option implies -1/–oneshot.

-i, --ignore-cycles

Ignore dependency cycles if they’re found to be unbreakable; for example: a depends on b, and b depends on a, with neither built.

--with-bdeps

Pull in build time dependencies for built packages during dependency resolution, by default they’re ignored.

-O, --nodeps

Build and merge packages without resolving any dependencies.

-o, --onlydeps

Build and merge only the dependencies for the packages specified.

-n, --noreplace

Skip packages that are already installed. By default when running without this option, any specified target packages will be remerged regardless of if they are already installed.

-b, --buildpkg

Force binary packages to be built for all merged packages.

-k, --usepkg

Binary packages are preferred over ebuilds when performing dependency resolution.

-K, --usepkgonly

Only binary packages are considered when performing dependency resolution.

-S, --source-only

Only ebuilds are considered when performing dependency resolution.

-e, --empty

Force all targets and their dependencies to be rebuilt.

-x TARGET[,TARGET,...], --exclude TARGET[,TARGET,...]

Comma-separated list of targets to pretend are installed.

This supports extended package globbing, e.g. 'dev-python/*' equates to faking the entire dev-python category is installed.

--ignore-failures

Skip failures during the following phases: sanity checks (pkg_pretend), fetching, dep resolution, and (un)merging.

--force

Force (un)merging on the livefs (vdb), regardless of if it’s frozen.

--preload-vdb-state

Preload the installed package database which causes the resolver to work with a complete graph, thus disallowing actions that conflict with installed packages. If disabled, it’s possible for the requested action to conflict with already installed dependencies that aren’t involved in the graph of the requested operation.

Output Options¶

--quiet-repo-display

In the package merge list display, suppress ::repo output and instead use index numbers to indicate which repos packages come from.

-F FORMATTER, --formatter FORMATTER

Select an output formatter to use for text formatting of –pretend or –ask output, currently available formatters include the following: basic, pkgcore, portage, and portage-verbose.

The basic formatter is the nearest to simple text output and is intended for scripting while the portage/portage-verbose formatter closely emulates portage output and is used by default.

Resolver Debugging Options¶

--pdb-intercept TARGET[,TARGET,...]

Comma-seperated list of targets to trigger a pdb.set_trace() within resolver code for investigation.

This is primarily used for debugging resolver implementation, being able to walk through what it has decided and why.

--disable-resolver-target-sorting

Resolution of package dependencies can grossly vary depending on which nodes you start from.

Pmerge by default sorts the targets it’s asked to resolve; this in turn stabilizes the resolvers output. This option allows disabling that sort.

This should be only used if you’re debugging the resolver and wish to effectively fuzz the resolvers ability to find solutions; for a properly working resolver if a solution can be found, it must be found. If a solution can’t be found, then this flag should also result in no solution found.

Any deviation from this is a bug in the resolver and should be reported.

Example Usage¶

Merge pkgcore from the gentoo repo:

pmerge sys-apps/pkgcore::gentoo

Output a simple list of package atoms that would be updated for a global update:

pmerge -uDp --formatter basic @world

Force new binpkgs to be built for the entire system set using a custom configuration directory:

pmerge -uDSeb --config /home/foo/portage @system