Issue 2015, diff summarize solution?

[Julian Foad <ju...@btopenworld.com>]

Martin Hauner wrote:
> i created a partial patch for diff summarize, Issue 2015.

Thanks for the patch, but before we think about the code let's discuss the 
requirements.  This is the first I've heard of it.

Quoting from http://subversion.tigris.org/issues/show_bug.cgi?id=2015
> A "-s" ("--summarize") option should be added to the "svn diff"

Well, the short option name "-s" is perhaps not appropriate because this option 
is specific to one svn subcommand.  "-q/--quiet" might be appropriate if it was 
going to behave like a cut-down version of "svn diff", but it seems that it is 
not going to do so.  So probably just a long option "--summarize".

> capability.  This will reduce the output to a single line for each file
> or directory that has changed between two URL's.  It should also work
> for two revisions and a single URL.  For consistency, I imagine this
> would look similar to "svn status", but instead of operating on a
> working copy, it would operate on two revisions in the repository.

OK, I can see this being useful.  The extreme approaches are to make the output 
as much as possible like "svn diff" or "svn status" or "cvs diff -s"; in 
practice it will probably have something in common with each of these.

"svn status" is already showing a summary of the difference between one 
repository state and another (uncommitted) state.  It would initially seem that 
the exact same output format could apply to a diff between two states which are 
each independently committed or uncommitted, just without some of the 
possibilities that exist in a WC.

> Coupled with this should be "-q" ("--quiet") and "-v" ("--verbose")
> options to display additional information.  Verbose output with "-s"
> should still only display a single line per file.

You don't say what "-q" should do.  If it just means "not verbose" then there's 
no need for it.

> I think the following information would be helpful to include in the output:

In the following I call the first target of "diff" its "left" target, and the 
second target its "right".  Often a diff is invoked with an old target for its 
"left" argument and a newer version of the same thing for its "right" argument, 
but not by any means always.

> * Whether the item is a file, directory, (or anything else?)

Certainly that would be nice, but I note that neither "svn diff" nor "svn 
status" currently make this distinction.

> * Whether the change was a content or property change

Yes (either, both, or neither).

> * What was the revision prior to any changes
> * What was the revision after all changes

 From the examples I see that you mean the revision in which the item had last 
been changed at the versions identified by LEFT and RIGHT respectively.

Hmm.  I don't particularly object to having this information, but it doesn't 
feel to me like a logical part of the summary of the difference.

<a while later>  I've now gone and read the discussion on the users list, where 
it is pointed out that CVS diff has such a summarise facility, and these 
revision numbers are the main information that it gives.  So, OK, we probably 
want to give these.

> * Who committed the last change

What, for LEFT or RIGHT or both?  I assume you mean for RIGHT only, on the 
assumption that that is often the newer version, with the possibility that that 
will have been the only change made to the item.  That information doesn't seem 
a good fit for this feature.  That information can be got from "svn list 
--verbose RIGHT".


> So, how would this look?  Roughly following the "svn status" syntax,
> here is a starting point:
> First column says if the item was added, deleted, or otherwise changed
> Second column determines if there were property changes

So far so good.

> Third column says if the item is a directory, or otherwise not a file

We have no precedent for that, though it's not necessarily bad.

> Remaining fields are variable width and delimited by spaces:
> (with -v) Last revision number prior to change
> (with -v) Last changed revision number
> (with -v) Author of last changed revision

If we have each of these, we should probably have it in exactly the same format 
as "svn status".

> Path, relative to the given URLs.

That's good if LEFT and RIGHT are directories, but what if they point directly 
to a file?

> 
> $ svn diff -s http://repos/tags/rel1 http://repos/tags/rel2
> A   /path/to/file1
> MM  /path/to/file2
> A D /path/to/a_new_dir
> D   /path/to/file3
> 
> $ svn diff -s -v http://repos/tags/rel1 http://repos/tags/rel2
> A      120    145    bob    /path/to/file1
> MM     100    111    joe    /path/to/file2
> A D    120    120    jane   /path/to/a_new_dir
>        80     80     bob    /path/to/unchanged_file
> D      101    130    bob    /path/to/file3
> 
> Notes:
> The -v option should list ALL files in either tag.

So it alters both the information that is shown for each item and the set of 
items that are displayed, like it does in "svn status"?  I don't like that 
much, though since we have it in "status" I might tolerate it.

Possibly we won't need a brief form of the information shown for a particular 
item ... I don't know.

> The extra -v information columns are padded with spaces in the same manner as
> "svn status -v".

OK.

> "last revision prior to change" for newly added files should be the
> revision in which it was added.  One should be able to checkout the
> first listed revision of all the files (that don't have an "A" in the
> first column) and get rel1.

That's self-contradictory if you mean the LEFT revision.  The LEFT revision 
number field should specify a revision BEFORE the file was added, such as zero 
or (the revision number of rel1), or be blank.

