document the term "ghost"

maxb: "A ghost is when you know a revision was merged, but you don't know anything else about the merged revision besides its id"

Possible causes: Repository format changes, uncommits, bugs, plugin code.

Generally not be an issue for end users, however might come up during repository forensics or debugging.

It could also be described as a revision that is mentioned *only* as a parent of another revision.
Only the rev_id is known, nothing else.
uncommits shouldn't create ghosts AFAIK that would be a serious bug. repo format changes either.

I also think it can be seen by users when they are generated on purpose (like some bzr-svn workflows) and should be handled as gracefully as we can.

Also, some ghosts *can* be filled if the repository that contain them is available.

If repoA doesn not contain <ghost> but repoB contains it, you can fill <ghost> by doing (untested but explaining the concept):

cd <somewhere below repoA>
bzr init dummy ; cd dummy
bzr pull -r<ghost> <some branch in repoB>
cd .. ; rm -fr dummy

This is documented in the glossary now ("brz help glossary")