The text at the URL says: When you don't want Portage to take a certain package or a specific version of a package into account you can mask it yourself by adding an appropriate line to the /etc/portage/package.mask location (either in that file or in a file in this directory). So this leads the reader to the wrong conclusion that a line in package.unmask will work only if it matches the package.mask line exactly, and that the only effect of that file is to cancel out (i.e., pretend that they are not really there) the exactly matching lines in the existing package.mask files. The real logic in portage seems to be different: it evaluates the package against each atom in package.unmask. If it is unmasked, then portage assumes that it is not masked and doesn't look anywhere else. Only if a package doesn't match any atoms in package.unmask, the atoms in package.mask are consulted. Reproducible: Always Steps to Reproduce: 1. Read documentation 2. Attempt to make sure that portage-2.2_rc75 from the main tree is ignored (portage and its version are used as an example only) while allowing all other 2.2_rc* versions, based on that reading: in /etc/portage/package.unmask put a copy of the existing line from /usr/portage/profiles/package.mask: >=sys-apps/portage-2.2_pre in /etc/portage/package.mask put the atom matching the single unwanted version: =sys-apps/portage-2.2_rc75 Actual Results: portage-2.2_rc75 is still considered. This is correct, but unexpected. Expected Results: Based on the text in the handbook, I should have had more correct expectations and should not have attempted to avoid portage-2.2_rc75 this way. Irrelevant.
The documentation is fine. I think you're running into some weird versioning issue of hardmasked (i.e. unsupported) versions of Portage, in which case, only the Portage team can fix the logic, and find some different versioning scheme so that p.mask works correctly. Not something the documentation team can do anything about.
I am not sure if this indeed is a versioning issue of portage. To figure this out, please answer the following questions. 1) Am I supposed to be able, given the existing versioning scheme of portage, to unmask all versions of portage-2.2 except 2.2_rc75? (in fact, this is achievable by putting into package.unmask some lines that are not copies of existing lines in package.mask) If this is false, then the bug is indeed about versioning of masked packages (not just portage). 2) Is it an intended interpretation of the handbook that one should put into package.unmask only copies of to-be-cancelled lines that already exist in package.mask, and the rest is undefined? If this is false, the text should be changed to avoid this misinterpretation. If both (1) and (2) are true, then the bug is that these statements contradict each other.
(In reply to comment #2) > I am not sure if this indeed is a versioning issue of portage. To figure this > out, please answer the following questions. All versions of portage use the same package.mask/unmask logic. > 1) Am I supposed to be able, given the existing versioning scheme of portage, > to unmask all versions of portage-2.2 except 2.2_rc75? (in fact, this is > achievable by putting into package.unmask some lines that are not copies of > existing lines in package.mask) > > If this is false, then the bug is indeed about versioning of masked packages > (not just portage). I'm not sure what you're asking there. Maybe you can clarify by providing some more usage examples and expected results. > 2) Is it an intended interpretation of the handbook that one should put into > package.unmask only copies of to-be-cancelled lines that already exist in > package.mask, and the rest is undefined? > > If this is false, the text should be changed to avoid this misinterpretation. > > If both (1) and (2) are true, then the bug is that these statements contradict > each other. I think what the handbook has done it to describe what the writers consider to be a "best practice" for using package.umask. There are other ways to use it, but the interest of the writers was to describe "best practice".
1) The handbook correctly explains how to mask an unwanted version of a package and also how to unmask a package. The use case that led to this report is a combination of the two situations: suppose that there is a package with masked betas that you want to use. The handbook tells you how to unmask them. You do so by copying the line about these betas from package.mask to package.unmask. After that, you use the beta for some time, then upgrade it and notice a regression. You want to re-mask that single bad version while keeping the general "unmask betas of this package" rule intact. The documented way of masking a bad version (adding a line to your package.mask) doesn't work because of the interaction with the existing unmask. I.e. given that >=foo-bar/baz-1.3 is masked, how to unmask 1.3.1, 1.3.2, 1.3.3, 1.3.5 (not released yet), 1.3.6, ... but not 1.3.4? 2) So it is clearly a misunderstanding from my part. The handbook doesn't say that copying lines for unmasking is only the best practice, not the hard rule.
(In reply to comment #1) > The documentation is fine. Maybe the documentation should say that it's giving a "best practice", since that's not the only way to use package.unmask (as said in comment #4)? We could also make it refer to the portage(5) man page for more detailed usage instructions. > I think you're running into some weird versioning > issue of hardmasked (i.e. unsupported) versions of Portage, in which case, only > the Portage team can fix the logic, and find some different versioning scheme > so that p.mask works correctly. > > Not something the documentation team can do anything about. All versions of portage use the same package.mask/unmask logic. Maybe it could be documented better though (if not in the handbook, then in the portage(5) man page).
(In reply to comment #5) > All versions of portage use the same package.mask/unmask logic. Maybe it could > be documented better though (if not in the handbook, then in the portage(5) man > page). I added a bit of clarification to the handbook on using p.unmask. Anything else you thought of should go into the manpages.
