bzr resolve

[Stephen J. Turnbull]

Aaron Bentley writes:

 > I find [bzr resolve] well-documented.

You *must* be joking.  Hmm ... maybe you're not. :-(

You might try remembering that very few people are as familiar with
the code or as practiced in the use of bzr as you are.

Let me walk you through it.  When reading "help bzr resolve", you
aren't given the values or even general semantics of --action.  It's
not obvious that the thing to do is follow the "See also" to "help bzr
conflicts", but maybe you do.  This doesn't help at all, but maybe you
follow the "See also" to "help bzr conflicts.  Now, once you've waded
through 48 lines (as it happens, the terminal I'm reading that in has
49 lines, so it is on the first screen), you finally find out that
--action can take the value "done".  Even then, I need to pagedown
twice to find the other values that --action takes, and only at the
bottom of that page -- around 135 lines into the second "See also" --
is there a list that implies ['done', 'take-other', 'take-this'] is
the full list.  The shortcut options --take-this and --take-other are
only mentioned in the generated usage message, and nowhere is the
no-argument form recommended, let alone a rationale given.  In fact,
although the possibility of a no-argument form is implicit in the
generated usage message, it is mentioned exactly once in "bzr help
resolve," and is otherwise not mentioned in "help" AFAICS.

At the very least, the text in "bzr help resolve" that reads:

    Once you have fixed a problem, use "bzr resolve" to automatically
    mark text conflicts as fixed

could be expanded to

    Once you have fixed a problem, use "bzr resolve" to automatically
    review files marked as 'text conflict', and mark each conflict as
    resolved if no conflict markers are present in the file.

(Assuming, of course, that's a correct description of the semantics of
"bzr resolve" with no arguments, which still isn't clear to me.)  The
"conflict-types" topic should be added to "See also."  It
wouldn't hurt to add

    A detailed description of conflict types and how each can be
    resolved using bzr is provided in the topic "conflict-types."

to the text.

 > However, I will cheerfully accept suggestions for improvements.

I made several in a previous post, some of which you've attempted to
rebut, but not all.

Even in the issue about the use of the verb "resolve", I take your
point that sometimes bzr does more than simply mark a file as not in
conflict, but "resolve" implies decision-making about how to resolve,
while this command does *not* make any such decisions (to the extent
that there are plausible heuristics, they are and should be
implemented in merge, not in resolve).

 > Why are we talking about --all?

Because it is the kind of unsafe option that makes one distrust the
reliability of the command in general.  The duplication of --action
vs. --take-this, --take-other, and (implicitly) "--mark-done" doesn't
help either (TOOWTDI violation).

 > I think that your suggestion to make it "safe" simply makes it
 > redundant.  Although we disagree,

Not just me.  vila doesn't seem to be 100% satisfied, either.  Nobody
(but you) seems to like the fact that "bzr resolve" and "bzr resolve
*" have semantics that differ in a way that almost guarantees that
"bzr resolve *" is a bug.  (I'm not referring to the fact that "bzr
resolve" is recursive and "bzr resolve *" is not -- while I don't
normally use * with "resolve" to limit effect to the current
directory, I *frequently* use such wildcards to prevent recursion into
subdirectories for other VCS commands and in general -- that semantics
is well-understood, I think).