.TH "EMERGE" "1" "Feb 2003" "Portage 2.0.47" "Portage"

.TH "EMERGE" "1" "Feb 2003" "Portage 2.0.48" "Portage"

[\fIoptions\fR] [\fIaction\fR] \fBebuildfile\fR

\fBsync\fR | \fBinfo\fR

\fBsync\fR | \fBrsync\fR

\fI\-\-resume\fR [\-\-\fBpretend\fR | \-\-\fBskipfirst\fR]

Cleans the system by removing packages that will not effect the

Cleans the system by removing outdated packages which will not

functionality of the system.  The arguments can be \fIebuilds\fR,

remove functionalities or prevent your system from working.

\fIclasses\fR, or \fIdependencies\fR.  For example, \fBemerge

The arguments can be \fIebuilds\fR, \fIclasses\fR, or

clean binutils\fR cleans out old versions of binutils;

\fIdependencies\fR.  For example, \fBemerge clean binutils\fR

\fBemerge clean net\-www/mozilla\-0.9.9\-r2\fR cleans out that

cleans out old versions of binutils;

specific version of Mozilla.  This is generally safe to use.

\fBemerge clean net\-www/mozilla\-0.9.9\-r2\fR cleans out

that specific version of Mozilla. This is generally safe to use.

Determines all packages installed on the system that have no

Cleans the system by removing packages that are not associated

explicit reason for being there.  \fBemerge\fR generates a list

with explicitly merged packages. Depclean works by creating the

of packages which it expects to be installed by checking the

full dependency tree from the system list and the world file,

\fBsystem\fR package list and the \fBworld\fR file.  It then

then comparing it to installed packages. Packages installed, but

compares that list to the list of packages which are actually

not associated with an explicit merge are listed as candidates

installed; the differences are listed as unnecessary packages

for unmerging. \fBWARNING: This can seriously affect your system by

and are suggested for unmerging. \fBWARNING: Removing some

removing packages that may have been linked against, but due to

packages may cause packages which link to the removed package

changes in USE flags may no longer be part of the dep tree. Use

to stop working and complain about missing libraries.\fR

caution when employing this feature.\fR

Re\-emerge the complaining package to fix this issue.

\fBNote that changes in USE flags can drastically affect the

output of depclean.\fR

\fBhelp\fR (\fB\-h\fR)

\fB\-\-help\fR (\fB\-h\fR)

This is a list of information to include in bug reports which aids

Displays important portage variables that will be exported to

the developers with fixing any problems you may report. \fBPlease

ebuild.sh when performing merges. This information is useful

include this information when submitting a bug report.\fR Expanded

for bug reports and verification of settings. All settings in

output can be obtained with the \fI--verbose\fR option.

make.{conf,globals,defaults} and the environment show up if

run with the '\-\-verbose' flag.

Injecting a package inserts a 'stub' for that package so that Portage

Add a stub entry for a package so that Portage thinks that it's

thinks that it is installed. It is handy if you need, say, a binary

installed when it really isn't. Handy if you roll your own

version of XFree86 for esoteric hardware, or you just like to roll

packages.  Example:

your own packages.  You \fBmust\fR specify a category and particular

\fBemerge inject sys-kernel/gentoo-sources-2.4.19\fR

version of a package for injecting.  For example,

\fBemerge inject sys\-kernel/gentoo\-sources\-2.4.19\fR.

\fBWARNING: This action can remove important packages!\fR Removes

\fBWARNING: This action can remove important packages!\fR

all but the latest versions of matching packages.  If there are

Removes all older versions of a package from your system.

multiple SLOTs for a package, it leaves the latest version in each

This action doesn't always verify the possible binary

SLOT. This does no checking of dependencies, so it may remove

incompatibility between versions and can thus remove essential

packages necessary for the proper operation of your system. \fBUse\fR

dependencies from your system.

clean \fBinstead unless you really know what you're doing\fR.  Its

The argument format is the same as for the \fBclean\fR action.

arguments can be \fIebuilds\fR, \fIclasses\fR, or \fIdependencies\fR

.TP

\-\- see \fBclean\fR above for examples.

\fBregen\fR

.TP

Causes portage to check and update the dependency cache of all

\fBrsync\fR

ebuilds in the portage tree. This is not recommended for rsync

See \fBsync\fR below.

users as rsync updates the cache using server-side caches.

Rsync users should simply '\fBemerge sync\fR' to regenerate.

Searches for matches of the supplied string in the portage tree.

Searches for matches of the supplied string in the current local

The search string is a regular expression.  For example, \fBemerge

portage tree. The search string is a regular expression.

search "^kde"\fR searches for any package that starts with "kde";

A few examples:

\fBemerge search "gcc$"\fR searches for any package that ends with

  \fBemerge search '^kde'\fR

"gcc"; \fBemerge search "office"\fR searches for any package that

    list all packages starting with kde

contains the word "office".  If you want to search the package

  \fBemerge search 'gcc$'\fR

descriptions as well, use the \fB\-\-searchdesc\fR,\fB-S\fR option.

    list all packages ending with gcc

  \fBemerge search ''\fR or

  \fBemerge search '.*'\fR

    list all available packages

\fBWARNING: This action can remove important packages!\fR Removes

\fBWARNING: This action can remove important packages!\fR

all matching packages.  This does no checking of dependencies, so

Removes all matching packages without checking for outdated

it may remove packages necessary for the proper operation of your

versions, effectively removing a package \fBcompletely\fR from

system. Its arguments can be \fIebuilds\fR, \fIclasses\fR, or

your system. Specify arguments using the dependency specification

\fIdependencies\fR \-\- see \fBclean\fR above for examples.

format described in the \fBclean\fR action above.

.TP

\fB\-\-version\fR

