Diff --old --new: too many peg revision specifiers

We've got a nasty relic of a meaning of "-r" in "diff --old --new" syntax.

> $ svn diff --help
> diff (di): Display the differences between two revisions or paths.
> usage: 1. diff [-c M | -r N[:M]] [TARGET[@REV]...]
> 2. diff [-c M | -r N[:M]] --old=OLD-TGT[@OLDREV] [--new=NEW-TGT[@NEWREV]] \
> [PATH...]
> 3. diff OLD-URL[@OLDREV] NEW-URL[@NEWREV]
> [...]
> 2. [...]
> -r N makes OLDREV default to N,
> -r N:M makes OLDREV default to N and NEWREV default to M

In syntax (1), "@REV" is a peg and "-r N" is an operative revision. Fine.

In syntax (2), "@OLDREV" and "@NEWREV" are pegs, and "-r N[:M]" provides
default values for the pegs. I think that's horrible. It's inconsistent with
every other command. It's redundant: if both "-r" and "@" revisions are
specified, the code silently ignores the "-r" value.

Furthermore, the "-c" option is even sillier, because it is intended to specify
"the change" that occured in an object or in the repository, whereas in this
syntax it is being used to provide the two revision numbers in which to locate
two separate objects.

I would like to delete the "-c" and "-r" options from syntax 2. It's an
incompatible UI change, but I'd call it a bug fix. The help would be:

        2. diff --old=OLD-TGT[@OLDREV] [--new=NEW-TGT[@NEWREV]] \
                [PATH...]

This would be more in line with the corresponding forms of merge command:

usage: 1. merge sourceURL1[@N] sourceURL2[@M] [WCPATH]
        2. merge sourceWCPATH1@N sourceWCPATH2@M [WCPATH]
        3. merge [-c M | -r N:M] SOURCE[@REV] [WCPATH]

However, we have a duty to maintain compatibility with the older UI. In v1.0,
which was before it supported peg revs, the syntax was:

           diff [-r N[:M]] [--old OLD-TGT] [--new NEW-TGT] [PATH...]

"-r" provided what we now call the peg revs.

The peg-rev notation was added in r9707, round about v1.1, changing the help to:

        2. diff [-r N[:M]] --old=OLD-TGT[@OLDREV] [--new=NEW-TGT[@NEWREV]] \
                [PATH...]

That is when "-r" was made to provide "defaults" for the peg revs, in order to
maintain compatibility with the v1.0 UI syntax.

At the very least I will get rid of "-c" in syntax 2, because it is just adding
to the confusion and there is still time to stop it before it is released in v1.4.

I would also like to:

   * error or warn if both "-r" and an "@" are specified, because that was
never intended

   * deprecate "-r" by changing the help to say so

but those would both be incompatible UI changes. Would either of them be
desirable on balance?

In short, I'm trying to find a migration path from having this horrible meaning
of "-r" to eventually either not having "-r" or having it specify operative
revisions as it does in other commands and particularly in other forms of "svn
diff".

Does anyone see any better steps along that road?

- Julian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Tue Mar 14 01:31:07 2006