Re: [PATCH] Documentation: Simplify git-rev-parse's example

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 19, 2008, 19:33 UTC
Message-ID: <7v8wx1te20.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <485AAF82.3030209@freescale.com>

Jon Loeliger <jdl@freescale.com> writes:

Show 23 quoted lines

> Pieter de Bie wrote:
>> This example was overly complex and therefore confusing.
>> The commits have been renamed to start the oldest commit with "A"
>> and working up from there. Also, this removes some commits so the graph
>> is simpler. Finally the graph has been reversed in direction to make it
>> more like gitk.
>>
>> Signed-off-by: Pieter de Bie <pdebie@ai.rug.nl>
>> ---
>>
>> This was created after some discussion in #git about how this was confusing.
>> The consesus was that this example is better.
>
> How is this a vast improvement?
>
> I could see that inverting it top-to-bottom would
> be more consistent with gitk or show-branch output.
> Your example doesn't have a 3-parent commit, though,
> and it isn't _that_ much simpler otherwise...
>
> So this is really better _how_?
>
> Oh, right, of course.  It removes my name.  Got it. :-)

I agree that the patch should have just flipped the tree upside down without changing the shape of the history the section talks about.

Yet another improvement would have been turning it sideways, not upside down, because that is how we typically write history in our documentation (time flows from left to right -- see e.g. git-rebase.txt).

I happen to think the last point you raise is an improvement. It will quickly become unreadble after a while if we credit individual authors for every paragraph in-text, and it always bothered me to see somebody's name (don't get me wrong -- this is not because it is your name nor because it is not my name, but because it _is_ a name), there but I wasn't bold enough to remove it without discussion.