emerge - Command-line interface to the Portage system
How to use :
emerge [options] [action] <package name>
emerge --sync
emerge --info
emerge --version
emerge --search <string>
emerge --help [system | config | sync]
ACTIONS
emerge <package name>
If no action is specified, the action is to merge in the specified packages, satisfying any dependencies that they may have.
eg. emerge mozilla-firefox - this will emerge firefox and all it's
dependancies.
emerge --clean
Cleans the system by removing packages that will not affect the functionality of the system.
eg. emerge --clean -it will remove all the unnecessary packages, that aren't
needed anymore.
emerge --clean net-www/mozilla-0.9.9-r2 - cleans out that specific
version of Mozilla. This is generally safe to use.
emerge --config <package name>
Run package specific actions needed to be executed after the emerge process has completed. This usually entails configuration file setup or other similar setups that the user may wish to run.
eg. emerge --config postfix - it will start set up process of configuration files and such.
emerge --depclean
Determines all packages installed on the system that have no explicit reason for being there. Packages listed as unnecessary packages are then unmerged after a short timeout.
WARNING: Removing some packages may cause packages which link to the removed package to stop working and complain about missing libraries. Re-emerge the complaining package to fix this issue. Note that changes in USE flags can drastically affect the output of --depclean[]
emerge --help
Displays help information for emerge. Adding one of the additional arguments listed above will give you more specific help information on that subject.
emerge --info
Produces a list of information to include in bug reports which aids the developers when fixing the reported problem. Please include this information when submitting a bug report. Expanded output can be obtained with the --verbose option.
emerge --prune
WARNING: This action can remove important packages! Tries to remove all but the last version installed. Since the command currently does not handle multiple versions of the same package properly, beware! This does not check dependencies, so it may also remove packages necessary for the proper operation of your system. Use --clean instead unless you really know what you're doing.
emerge --resume
Resumes the last merge operation. Please note that this operation will only return an error on failure. If there is nothing for portage to do, then portage will exit with a message and a success condition.
emerge --search <string>
Searches for matches of the supplied string in the portage tree. The --search string is a regular expression.
eg. emerge --search "^kde" -search for any package that starts with "kde"
emerge --search "gcc$" -search for any package that ends with "gcc"
emerge --search "office" -search for any package that contains the
word "office"
emerge --sync
Initiates a portage tree update with one of the rsync.gentoo.org mirrors. Note that any changes you have made to the portage tree will be erased. Except for special circumstances, this uses rsync to do the update. It's preferable to use eix to sync the portage tree.
emerge --unmerge <package name>
- WARNING: This action can remove important packages!** Removes all matching packages. This does no checking of dependencies, so it may remove packages necessary for the proper operation of your system.
eg. emerge --unmerge links - it will remove links package
emerge --unmerge links-2.1_pre26 - it will only remove the
specified version
emerge --update
Updates packages to the best version available. This will also update direct dependencies which may not be what you want. In general, use this option only in combination with the world or system target.
emerge --version
Displays the version number of emerge.
OPTIONS
These are the options that can be passed to emerge. More than one can be used at a time
emerge <option> <package name/string>
eg. emerge --ask --verbose sendmail
emerge -av sendmail
Both of the above are the same thing, you can use either the
longer option or the shorter one, whatever you like. Their
descriptions are given below.
--alphabetical
When displaying USE and other flag output, combines the enabled and disabled lists into one list and sorts the whole list alphabetically.
--ask
Before performing the merge, asks whether to continue with the merge or abort.
WARNING: If the "Enter" key is pressed at the prompt (with no other input), it is interpreted as acceptance of the first choice.
--columns
Used alongside --pretend to cause the package name, new version, and old version to be displayed in an aligned format for easy cut-n-paste.
--debug
Tells emerge to run the emerge command in --debug mode. --debug is great for finding bash syntax errors.
--deep
When used in conjunction with --update, this flag forces emerge to consider the entire dependency tree of packages, instead of checking only the immediate dependencies of the packages.
--emptytree
Reinstalls all world packages and their dependencies to the current USE specifications while differing from the installed set of packages as little as possible. You should run with --pretend first to make sure the result is what you expect.
--fetchonly
Instead of doing any package building, just perform fetches for all packages (the main package as well as all dependencies).
--fetch-all-uri
Instead of doing any package building, just perform fetches for all packages (the main package as well as all dependencies), grabbing all potential files.
--getbinpkg
Using the server and location defined in PORTAGE_BINHOST, portage will download the information from each binary package found and it will use that information to help build the dependency list. This option implies -k. (Use -gK for binary-only merging.)
--getbinpkgonly
This option is identical to -g, as above, except it will not use ANY information from the local machine. All binaries will be downloaded from the remote server without consulting packages existing in the local packages directory.
--ignore-default-opts
Causes EMERGE_DEFAULT_OPTS to be ignored.
--newuse
Tells emerge to include installed packages where USE flags have changed since compilation. An asterisk marks when a USE flag has changed since the package was compiled.
--nocolor
Suppresses all coloring of portage's output.
--nodeps
Merges specified packages without merging any dependencies. Note that the build may fail if the dependencies aren't satisfied.
--noreplace
Skips the packages specified on the command-line that have already been installed. Without this option, any packages, ebuilds, or deps you specify on the command-line *will* cause Portage to remerge the package, even if it is already installed. Note that Portage will not remerge dependencies by default.
--nospinner
Disables the spinner for the session. The spinner is active when the terminal device is determined to be a TTY. This flag disables it regardless.
--oneshot
Emerge as normal, but do not add the packages to the world profile for later updating.
--onlydeps
Only merge (or pretend to merge) the dependencies of the packages specified, not the packages themselves.
--pretend
Instead of actually performing the merge, simply display what *would* have been installed if --pretend weren't used. Using --pretend is strongly recommended before installing an unfamiliar package.
--quiet
Results may vary, but the general outcome is a reduced or condensed output from portage's displays.
--tree
Shows the dependency tree for the given target by indenting dependencies. This is only really useful in combination with --emptytree or --update and --deep.
--usepkg
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.
--usepkgonly
Tells emerge to only use binary packages (from $PKGDIR). All the binary packages must be available at the time of dependency calculation or emerge will simply abort. Portage does not use $PORTDIR when calculating dependency information so all masking information is ignored.
--verbose
Tell emerge to run in verbose mode. Currently this flag causes emerge to print out GNU info errors, if any, and to show the USE flags that will be used for each package when pretending.
OUTPUT
When utilizing emerge with the --pretend and --verbose flags, the output may be a little hard to understand at first. This section explains the abbreviations.
[blocks B ] app-text/dos2unix (from pkg app-text/hd2u-0.8.0)
Dos2unix is Blocking hd2u from being emerged. Blockers are defined when two packages will clobber each others files, or otherwise cause some form of breakage in your system. However, blockers usually do not need to be simultaneously emerged because they usually provide the same functionality.
[ebuild N ] app-games/qstat-25c
Qstat is New to your system, and will be emerged for the first time.
[ebuild NS ] dev-libs/glib-2.4.7
You already have a version of glib installed, but a 'new' version in a different SLOT is available.
[ebuild R ] sys-apps/sed-4.0.5
Sed 4.0.5 has already been emerged, but if you run the command, then portage will Re-emerge the specified package (sed in this case).
[ebuild F ] media-video/realplayer-8-r6
The realplayer package requires that you Fetch the sources manually. When you attempt to emerge the package, if the sources are not found, then portage will halt and you will be provided with instructions on how to download the required files.
[ebuild f ] media-video/realplayer-8-r6
The realplayer package's files are already downloaded.
[ebuild U ] net-fs/samba-2.2.8_pre1 [2.2.7a]
Samba 2.2.7a has already been emerged and can be Updated to version 2.2.8_pre1.
[ebuild UD] media-libs/libgd-1.8.4 [2.0.11]
Libgd 2.0.11 is already emerged, but if you run the command, then portage will Downgrade to version 1.8.4 for you. This may occur if a newer version of a package has been masked because it is broken or it creates a security risk on your system and a fix has not been released yet. Another reason this may occur is if a package you are trying to emerge requires an older version of a package in order to emerge successfully. In this case, libgd 2.x is incompatible with libgd 1.x. This means that packages that were created with libgd 1.x will not compile with 2.x and must downgrade libgd first before they can emerge.
[ebuild U ] sys-devel/distcc-2.16 [2.13-r1] USE=ipv6* -gtk -qt%
Here we see that the make.conf variable USE affects how this package is built. In this example, ipv6 optional support is enabled and both gtk and qt support are disabled. The asterisk following ipv6 indicates that ipv6 support was disabled the last time this packages was installed. The percent sign following qt indicates that the qt option has been added to the package since it was last installed.
- Note: Flags that haven't changed since the last install are only displayed when you use the --pretend and --verbose options. Using the --quiet option will prevent all information from being displayed.
NOTES You should almost always precede any package install or update attempt with a --pretend install or update. This lets you see how much will be done, and shows you any blocking packages that you will have to rectify. This goes doubly so for the system and world sets, which can update a large number of packages if the portage tree has been particularly active.
If emerge --update system or emerge --update world fails with an error message, it may be that an ebuild uses some newer feature not present in this version of emerge. You can use emerge --update portage to upgrade to the lastest version, which should support any necessary new features.