Good point. I tend to deliberately omit talking about multi-package repositories to avoid throwing out too much information — but also because I don’t feel that comfortable with them yet, for some reason. I’m also not a big fan of pushing this feature yet, in case people are working in pre-v1.5 environments (but that’s probably not a good reason).
I really should start playing with this feature more. It does address a very real issue in a rather elegant (straightforward way).
Though I must say I would probably find them much less confusing if all packages in these multi-package Git repository bundles were registered simultaneously under the same revision number. I realize that means more Pkg complexity, and less flexibility in our solutions, but I think it better fits the way Git repositories work.