[Merge] lp:~amanica/bzr/log_returns_too_much into lp:bzr

[Matthew D. Fuller]

On Fri, Jul 10, 2009 at 03:32:48PM +1000 I heard the voice of
Robert Collins, and lo! it spake thus:
> 
> Citation needed!
> 
> log -v shows status between revisions; I think its entirely reasonable
> to see the same the same thing in log and diff. I get asked about this
> all the time over beer by friends and colleagues.

Well, Maritza roughly walked over much of it.  I'll just try being
more verbose; it's what I'm good at.  It kinda comes back to the
changeset/snapshot thing, really.

log and diff are fundamentally completely different requests; log is
asking for information about a revision; it's primarily a unitary
operation.  It's trivially extensible to multiple revisions by simply
iterably doing its thing on each.  diff isn't; it's necessarily a
comparison of 2 (and only 2[0]) snapshots.

Asking a question like "bzr diff -rX" is fundamentally nonsensical[1];
you can't diff a revision.  You can only diff a revision AGAINST
something else.  Asking "bzr log -rX" however is perfectly
well-defined; you're asking for the log information attached to rev X.
Asking "bzr log -r3,9,15" (assuming the syntax existed) would be
totally reasonable; doing the same with diff would be just as
meaningless as asking for a single rev.  Now, certainly, "log -v"
blurs things by showing diffish information, but that's ancillary to
what is primarily happening.


Explanations like "diff uses a half-open range, log uses a closed
range" are a terrible thing.  Like a number of other attempted
explanations, it gives the impression of special casing[2], instead of
just explaining why it's COMPLETELY consistent and naturally
emergent.

"diff -rX..Y" means "show the difference starting from the state of
revision X running to the state of revision Y".  It's Obvious(tm) that
that doesn't and can't include the difference from the state of
revision (X-1) to revision X, any more than it includes the difference
between Y and (Y+1).  "log -rX..Y" means "show the log information
starting from revision X running to revision Y".  It's Obvious(tm)
that that does include the log of revision X, just as it includes the
log of Y.

These aren't special cases where one command arbitrarily treats
something differently than another.  They're different things
happening as a direct result of asking for entirely different
operations.



[0] Yes, there are tools for multi-way diff showing, and some
    non--non-interactive-CLI ones may even be practical, but `bzr diff`
    ain't them.

[1] That it does something presumably-useful in bzr is a direct result
    of a decision that since the actual request is impossible and
    meaningless, the syntax can be interpreted to mean something else.

[2] This is a recurrent problem.  Explanations of things like the
    behavior of 'pull' in a checkout vs. in a branch keep falling into
    the trap of trying to explain the differences as special cases,
    rather than the result of what pull _does_ [update a branch]
    applied to the situation you're in [where your branch is at the
    moment relative to $CWD].  This is a monumental disservice.



-- 
Matthew Fuller     (MF4839)   |  fullermd at over-yonder.net
Systems/Network Administrator |  http://www.over-yonder.net/~fullermd/
           On the Internet, nobody can hear you scream.