Package and slot moves

This chapter describes the use of package and slot moves. The package update mechanism is a powerful tool, and needs to be used with caution. In particular, the following must be noted:

Updates are not one-shot operations and they are not stateful. All updates can be reapplied multiple times to the same system, and all old updates are applied to fresh Gentoo installations.
Once an update entry is created, the old package name (or slot) cannot be reused for another package. Attempting to reuse it will cause updates to apply again, to the reused name. This also means that while a package can be moved back to its previous name, all the names historically used for a package are reserved to it alone.
Updates can only perform one-to-one moves. They cannot be used to merge packages. Attempting to move two or more packages into a single name may cause serious problems for users.

Moving or renaming a package

Moving or renaming a package (sometimes called a "pkgmove" or just "move") requires several operations. Firstly, verify that the ebuilds will continue to work correctly after the move. If the category changes, you must verify all ${CATEGORY} uses. If the package name changes, you must verify ${PN}, ${P}, etc. Whenever the old value is necessary, substitute the variable reference with the verbatim text, so that it won't get affected by the move. Commit the changes separately before moving the package.

Afterwards, move the package files using git mv. Add the move entry to profiles/updates/ in the following format:

move old-category/old-name new-category/new-name

Following the update entry, find all references to the old package name and update them. These include:

dependencies, optfeature.eclass uses, has_version and best_version uses in other ebuilds and eclasses
all profiles/ tree entries (e.g. profiles/package.mask)
restrict entries in package metadata.xml files, as well as <pkg/> tags
news item Display-If-Installed
open bug summaries
wiki pages

Preferably, combine all those changes into a single commit to ensure atomicity during the update.

Changing ebuild's SLOT

The process for changing the ebuild's SLOT (a "slotmove") is very similar to the previous process. Besides changing the SLOT in the ebuild file, you also need to create a new entry in profiles/updates/ in the Gentoo repository in the following format:

slotmove app-text/gtkspell 0 2

Make sure that you have fixed all the reverse dependencies and that you have updated every file in profiles/ directory that happens to contain an entry which may be affected by your change.

Updating prior update entries when moving the package again

When the same package is moved again, the previous update entries should be updated appropriately. This is meant to make the situation more transparent to users reading update entries and to ensure that the process is handled efficiently even if the package manager does not implement updates in a robust way. This involves the following steps:

The previous package moves for the package in question must be updated to reference the final name. That is, rather than the chain A → B → C, we want to have two update entries: A → C, and B → C.
If the package is being moved to a name that it used before, the original move entry must be removed. That is, rather than the chain A → B → A, we want to have the reverse entry: B → A. If the package manager did not move A → B before, we don't want it to touch the package at all.
As a combination of the two aforementioned steps, a chain of A → B → C → A would be replaced by two moves: B → A, and C → A.
If the package was slot-moved before, the slot moves should be updated to use the final package name, and moved after the final package move. That is, rather than the chain: A:S₁ → A:S₂, A → B; we prefer to have the chain: A → B, B:S₁ → B:S₂. All package and slot move entries must reside in the same file then, to guarantee sequential processing.