Gentoo Linux, being a true meta-distribution, give users maximum flexibility and control
over the system. A stark example of this is the OS upgrade process. Users have a large
choice of different command utilities and a bunch of configuration option to choose from
to tailor the upgrade process to their needs. This guide will attempt to combine and
distill the best practices and recommendations from the Gentoo Wiki/Forums and other
sources into a single guide.
TLDR:
emaint sync -a
emerge --ask --verbose --update --newuse --deep @world
dispatch-conf
emerge --ask --depclean
revdep-rebuild
eclean -d distfiles
Preqrequisites
@world
The @world set is a special set that contains all the packages that are installed on the system. It is used to update the system.
I did an overview of sets in Gentoo World Set.
Use flags
Use flags are used to control the compilation of packages. They are used to enable or disable certain features of a package. For example, the X use flag is used to enable or disable the X11 support in a package.
I did an overview of use flags in Gentoo USE Flags.
Command-line tools that might be used during the upgrade
Tecnhically emerge can do all the basic steps, but there are other tools that might be useful:
eix- search for packagesequery- query information about packagesemaint- maintenance tool for Portageeuse- manage USE flagsetc-update- update configuration files (old program)dispatch-conf- update configuration fileseselect- manage system configurationelogv- view the latest entries in the Portage logsneedrestart- check if a restart is needed after updateeclean- clean up obsolete fileseclean-kernel- clean up old kernelsqcheck- check for broken packagesrevdep-rebuild- rebuild packages that depend on a package that has been updatedglsa-check- check Gentoo Linux Security Advisory for security updateslayman- manage overlays
Step 1: Sync Portage Tree
The first step is to sync the Portage tree. This is done by running the following command:
emaint --auto sync
It downloads the latest version of the Portage tree and the metadata from the Gentoo mirrors.
Step 2: Update the System
There are many ways to update the system. To do the most basic full update run:
emerge --ask --verbose --update --newuse --deep @world
Flags:
--ask- ask before performing the action--verbose- show more information--update- update to the best available version (not neweset)--newuse- include installed packages where USE flags have changed since compilation--deep- update entire dependency tree, even libraries that are not directly listed in the dependencies of a package
Other options:
--keep-going- continue updating even if a package fails to update--oneshot- install package without adding it to the world file
Step 3: Update the Configuration Files
Sometimes after an update configuration files might change. When this happens, Portage create a new config at
/etc/portage/config/._cfg0000_etc_file_name_ and leaves the old config at /etc/file_name.
dispatch-conf can be used to interactively update the configuration files.
Step 4: Clean up obsolete packages
After multiple updates, some packages might become obsolete (stop being other package’s dependencies). To clean them up run:
emerge --ask --depclean
Step 5: Verify system consistency after cleanup
In some rare case libraries and dependencies might not be installed or be broken. To re-emerge them run:
revdep-rebuild
Step 6: Clean up source code
After multiple updates, some package source files might become obosolete. A common example is Linux kernel source. To clean them up run:
emerge --ask --verbose --depclean
Step 7: Additional (optional) steps
Update Portage itself when needed:
emerge -1v portage
Read the news:
eselect news read
Read update information from logs:
elogv
Check if a restart is needed:
needrestart
Remove old kernels:
eclean-kernel -n 1