Profiles package.mask file

The package.mask file can be used to hard mask packages or certain versions of packages that should not be merged by users. This is often used when adding certain experimental (either in ebuild or upstream terms) packages to the tree, or to prevent merging of packages that are broken or break something else. Every entry should have a comment detailing the specific reason for the mask. The format of the package.mask file is described in man portage.

Development or unstable (per upstream declaration/categorization) versions of packages should usually be masked in package.mask. Upstreams may not deem such releases to be ready for general distribution (or safe to use), or may not be expecting bug reports from the wider userbase yet. The default should generally be to mask such versions, but it is acceptable to not mask in some circumstances — e.g. upstream make very infrequent releases, the changes are safe (reviewed by the Gentoo maintainer), or perhaps other distributions are shipping the same new version. As an alternative to a development version, you may also consider backporting required upstream fixes to the released version.

Overall, masking something and unmasking if it turns out to be stable is safer (and leads to a better user experience) than the inverse (pushing unmasked and breakage occurring).

Entries are added chronologically — that is, newer entries should be placed towards the top of the file, underneath any initial header comment block.

This file can be used in subprofiles to mask packages only for certain setups.