portage(5) states the information to not use metadata/cache when using eclass-overrides (in the 'repos.conf' section). This information refers to bug #276264. But this bug has been marked RESOLVED FIXED and also it seems to work without removing metadata/cache. Hence: If this issue is really fixed, please remove this outdated information. If not (and it happens to work by accident), please update the information to not refer to a fixed bug. Thanks!
Since bug 409445, we've migrated our repository to the new metadata/md5-cache (aka md5-dict) format, which solves the issues with eclass-overrides. However, if you're using some other repository that distributes just the metadata/cache directory, then it would still be a problem for that repository. Currently, I'm taking steps toward deprecating the old metadata/cache format, so that the issue will be completely resolved. The first step is in that latest versions of portage (which haven't been marked stable yet): http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=commit;h=24b7ebe3b9404f0344f5b34eb322abde64143263
The information in portage(5) still seems accurate. Although Gentoo's repository does contain the problematic metadata/cache directory any more, it could still be an issue for third-party repositories (like I mentioned earlier). The reason that bug 276264 is marked RESOLVED FIXED is that portage(5) was updated to add the relevant warning message.
Thanks for this clarification. Would it possible perhaps to add a short note, that this does not concern the main gentoo tree (for me the notation 'your portage tree' is synonym with the main gentoo tree -- the rest are overlays)? Also the PORTAGE_RSYNC_EXTRA_OPTS hint is not needed anymore? Or is it used for something that is NOT the gentoo main tree?
egencache: enable md5-dict format by default http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=commit;h=e760c8d2a4ccc56e351ac37904c715f596b58e42 portdbapi: DeprecationWarning for 'pms' cache http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=commit;h=02a6bf1ac95861831a303f220c7a41b9bbd398ab With these changes, we can now go ahead and remove the reference to bug #276264 from the docs: http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=commit;h=a73d9ae594b24efe35fa8c0c1c00ea06dc80886a
This is fixed in 2.1.11.32 and 2.2.0_alpha143.