>  Similarly, "last changed revision"
> for deleted files should be the revision in which it was deleted.

That sounds reasonable, though not the only possibility.

> Checking out the 2nd listed revision of all files (without a "D" in the
> first column) should be equivalent to checking out rel2.

Yes; this should work even if one tries to include those with a "D" in the 
first column.

Well, those are my comments on what is written in the issue.  I haven't yet 
thought about it from the direction of trying to summarise "svn diff" or 
generalise "svn status" myself.

- Julian



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Issue 2015, diff summarize solution?

[Julian Foad <ju...@btopenworld.com>]

kfogel@collab.net wrote:
> Julian Foad <ju...@btopenworld.com> writes:
>>Well, the short option name "-s" is perhaps not appropriate because
>>this option is specific to one svn subcommand.  "-q/--quiet" might be
>>appropriate if it was going to behave like a cut-down version of "svn
>>diff", but it seems that it is not going to do so.  So probably just a
>>long option "--summarize".
> 
> Actually, why not '-q'?

Because both the normal diff output and the new diff summary output might want 
to have "quieter" versions - such as, for the former, not diffing added/deleted 
files (OK, so there may be a separate option for that, but you get the idea).

If the new summary output was really just a "quieter" version of the normal 
diff output then it would be fine, but what's being proposed is completely 
different both in format and in content.

- Julian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Issue 2015, diff summarize solution?

[kf...@collab.net]

Julian Foad <ju...@btopenworld.com> writes:
> Well, the short option name "-s" is perhaps not appropriate because
> this option is specific to one svn subcommand.  "-q/--quiet" might be
> appropriate if it was going to behave like a cut-down version of "svn
> diff", but it seems that it is not going to do so.  So probably just a
> long option "--summarize".

Actually, why not '-q'?  I like the feature, I just don't see that we
need a new option to control it.

By the way, it's fine to combine -q and -v.  "svn status" already does.

-Karl

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Issue 2015, diff summarize solution?

[Julian Foad <ju...@btopenworld.com>]

Martin Hauner wrote:
> Ok, i will write a proposal. It will be from my point of view (gui) (mostly)
> ignoring issue #2015 as a first step to avoid a mixture.

That would be great.  You can concentrate on designing an API, and ignore the 
command-line interface completely if you like.

> We can then see where both features overlap or not.

Absolutely.

- Julian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Issue 2015, diff summarize solution?

[Martin Hauner <ma...@gmx.net>]

Julian Foad wrote:
> Martin Hauner wrote:
>> My motivation behind it is to display a list of changed items in a gui
>> client when I like to see the difference between branches/tags. I can
>> then select an item from the list to run a "real" diff on it. So the
>> summarize is something like a diff preview.
> 
> 
> OK.  For GUIs we should think mainly about the API.  So, what is the 
> best that a GUI can do in terms of achieving this goal using the 
> existing API?  That would be interesting to know before designing an 
> extended API.

Not much. Stefan said that he parses the diff output in tsvn to get this
info. I thought about that too but i don't like to implement it that way.
I don't know of another solution.

>> A gui client needs the revisions so it can run diff on that file from
>> the preview if i like to see a detailed diff of the changed file.
> 
> 
> It doesn't need the revision numbers to be reported back to it, because 
> it can just use the same URLs and/or revision numbers that were supplied 
> to the "diff"
> command in the first place.

Correct. For the gui case the revisions would be sugar information.
Not for #2015 (diff summarize) which likes to see them.

Note that I am more interested in the gui case and was pointed to #2015
as a solution.

> It looks like you would like some help with this design stage (and the 
> coding) from others on the list, and that's fine, though I would also 
> like to encourage you to have a go at researching the features that we 
> want it to be somewhat compatible with (cvs diff, svn diff, svn status) 
> and designing and writing up a proposal.  A good way to present it would 
> be as a patch to the Subversion book and/or on-line help, stating 
> exactly what the feature does and what its output means.

Ok, i will write a proposal. It will be from my point of view (gui) (mostly)
ignoring issue #2015 as a first step to avoid a mixture. We can then see
where both features overlap or not.

-- 
Martin

Subcommander, http://subcommander.tigris.org
a crossplatform Win32/Unix/MacOSX svn gui client & diff/merge tool.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Issue 2015, diff summarize solution?

[Julian Foad <ju...@btopenworld.com>]

Martin Hauner wrote:
> Julian Foad wrote:
>> Martin Hauner wrote:
>>> i created a partial patch for diff summarize, Issue 2015.
>>
>> Thanks for the patch, but before we think about the code let's discuss 
>> the requirements.  This is the first I've heard of it.
> 
> There was thread a few days ago:
> 
> "show diffs in a gui client, how to get a list of changed files?"

OK, thanks for pointing that out, but I don't think the requirements are 
discussed (functionality, output format and invocation syntax).

