patchRe: [PATCH] bring description of git diff --cc up to date

Junio C Hamano wrote:

Yes, exactly - this is what I meant in saying "my proposed text does not suggest very strongly what --cc is intended to do". I haven't found any wording yet that both makes it clear what --cc actually does and follows a thought process suggesting why.

Just to make sure I understand, here is what I think --cc does:

  - In a two-parent merge, it is exactly as Linus has been
    describing it.  A hunk is interesting if and only if
    it shows changes from both parents.

  - In a many-parent merge, the criterion is more stringent.
    As in the two-parent merge case, the hunk must show no
    changes from at least one of the parents, meaning that
    one of several alternatives for that portion of code
    was chosen by the code integrator (without mixing and
    matching or adding additional changes); but further, there
    must have been only two alternatives for that portion of
    code to choose between.  If there were three distinct
    alternatives, no matter what the code integrator does, the
    hunk will show up (because that is so rare and deserves
    attention).

Is that correct?

Thanks for the reading matter. If it stimulates anyone reading into coming up with a better description, they should please let me know :)

Jonathan Nieder <jrnieder@uchicago.edu> writes:

The logic in the code does not have separate criteria for two-parent and Octopus cases. Actually Linus talks about "when you have two versions to choose from, and if the result matches one of them, then it is not interesting". In a two-parent merge, you cannot have three or more possible versions to choose from by definition, can you?

Junio C Hamano <gitster@pobox.com> writes:

To put it another way, I think what you wrote is correct, but two-parent case is just a degenerated case of a more general rule, that is:

    A hunk is not interesting if the person who merged had only two
    choices offered by the parents to pick from, and the merge result
    exactly matched one of the choices.

You can come up with examples that do not match the above criteria; they are all interesting.

For example, if all the parent of a tripus disagreed, the person had more than two choices to pick from, so no matter what the resolution is, the hunk is interesting.

On the other hand, if 4 parents in a dodecapus lack a line that all other 8 parents have (see the first example in [*1*]), then the choice for the person who merges these 12 parents is either to include or not include that line. If the line was included, it is not interesting. If the line was deleted (which is different from what happened in *1*), it is not interesting, either.

One thing to note is "have only two choices to pick from" does not have a direct connection to two-parent-ness. In a two-parent merge (di-pus?), by definition you cannot have more than two choices, but that is not any different from a Dodecapus that has only two groups of parents. Most octopus merges have only two groups of parents like the "merge from hell" does when we talk about individual paths (otherwise it would be very painful to resolve so it is not done in practice).

[Reference]

*1* http://article.gmane.org/gmane.comp.version-control.git/15487

Junio C Hamano wrote:

That is much better - thanks. (The description by Linus I was referring to was from <http://thread.gmane.org/gmane.comp.version-control.git/89415>: "So "--cc" only shows output if: the merge itself actually changed something from _all_ parents" - which is not too misleading since the two-parent case is the usual one.)

How about this, then?
--- %< ---
Subject: document diff --cc's long-ago-changed semantics

In February 2006 [1], the definition of "interesting hunk" for git's "compact combined diff" format changed, without any corresponding change in documentation. This patch brings the documentation up to date.

[1] commit bf1c32bdec8223785c779779d0a660a099f69a63
    combine-diff: update --cc "uninteresting hunks" logic
---
 Documentation/git-diff-tree.txt    |   12 +++++++-----
 Documentation/rev-list-options.txt |    9 +++++----
 2 files changed, 12 insertions(+), 9 deletions(-)

Jonathan Nieder <jrnieder@uchicago.edu> writes:

Hmm, I am not a native speaker, but the above makes me confused into thinking that even if there are 47 parent versions, it is Ok if I looked at only two versions and picked from one of them -- the description does not seem to make it clear that it is required that the other 45 agree with one of the two I looked at and picked from.

    ... if the contents in the parents had only two variants and the merge
    result picked one of them without modification.

would be succinct enough, perhaps?

If we want to further elaborate, we could say something like:

    In a two-parent merge, by definition, there can only be two variants
    to choose from.  Even in a merge with more than two parents, if some
    parents share the same content, and all the other parents share
    another, same content, there are only two variants to choose from.

but I think that is too verbose...

On Tue, 22 Jul 2008, Junio C Hamano wrote:

Here's another attempt. I grimace at the sound of it, but it might be more clear.

--- snipsnip ---
Subject: document diff --cc's long-ago-changed semantics

In February 2006 [1], the definition of "interesting hunk" for git's compact-combined diff format changed without a corresponding change in documentation. This patch brings the documentation up to date.

[1] commit bf1c32bdec8223785c779779d0a660a099f69a63
    combine-diff: update --cc "uninteresting hunks" logic

Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
---
 Documentation/git-diff-tree.txt    |   12 +++++++-----
 Documentation/rev-list-options.txt |    9 +++++----
 2 files changed, 12 insertions(+), 9 deletions(-)

Jonathan Nieder <jrnieder@uchicago.edu> writes:

Let's just do this.  I think it is clear enough.

 Documentation/git-diff-tree.txt    |   10 +++++-----
 Documentation/rev-list-options.txt |    6 +++---
 2 files changed, 8 insertions(+), 8 deletions(-)

Junio C Hamano wrote:

Works for me.  Thanks, and sorry I dragged this on so.