bzr resolve

[Aaron Bentley]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 12-07-27 09:55 PM, Stephen J. Turnbull wrote:
> Aaron Bentley writes:
> 
>> I find [bzr resolve] well-documented.
> 
> You *must* be joking.  Hmm ... maybe you're not. :-(

No, I'm not.  In fact, I'm making the point that merely saying "poorly
documented" doesn't convey much useful information to those who wrote
the documentation.

> 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.

Actually, I was hoping you might remember that.  Although we try to
see the subject from a user's perspective, we don't always succeed.
And when we don't, simply saying that we've failed is too vague to
improve matters.  It we could see why it was poor, we wouldn't have
written it that way.

> Let me walk you through it.

Thanks!

> When reading "help bzr resolve", you aren't given the values or
> even general semantics of --action.

I agree.  I've never been a fan of supplying enumerations as
value-accepting options.  One of the main reasons is that we never had
any good way of listing the enumeration values.

Since --action is redundant with the other options in that section, I
would remove it if I had my druthers.  Unfortunately, other
contributors don't agree with me.

> 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.

The statements "nowhere is the no-argument form recommended" and "[the
no-argument form] it is mentioned exactly once in "bzr help
> resolve,"" seem contradictory to me.  Can you explain what you
> mean?

> 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.

Seems reasonable.

> (Assuming, of course, that's a correct description

It is.

> of the semantics of "bzr resolve" with no arguments, which still
> isn't clear to me.)

You said:

> Sane behavior for "bzr resolve" with no arguments would be to
> 
> (1) check the tree for files containing conflict markers, (2)
> update the list of conflicted files, and (3) print the list.

And I said:

> That sounds like what it does.

I should add that in step (1), it does not examine the whole tree,
only files marked as having text conflicts.  So there is no chance
that it would *add* conflict markers to files.

What else would you like to know?

> 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.

I did not think the rest needed rebutting.  For reference:

> (a) All uses of the verb "resolve" should be changed to "mark as 
> resolved."  (b) Where "resolve" has additional semantics, as the 
> --take-other and --take-this options apparently imply, these should
> be spelled out explicitly.  Eg, "--take-this    Preserve the
> pre-merge version in the working tree (discarding the merged
> version), and mark the conflict as resolved."  (c) List the values
> that may be used for ARG in the --action option.  (d) The
> Description should describe the default output so that the
> descriptions of -v and -q are meaningful.

I rebutted a).  I thought that b) was in reference to a, so no longer
relevant.  I somewhat agree with c), although I think it would be
preferable to remove --action altogether.  I agree with d).

> 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).

I don't understand.  --take-this resolves conflicts in favour of THIS.
 Are you saying the command does not make decisions because the user
specified the way that the conflict should be resolved?

>> 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.

We need --all because the default behaviour is safe.  Kind of ironic
that it engenders distrust.

> The duplication of --action vs. --take-this, --take-other, and
> (implicitly) "--mark-done" doesn't help either (TOOWTDI
> violation).

+1

>> 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.

OTOH, that behaviour was introduced in 2007, and it hasn't been an
issue 'till now, so perhaps most people are happy with it, and only
those who disagree are talking.

> (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).

In Bazaar, that will often cause recursive behaviour, because * will
select the subdirectory, and bzr usually recurses into specified
subdirectories.  (Much like ls -r)

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAlAUCxkACgkQ0F+nu1YWqI05PwCfY1Z4hX6ah58TokjRmHRBS08y
VYsAniGyltEXKstkcP5/q1JAPqjcpq3a
=yDmg
-----END PGP SIGNATURE-----