> My motivation behind it is to display a list of changed items in a gui
> client when I like to see the difference between branches/tags. I can
> then select an item from the list to run a "real" diff on it. So the
> summarize is something like a diff preview.

OK.  For GUIs we should think mainly about the API.  So, what is the best that 
a GUI can do in terms of achieving this goal using the existing API?  That 
would be interesting to know before designing an extended API.

> A gui client would like to know if it is a file or folder because it
> doesn't make sense to run a visual diff on a folder.

Yes.

> A gui client needs the revisions so it can run diff on that file from
> the preview if i like to see a detailed diff of the changed file.

It doesn't need the revision numbers to be reported back to it, because it can 
just use the same URLs and/or revision numbers that were supplied to the "diff"
command in the first place.

>>> Path, relative to the given URLs.
>>
>> That's good if LEFT and RIGHT are directories, but what if they point 
>> directly to a file?
> 
> For diffs between branches/tags the filename is usually the same in
> both urls. In case of a rename one could simply use the new name or
> print both:  /path/newfilename (/path/oldfilename)

Those are indeed possibilities but I'm asking you to think about the various 
ways in which the command could be used, decide what rules would be best, and 
then propose your specification, saying something like, "The path should be 
shown relative to <...> when it is <...> and otherwise it should be <...>, 
because that makes the output unambiguous in all of these cases: <...>.  The 
only other possible cases are <...> and they don't matter because <...>."

It looks like you would like some help with this design stage (and the coding) 
from others on the list, and that's fine, though I would also like to encourage 
you to have a go at researching the features that we want it to be somewhat 
compatible with (cvs diff, svn diff, svn status) and designing and writing up a 
proposal.  A good way to present it would be as a patch to the Subversion book 
and/or on-line help, stating exactly what the feature does and what its output 
means.

- Julian


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Issue 2015, diff summarize solution?

[Martin Hauner <ha...@web.de>]

Julian Foad wrote:
> Martin Hauner wrote:
> 
>> i created a partial patch for diff summarize, Issue 2015.
> 
> 
> Thanks for the patch, but before we think about the code let's discuss 
> the requirements.  This is the first I've heard of it.

There was thread a few days ago:

"show diffs in a gui client, how to get a list of changed files?"

My motivation behind it is to display a list of changed items in a gui
client when I like to see the difference between branches/tags. I can
then select an item from the list to run a "real" diff on it. So the
summarize is something like a diff preview.

Then there came up the already filed issue #2015 and Ben gave advise
where to start in the code.

> Quoting from http://subversion.tigris.org/issues/show_bug.cgi?id=2015
> [..]
>> I think the following information would be helpful to include in the 
>> output:
 > [..]
>> * Whether the item is a file, directory, (or anything else?)
> 
> 
> Certainly that would be nice, but I note that neither "svn diff" nor 
> "svn status" currently make this distinction.

A gui client would like to know if it is a file or folder because it
doesn't make sense to run a visual diff on a folder.


>> * What was the revision prior to any changes
>> * What was the revision after all changes
> 
>  From the examples I see that you mean the revision in which the item 
> had last been changed at the versions identified by LEFT and RIGHT 
> respectively.
 > [..]
> <a while later>  I've now gone and read the discussion on the users 
> list, where it is pointed out that CVS diff has such a summarise 
> facility, and these revision numbers are the main information that it 
> gives.  So, OK, we probably want to give these.

A gui client needs the revisions so it can run diff on that file from
the preview if i like to see a detailed diff of the changed file.

>> * Who committed the last change
> 
> What, for LEFT or RIGHT or both?  I assume you mean for RIGHT only, on 
> the assumption that that is often the newer version, with the 
> possibility that that will have been the only change made to the item.  
> That information doesn't seem a good fit for this feature.  That 
> information can be got from "svn list --verbose RIGHT".

We can drop that, it isn't too interesting from my gui client point of
view.

>> So, how would this look?  Roughly following the "svn status" syntax,
>> here is a starting point:
>> First column says if the item was added, deleted, or otherwise changed
>> Second column determines if there were property changes
> 
> 
> So far so good.
> 
>> Third column says if the item is a directory, or otherwise not a file
> 
> 
> We have no precedent for that, though it's not necessarily bad.
> 
>> Remaining fields are variable width and delimited by spaces:
>> (with -v) Last revision number prior to change
>> (with -v) Last changed revision number
>> (with -v) Author of last changed revision
> 
> 
> If we have each of these, we should probably have it in exactly the same 
> format as "svn status".
> 
>> Path, relative to the given URLs.
> 
> 
> That's good if LEFT and RIGHT are directories, but what if they point 
> directly to a file?

For diffs between branches/tags the filename is usually the same in
both urls. In case of a rename one could simply use the new name or
print both:  /path/newfilename (/path/oldfilename)


-- 
Martin

Subcommander, http://subcommander.tigris.org
a crossplatform Win32/Unix/MacOSX svn gui client & diff/merge tool.


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org