On Mon, Nov 13, 2017 at 1:06 PM, Stefan Beller [off-list ref] wrote:

On Fri, Nov 10, 2017 at 11:05 AM, Elijah Newren [off-list ref] wrote:

quoted

+       /*
+        * Because I keep forgetting every few years what src_entry and
+        * dst_entry are and have to walk through a debugger and puzzle
+        * through it to remind myself...

This repeats the commit message; and doesn't help me understanding the
{src/dst}_entry. (Maybe drop the first part here?) I'll read on.

Yep, I'll toss it.

quoted

+        *
+        * If 'before' is renamed to 'after' then src_entry will contain
+        * the versions of 'before' from the merge_base, HEAD, and MERGE in
+        * stages 1, 2, and 3; dst_entry will contain the versions of
+        * 'after' from the merge_base, HEAD, and MERGE in stages 1, 2, and
+        * 3.

So src == before, dst = after; no trickery with the stages (the same
stage number
before and after; only the order needs to be conveyed:
base, HEAD (ours?), MERGE (theirs?)

I can understand that, so I wonder if we can phrase it to mention (base,
HEAD, MERGE) just once.

Perhaps:

  If 'before' is renamed to 'after' then src_entry will contain
  the versions of 'before' from the merge_base, HEAD, and MERGE in
  stages 1, 2, and 3; and dst_entry will contain the respective versions of
  'after' in corresponding locations.  Thus, we have a total of six modes
  and oids, though some will be null.  (Stage 0 is ignored; we're interested
  in handling conflicts.)

?