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.
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Thu Oct 27 14:21:50 2005