Re: [PATCH v2] user-manual: add advanced topic "bisecting merges"

["J. Bruce Fields" <bfields@fieldses.org>]

On Wed, Nov 07, 2007 at 11:16:06PM +0100, Benoit Sigoure wrote:
> Hi Steffen,
>
> On Nov 7, 2007, at 10:50 PM, Steffen Prohaska wrote:
>
>> This commits adds a discussion of the challenge of bisecting
>> merge commits to the user manual. The text is slightly
>> adapted from a mail by Junio C Hamano <gitster@pobox.com>
>> to the mailing list
>> <http://marc.info/?l=git&m=119403257315527&w=2>.
>>
>> The discussion is added to "Exploring git history" in a
>> sub-section titled "Advanced topics". The discussion requires
>> detailed knowledge about git. It is assumed that the reader will
>> skip advanced topics on first reading. At least the text suggest
>> to do so.
>>
>> Signed-off-by: Steffen Prohaska <prohaska@zib.de>
>> ---
>>  Documentation/user-manual.txt |   89 
>> +++++++++++++++++++++++++++++++++++++++++
>>  1 files changed, 89 insertions(+), 0 deletions(-)
>>
>> Some minor errors were fixed. Thanks to <Ralf.Wildenhues@gmx.de>.
>>
>> I kept the naming of the commits. Benoit Sigoure suggested to choose
>> a different naming which he claims would be easier to remember.
>> I'm not convinced. The current naming starts with X, Y, Z on the left
>> and names the remaining commits on the right with A, B, C, D. This
>> is simple and give sufficient orientation.
>
> I still disagree but...  fair enough ;)
> You end up comparing [ABCD] with [XYZ] which (to me) is hard to follow 
> because it's like you were comparing two different kind of entities.  I 
> tend to think more in term of branch (e.g. what's happened to the upper 
> branch and what's happened to the lower branch, rather than think in terms 
> of "before a point in time" and "after that point in time").  Because of 
> that, I constantly need to look back at the scheme to find out what is `A', 
> what is `Z' etc.
>
> Some more comments below.  Sorry for not spotting these earlier.
>
>>
>> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
>> index d99adc6..d0e738e 100644
>> --- a/Documentation/user-manual.txt
>> +++ b/Documentation/user-manual.txt
>> @@ -934,6 +934,95 @@ Figuring out why this works is left as an exercise to 
>> the (advanced)
>>  student.  The gitlink:git-log[1], gitlink:git-diff-tree[1], and
>>  gitlink:git-hash-object[1] man pages may prove helpful.
>>
>> +[[history-advanced-topics]]
>> +Advanced topics
>> +---------------
>> +This section covers advanced topics that typically require more
>> +knowledge about git than the manual presented to this point.
>> +
>> +You may want to skip the section at first reading, and come back
>
> I think the correct wording here is "on first reading".  If a native 
> English speaker could confirm this...

Confirmed....

--b.