Displays the version number of \fBemerge\fR.

Used along side \fI--pretend\fR to causes the package, new version,

Display the pretend output in a tabular form. Versions are

and old version to be displayed in an aligned format for easy cut\-n\-paste.

aligned vertically.

Tells emerge to run the emerge command in \-\-debug mode.  In this

Tells emerge to run the emerge command in \fB\-\-debug\fR mode.  In this

\fB\-\-deep\fR

\fB\-\-deep\fR (\fB\-D\fR)

Virtually tweaks the tree of installed packages to only contain glibc;

Virtually tweaks the tree of installed packages to only contain glibc,

this is great to use together with \-\-pretend. This allows developers

this is great to use together with \fB\-\-pretend\fR. This makes it possible for

to get a complete overview of the complete dependency tree of a package,

developers to get a complete overview of the complete dependency tree of a package,

packages (the main package as well as all dependencies.)

packages (the main package as well as all dependencies). When

used in combination with \fB\-\-pretend\fR all the SRC_URIs will be

displayed multiple mirrors per line, one line per file.

Causes portage to disregard merge records indicating that a config file

Portage keeps track of files that have been placed into

inside of a CONFIG_PROTECT directory has been merged already. Portage

CONFIG_PROTECT directories, and normally it will not merge the

will normally merge those files only once to prevent the user from

same file more than once, as that would become annoying. This

dealing with the same config multiple times. This flag will cause the

can lead to problems when the user wants the file in the case

file to always be merged.

of accidental deletion. With this option, files will always be

.TP

merged to the live fs instead of silently dropped.

\fB\-\-nodeps\fR

.TP

Merges specified packages without merging any dependencies.  Note that

\fB\-\-nodeps\fR (\fB\-O\fR)

the build may fail if the dependencies aren't satisfied.

Merges specified packages, but don't merge any dependencies.  Note that

the build may fail if deps aren't satisfied.

for later updating.

for later updating. This prevents consideration of this package

unless this package is depended upon by another package.

Instead of actually performing the merge, simply display what *would*

Instead of actually performing the merge, simply display what

have been installed if \-\-pretend weren't used.  Using \-\-pretend

ebuilds and tbz2s *would* have been installed if \-\-pretend

is strongly recommended before installing an unfamiliar package. In

weren't used.  Using \-\-pretend is strongly recommended before

the printout, N = new, U = upgrading, R = replacing, B = blocked by

installing an unfamiliar package.  In the printout, N = new,

an already installed package.

U = updating, R = replacing, B = blocked by an already installed

package, D = possible downgrading. \-\-verbose causes affecting

use flags to be printed out accompanied by a '\+' for enabled

and a '\-' for disabled flags.

.TP

\fB\-\-quiet\fR (\fB\-q\fR)

Effects vary, but the general outcome is a reduced or condensed

output from portage's displays.

.TP

\fB\-\-resume\fR

Resumes the last merge operation. Can be treated just like a

regular merge as \-\-pretend and other options work along side.

'emerge \-\-resume' only returns an error on failure. Nothing to

do exits with a message and a success condition.

the package name.  \fBTake caution\fR as the descriptions are also

the package's name. \fBTake caution\fR as the descriptions are also

Updates packages to the most recent version available.  \fBNote that\fR \-\-update \fBdoes not have full functionality yet\fR.  It will not automatically update dependencies of packages in the \fBworld\fR file, unless they too are in the \fBworld\fR file.

Updates packages, along with their dependencies, to the best

.TP

version available, which may not always be the highest version

\fB\-\-usepkg\fR (\fB\-k\fR) 

number due to masking for testing and development.

Tells emerge to use binary packages (from $PKGDIR) if they are available, thus possibly avoiding some time\-consuming compiles. This option is useful for CD installs; you can export PKGDIR=/mnt/cdrom/packages and then use this option to have emerge "pull" binary packages from the CD in order to satisfy dependencies.

.TP

\fB\-\-upgradeonly\fR (\fB\-U\fR)

Updates packages, but excludes updates that would result in a

lower version ofthe package being installed. SLOTs are

considered at a basic level.

.TP

\fB\-\-usepkg\fR (\fB\-k\fR)

Tell emerge to use binary packages (from $PKGDIR) if they are

available, thus possibly avoiding some time-consuming compiles.

This option is useful for CD installs; you can export

PKGDIR=/mnt/cdrom/packages and then use this option to have

emerge "pull" binary packages from the CD in order to satisfy

dependencies.

.TP

\fB\-\-usepkgonly\fR (\fB\-K\fR)

Like \-\-usepkg above, except this only allows the use of binary

packages, and it will abort the emerge if the package is not

available at the time of dependency calculation.

\fB\-\-version\fR

\fB\-\-version\fR (\fB\-V\fR)

Displays the version number of \fBemerge\fR.  It cannot be used in

Displays the currently installed version of portage along with

conjunction with other options; the name and format of the action

other information useful for quick reference on a system. See

is a convention.

\fBemerge\fR info for more advanced information.

.BR emerge --help,

\fBemerge \-\-help\fR,

.BR ebuild (1),

\fBebuild\fR(1),

.BR ebuild (5),

\fBebuild\fR(5),

.BR make.conf (5)

\fBmake.conf\fR(5)

Contains the USE flags that are enabled by default. \fBDo not edit this

Contains packages that, if installed, cause respective USE flag to be enabled by default.

file\fR.

\fBDo not edit this file\fR.

\fB/usr/portage/profiles/use.desc\fR 

\fB/usr/portage/profiles/use.desc\fR

\fB/etc/make.profile/virtuals\fR 

\fB/etc/make.profile/virtuals\fR

\fB/etc/make.profile/package\fR

\fB/etc/make.profile/packages\fR