emerge.8

.TH emerge  8 "January 13, 2022" "version 0.1" "EMERGE MANUAL"
.SH NAME
emerge -\ bring package database in sync with a configuration set
.SH SYNOPSIS
.B emerge [options]
.SH DESCPRIPTION

Emerge is a frontend for pacman which, rather than taking commands such as
"install foo" or "remove bar", looks at a set of configuration files to
determine what should be on the system, then brings system in sync with that
view.

This mirrors the concept used by Gentoo's emerge package management tool.
As such, the command line arguments have been redesigned to approximate Gentoo's
emerge syntax as well.

As this is a secondary package management tool on top of an existing package
management system, the ability to import an existing system package
configuration has been added for ease of migration into this paradigm.  This
is done when an existing EMERGE_CONF/world.set is not present (such as during
the initial run), or when emerge is passed the
.B --rebuild-world-set
argument.  If an existing world.set file is present, it is safely backed up
before any rebuild begins.

See the
.B -h
or
.B --help
output for other options.

Since this tool is meant to mimic Gentoo's emerge options, you can also look
at the usage and description of that tool and its options, as the options
that have been reimplemented here should be quite similar in function.

.SH CONFIGURATION

Configuration files for emerge belong in the directory contained in
$EMERGE_CONF, or /etc/emerge if it is not defined. The configuration defines
sets of packages. Each set comes in the form of a pair of files, <setname>.set
and <setname>.mask, where <setname> is the name of the set. The .set file
specifies a list of packages, groups, and other sets that should be included
in the file. The .mask file is of the same form, but specifies packages,
groups, and other sets that should be ommitted from the set, even if would
otherwise be included. The form of these files is a series of lines, each of
which names a package, set, or group. If the line begins with a '<', its
remainder specifies a set name, if it begins with a '@' its remainder
specifies a group name, and otherwise the line specifies a package.

The special set 'world' determines the set of packages that should be
explicitly installed on the system. When emerge is run, it will ensure that
all packages in world are explicitly installed, no other packages are
installed explicitly, and only packages in world and their dependencies (both
direct and indirect) are installed.

If the user running emerge (typically root) has execute permissions on a .set
or .mask file, then instead of reading from the file, the file will be executed
and it's output will be used.

.SH EXAMPLES

A set which contains all of the xorg group except for those packages in the xorg-drivers
group, plus xf86-video-intel and xf86-input-synaptics:

.B x11.set:

.nf
@xorg 
xf86-video-intel
xf86-input-synaptics
.fi

.B x11.mask:

.nf
@xorg-drivers
.fi

A set which contains all of kde, except for the kdegames group:

.B kde.set:

.nf
@kde
.fi

.B kde.mask:

.nf
@kdegames
.fi

A possible world set for a kde desktop machine, given the two sets above:

.B world.set:

.nf
@base
@base-devel
<x11
<kde
.fi

(world.mask is empty)

If the same groups of packages, with slight variations are to be used on multiple machines,
world.set can be made executable, and contain:

.nf
#!/bin/sh

echo '<'`hostname`
.fi

Then, individual sets for each host can be created. They may include common sets.

.SH ENVIRONMENT VARIABLES

EMERGE_CONF - location in which to look for configuration sets.

.SH AUTHORS
Brian Gisseler <gissf1@gmail.com> (arch-emerge author)
.br
Ian Denhardt <ian@zenhack.net> (original pacsync author)

.SH BUGS
None hopefully. Contact the author if you find evidence to the contrary.