Re: questions / suggestions about history simplification

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 19, 2013, 20:37 UTC
Message-ID: <xmqqsitoefvi.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20131219190333.GE23496@pacific.linksys.moosehall>

Adam Spiers <git@adamspiers.org> writes:

Show 8 quoted lines

> On Thu, Dec 19, 2013 at 06:36:45PM +0000, Adam Spiers wrote:
>> I wanted to be able to experiment with the TREESAME example given in
>> the git-log(1) man page, so I built this script which recreates it:
>
> [snipped]
>
>> Would it be worth including this in (say) contrib/, and then referring
>> to it from the man page, in case anyone else feels a similar urge?

I doubt it. 75% of the work for such a person to understand the behaviour from such an example is to understand what kind of history the example is building. As you noticed, we do have existing tests to build "interesting" sample histories, but the fact that you did not bother with them and instead rolled your own should tell us something ;-) The next person is unlikely to read your sample in contrib/ but will roll his own, which is probably more efficient way than learning from a series of commands.

What we _could_ do instead may be to better annotate sample histories in the existing tests. Some of them (e.g. 6004, 6007) do have topology illustrations with what paths are changed at each node in the graph, but many lack such a visual aid to help readers understand what is going on at a glance.