On Thu, 27 Oct 2005, Julian Foad wrote:
> Some thoughts on the introduction of the "--change" ("-c") option.
>
> This is important. It is not just a little syntax tweak. It gives us a way
> to express a concept directly that has hitherto only been implied. We need
> to be comfortable with this.
>
> This finally enables us to resolve some of the confusion between "revision"
> meaning "a snapshot or version of the managed tree" (as in "svn cat -r10")
> and "revision" meaning "the change from one version to another" (as in "svn
> log -r10"). We can keep "revision" and the option "-r" for the former, as
> that is what it usually means, but express the latter concept with this new
> option "-c"/"--change".
>
> Here is how changes and versions fit together through time (ASCII art):
>
> Time Changes Versions
>
> | ----------------------------+
> v / |
> | +---------------------------- r0: The empty tree. |
> | | \ |
> v | Commit 1: time, author, ----------------------------+
> | | log message / |
> | +---------------------------- r1: The first version. |
> v | \ |
> | | Commit 2: time, author, ----------------------------+
> | | log message / |
> v +---------------------------- r2: The second version. |
> | \ |
> v ----------------------------+
>
> I looked through the "svn" subcommands. Most of those that take "--revision"
> conceptually operate on a version. These few are the exceptions:
>
> * diff, merge: These can usefully be enhanced to accept a single "change" as
> a special case of their general operation on the difference between one
> revision and another.
>
> * log: This conceptually reports on changes, not versions. "log --change 10"
> would be a conceptually better syntax to replace the current meaning of "log
> -r 10" because it only tells you about the change that resulted in version
> 10, nothing about version 10 of the tree itself. "log -c 10,20" would make
> perfect sense as a way to report on a few selected changes. The current "log
> -r 10:20", on the other hand, is an anomaly. It presently reports on the
> _changes_ numbered from 10 to 20 inclusive, not on the changes made between
> revisions 10 and 20. That is, it doesn't report on the same set of changes
> that "diff -r 10:20" does. I have always regarded this as a design bug, but
> we have not yet had a convenient way to resolve it. Now we have. We should
> introduce "log -c 10" to replace "log -r 10", and deprecate the latter. We
> should deprecate the inconsistent "log -r 10:20" syntax, and/or "fix" it to
> mean the changes between r10 and r20. We could introduce "log -c 10:20" to
> mean "log of all of the changes numbered 10 to 20 inclusive (exactly what
> "log -r 10:20" does now), but I don't think that's necessarily useful; but
> that's getting too detailed for now.
>
> * propget, propset, etc.: When used with "--revprop", these operate on a
> change, not on a version. This may sound radical, but it would make sense
> for "propset --change 10" to replace "propset --revprop -r 10".
>
> I'm not saying we have to change these things all at once, just that we
> should discuss whether the concept makes sense and whether we want to move in
> this direction.
>
>
> We should try to write the patch for the book to explain this feature.
> Firstly because it's important. Secondly because writing documentation for a
> feature is a _very_ good way to determine whether it is well designed and
> conceptually clear. If the documentation has to keep referring to special
> cases, or has difficulty describing what it really means, then it shows us
> there's a problem.
>
Thanks,
This is the best description of change, revision, and version (the
drawing was great) that I've seen yet. It makes these concepts crystal
clear (to me) and disambiguates the concepts in my mind.
If this could be documented in the subversion book in the basic sections,
maybe along with the already existing great "sequence of trees" image then
I think it would greatly help newcomers come up to speed on these
concepts.
--
David Wayne Summers "Linux: Because reboots are for hardware upgrades!"
david_at_summersoft.fay.ar.us PGP Key: http://summersoft.fay.ar.us/~david/pgp.txt
PGP Key fingerprint = 0B44 B118 85CC F4EC 7021 1ED4 1516 5B78 E320 2001
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Thu Oct 27 16:04:00 2005