On Wed, Nov 07, 2007 at 11:16:06PM +0100, Benoit Sigoure wrote:
Show 61 quoted lines
> 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...