Re: [PATCH] rebase docs: fix incorrect format of the section Behavioral Differences

> On Tue, Dec 4, 2018 at 7:54 PM Junio C Hamano <gitster@pobox.com> wrote:
>>
>> Elijah Newren <newren@gmail.com> writes:
>>
>>> Gah, when I was rebasing on your patch I adopted your sentence rewrite
>>> but forgot to remove the "sometimes".  Thanks for catching; correction:
>>
>>>
>>> -- 8< --
>>> Subject: [PATCH v2] git-rebase.txt: update note about directory rename
>>>   detection and am
>>>
>>> In commit 6aba117d5cf7 ("am: avoid directory rename detection when
>>> calling recursive merge machinery", 2018-08-29), the git-rebase manpage
>>> probably should have also been updated to note the stronger
>>> incompatibility between git-am and directory rename detection.  Update
>>> it now.
>>>
>>> Signed-off-by: Elijah Newren <newren@gmail.com>
>>> ---
>>>   Documentation/git-rebase.txt | 8 ++++++--
>>>   1 file changed, 6 insertions(+), 2 deletions(-)
>>>
>>> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
>>> index 41631df6e4..ef76cccf3f 100644
>>> --- a/Documentation/git-rebase.txt
>>> +++ b/Documentation/git-rebase.txt
>>> @@ -569,8 +569,12 @@ it to keep commits that started empty.
>>>   Directory rename detection
>>>   ~~~~~~~~~~~~~~~~~~~~~~~~~~
>>>
>>> -The merge and interactive backends work fine with
>>> -directory rename detection.  The am backend sometimes does not.
>>> +The merge and interactive backends work fine with directory rename
>>
>> I am not sure "work fine" a fair and correct label, as rename is
>> always heuristic.
>>
>>      The "directory rename detection" heuristic in "merge" and the
>>      "interactive" backends can take what happened to paths in the
>>      same directory into account when deciding if a disappeared path
>>      was "renamed" and to which other path.  The heuristic produces
>>      incorrect result when the information given is only about
>>      changed paths, which is why it is disabled when using the "am"
>>      backend.
>>
>> perhaps.
> 
> The general idea sounds good.  Does adding a few more details help
> with understanding, or is it more of an information overload?  I'm
> thinking of something like:
> 
>       The "directory rename detection" heuristic in the "merge" and
>       "interactive" backends can take what happened to paths in the
>       same directory on the other side of history into account when
>       deciding whether a new path in that directory should instead be
>       moved elsewhere.  The heuristic produces incorrect results when
>       the only information available is about files which were changed
>       on the side of history being rebased, which is why directory
>       rename detection is disabled when using the "am" backend.