Re: questions / suggestions about history simplification

[Junio C Hamano <gitster@pobox.com>]

Adam Spiers <git@adamspiers.org> writes:

> 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.