On Tue, Jul 3, 2018 at 4:26 AM Johannes Schindelin via GitGitGadget
<gitgitgadget@xxxxxxxxx> wrote:
> +'git range-diff' [--color=[<when>]] [--no-color] [<diff-options>]
> + [--dual-color] [--creation-factor=<factor>]
> + ( <range1> <range2> | <rev1>...<rev2> | <base> <rev1> <rev2> )
> +
> +DESCRIPTION
> +-----------
> +
> +This command shows the differences between two versions of a patch
> +series, or more generally, two commit ranges (ignoring merges).
Does it completely ignore merges or does it die("not supported"), how is the
user expected to cope with the accidental merge in the given range?
> +To that end, it first finds pairs of commits from both commit ranges
> +that correspond with each other. Two commits are said to correspond when
> +the diff between their patches (i.e. the author information, the commit
> +message and the commit diff) is reasonably small compared to the
> +patches' size. See ``Algorithm` below for details.
> +
> +Finally, the list of matching commits is shown in the order of the
> +second commit range, with unmatched commits being inserted just after
> +all of their ancestors have been shown.
> +
> +
> +OPTIONS
> +-------
> +--dual-color::
> + When the commit diffs differ, recreate the original diffs'
> + coloring, and add outer -/+ diff markers with the *background*
> + being red/green to make it easier to see e.g. when there was a
> + change in what exact lines were added.
I presume this is a boolean option, and can be turned off with
--no-dual-color, but not with --dual-color=no. Would it be worth to
give the --no-option here as well.
The more pressing question I had when reading this, is whether this
is the default.
> +--creation-factor=<percent>::
> + Set the creation/deletion cost fudge factor to `<percent>`.
> + Defaults to 60. Try a larger value if `git range-diff` erroneously
> + considers a large change a total rewrite (deletion of one commit
> + and addition of another), and a smaller one in the reverse case.
> + See the ``Algorithm`` section below for an explanation why this is
> + needed.
> +
> +<range1> <range2>::
> + Compare the commits specified by the two ranges, where
> + `<range1>` is considered an older version of `<range2>`.
Is it really older? How does that help the user?
I think this comes from the notion of e.g. patch 4 ("range-diff: improve the
order of the shown commits "), that assume the user wants the range-diff
to be expressed with range2 as its "base range".
> +<rev1>...<rev2>::
> + Equivalent to passing `<rev2>..<rev1>` and `<rev1>..<rev2>`.
That is cool.
> +Algorithm
> +---------
> +
> +The general idea is this: we generate a cost matrix between the commits
> +in both commit ranges, then solve the least-cost assignment.
Can you say more about the generation of the cost matrix?
I assume that it counts the number of lines added/deleted to make
one patch into the other patch.
If that assumption was correct, an edit of a commit message adding one
line is just as costly as adding one line in the diff.
Further I would assume that the context lines are ignored?
I think this is worth spelling out.
Another spot to look at is further metadata, such as author and author-date,
which are kept the same in a rebase workflow.
Maybe worth noting that this algorithm doesn't pay special attention to these,
but a change in them would be strong signal that the two patches compared are
not the same?
I like the example below, thanks!
Stefan
