[doc] inadequate documentation of "revert --forget-merges"

[Eli Zaretskii]

The documentation of the --forget-merges option to "revert" is confusing and insufficient:

   The working tree contains a list of pending merged revisions, which will
   be included as parents in the next commit. Normally, revert clears that
   list as well as reverting the files. If any files are specified, revert
   leaves the pending merge list alone and reverts only the files. Use "bzr
   revert ." in the tree root to revert all files but keep the merge record,
   and "bzr revert --forget-merges" to clear the pending merge list without
   reverting any files.

   Using "bzr revert --forget-merges", it is possible to apply the changes
   from an arbitrary merge as a single revision. To do this, perform the
   merge as desired. Then doing revert with the "--forget-merges" option will
   keep the content of the tree as it was, but it will clear the list of
   pending merges. The next commit will then contain all of the changes that
   would have been in the merge, but without any mention of the other parent
   revisions. Because this technique forgets where these changes originated,
   it may cause additional conflicts on later merges involving the source and
   target branches.

The main stumbling block is the notion of "pending merges" or "pending merged revisions". It is not explained anywhere in the manual, although it is used in documenting other commands. Without explaining what it means, it is impossible to understand what exactly is "forgotten" when this option is used.

The notion of "pending merges" is hard to understand without a detailed and clear explanation because it abuses the usual language conventions: the user has already done "bzr merge", so conceptually the merge was already performed, and is no longer "pending". The fact that "bzr merge" does only part of the job, and should be followed by "bzr commit" to finish it, and that "pending merges" actually refers to _uncommitted_ merges is what is missing from the above documentation.

A few additional comments on this part of the documentation:

   The working tree contains a list of pending merged revisions, which will
   be included as parents in the next commit.

I think "merged revisions" cannot be contained by the working tree. The working tree is just the set of files that are part of a project. The list of merged _revisions_ is stored somewhere in the metadata that is part of a branch, not in the working tree. Also, what does it mean "will be included as parents"? parents of what?

   If any files are specified, revert
   leaves the pending merge list alone and reverts only the files.

This seems to imply that after "bzr revert foo bar baz", the working tree and the "pending merge list", whatever it is, are now out of sync: the latter indicates that foo, bar, and baz where merged, but they in fact are exactly as in the last committed revision. That sounds bad, doesn't it? If not, the docs should explain why not, right there and then. Otherwise, the user is left wondering whether doing this will get her in trouble.

   The next commit will then contain all of the changes that
   would have been in the merge, but without any mention of the other parent
   revisions.

What are the "other parent revisions" that will not be mentioned in the commit following "bzr revert --forget-merges"? what is the significance of the word "parent" in this context? Also note how it again confusingly mixes "commit" and "merge": "the next commit will then contain changes that would have been in the merge".

[Martin Pool (mbp)]

I agree these things should be improved, but to at least explain them here, as a sketch of what should go for the document:

As you have surmised, pending merges means changes that have been merged but not yet committed.

> I think "merged revisions" cannot be contained by the working tree.

They are contained by the working tree metadata (ie the contents of .bzr/checkout).

> Also, what does it mean "will be included as parents"? parents of what?

Revisions have parent revisions: none for the first commit, one normally, and two or more for commits of merges.

> This seems to imply that after "bzr revert foo bar baz", the working tree and the "pending merge list", whatever it is, are now out of sync: the latter indicates that foo, bar, and baz where merged, but they in fact are exactly as in the last committed revision. That sounds bad, doesn't it?

That is correct. It's only bad if it's not what you want. ;-)

Thanks very much for pointing out these doc bugs, a pair of fresh eyes is immensely useful for picking up these problems.

[Neil Martinsen-Burrell (nmb)]

This has been addressed in a recent revision of bzr.dev. Please check and see if it addresses your concerns. If not, please re-open the bug.