Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation

Sergey Organov <sorganov@gmail.com> writes:

I think the sentence reads better without the translated (q.v.) that confused Eric.

Good.

I suspect that many people do not get what "re-merge" in "against re-merge" really is. As "combined diff" and "dense combined diff" are not explained in the previous two entries either, and expect the readers to read the real description (which more or less matches what the original description for "-c" and "--cc" had, which is good), it would be better to say "Produce remerge-diff output for merge commits." here, too. It makes it consistent, and "for merge commits" makes it clear the "magic" does not apply to regular commits (which the above entries for "-c" and "--cc" do, which is very good).

This reads well.

In the longer term, "--diff-merge=first-parent" that is used without first-parent traversal should be discouraged and be deprecated, I think, but that is a separate story [*].

The original is already wrong so these are not problems this patch introduces, but

 - "configuration variable" is how we refer to these entities.
 - "which default value" -> "whose default value".

Yes, this is the same output as `-p`, as if parents other than the first parent of the merge commit did not exist.

This was inherited from the original elsewhere, but it makes it unnecessary confusing to say "full diff" here and in the next one.

    Show `--patch` output with respoect to the first parent for a
    merge commit, as if the other parents did not exist.

perhaps?

In the early days of Git before -c/--cc were invented, we explained this mode as "pairwise comparison", and the phrase "pairwise" still may be the best one to describe the behaviour here. In fact, we see in the updated description of combined below the exact phrase is used to refer to this oldest output format.

    Show the `--patch` output pairwise, together with the commit
    header, repeated for each parent for a merge commit.

or something, perhaps. I added "repeated" here to make the contrast with "simultaneously" stand out.

The original says "two-parent merge comimts are remerged" so it is not a failure of this patch, but the first verb "Remerge" sounds unnecessarily unfriendly to the readers.

	For a two-parent merge commit, a merge of these two commits
	is retried to create a temporary tree object, potentially
	containing files with conflict markers.  A `--patch` output
	then is shown between ...

would be easier to follow and more faithful to the original description added by db757e8b (show, log: provide a --remerge-diff capability, 2022-02-02).

Either way, it makes readers wonder what happens to merges with more than 2 parents (octopus merges). It is not a new problem and this topic should not attempt to fix it.

Looks very good otherwise.  Let me read on.

Thanks.

[Footnote]

* When a project allows fast-forward merges, something like this can
  happen (and Git was _designed_ to allow and even encourage it)

  - Linus pulls from Sergey and sees merge conflicts that are very
    messy.  Sergey is asked to resolve the conflict, as Linus knows
    Sergey understands the changes he is asking Linus to pull much
    better than Linus does.

  - Sergey does "git pull origin" that would give the same set of
    conflicts Linus saw, perhaps ours/theirs sides swapped, resolves
    the conflicts, and comits the merge result.  He may even add a
    few other improvements on top (or may not).  He tells Linus that
    his tree is ready to be pulled again.

  - Linus pulls from Sergey again.  This time it is fast-forward,
    without an extra merge commit that records the Linus's previous
    tip as the first parent and Sergey's work as the second parent.

  - Linus continues working from here.

  In such a workflow, merges are nothing more than "combining
  multiple histories together" and the first parenthood is NOT
  inherently special among parents at all.  The original "-m -p"
  (aka "pairwise diff") output reflects this world view and ensures
  that all parents are shown more or less as equals (yes, the first
  parent diff is shown first before the other parents, but you
  cannot avoid it when outputting to a single dimension medium).

  This world view was the only world view Git supported, until I
  added the "--first-parent" traversal in 0053e902 (git-log
  --first-parent: show only the first parent log, 2007-03-13).

  With the "--first-parent", with "--no-ff" option to "git merge", a
  different world view becomes possible.  A merge is not merely
  combining multiple histories, which are equals.  It is bringing
  work done on a side branch into the trunk.  To see the overview of
  the history, "git log --first-parent" would give the outline,
  which would be full of merges from side branches, each of which
  can be seen as summarizing the work done on the side branch that
  was merged, and it may occasionally have single-parent commits
  that are hotfixes or trivial clean-ups or project administrivia
  commits.  With "-p", "git log" would show the changes the work
  done on a side branch as a single unit for a merge, and individual
  commits if they are single-parent.  The life is good.

  It all breaks down if the "diff against the first parent" is done
  on a merge that is not bringing the work on a side branch in to
  the trunk.  The merge done in the second step Sergey did for Linus
  in the above example will have his work on the history leading to
  its first parent, and from the overall project's point of view,
  the second parent is the tip of the history of the trunk.  Showing
  first-parent diff for a merge that was *not* discovered via the
  first-parent traversal would show such a meaningless patch.  This
  is an illustration of the fallout from mixing two incompatible
  world views together, "--diff-merges=first-parent" wants to work
  in a world where the first-parent is special among parents, but
  traversal without "--first-parent" wants to treat all the branches
  equally.

  All the other <format>s accepted by the "--diff-merges=<format>"
  option are symmetrical and they work equally well when in a
  history of a project that considers the first-parenthood special
  (i.e. work on a side branch is brought into the trunk history) or
  in a history with merges whose parent order should not matter, so
  unlike "--diff-merges=first-parent", it makes sense to apply them
  with or without first-parent traversal.  It however is not true
  for the "--diff-merges=first-parent" variant, which is asymmetric.

  And that is why I think use of "--diff-merges=first-parent"
  without "--first-parent" traversal is a bad thing to teach users
  to use.