From: J. Bruce Fields Date: Wed, 07 Nov 2007 22:26:49 GMT Subject: Re: [PATCH v2] user-manual: add advanced topic "bisecting merges" Message-ID: <20071107222649.GL29728@fieldses.org> In-Reply-To: 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 >> to the mailing list >> . >> >> 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 >> --- >> Documentation/user-manual.txt | 89 >> +++++++++++++++++++++++++++++++++++++++++ >> 1 files changed, 89 insertions(+), 0 deletions(-) >> >> Some minor errors were fixed. Thanks to . >> >> 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.