Re: questions / suggestions about history simplification

From: Adam Spiers <git@adamspiers.org>
Date: Dec 19, 2013, 20:58 UTC
Message-ID: <20131219205858.GJ23496@pacific.linksys.moosehall>
In-Reply-To: <xmqqsitoefvi.fsf@gitster.dls.corp.google.com>

On Thu, Dec 19, 2013 at 12:37:53PM -0800, Junio C Hamano wrote:

Show 14 quoted lines

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

Agreed. And that's precisely why I wanted a real repository manifesting the given example: being able to view it in gitk makes that a lot easier to understand, for obvious reasons.

> 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 ;-)

Well I didn't roll my own; I just copied the example from the man page. So it only tells you that I was spending a fair amount of effort trying to understand the man page ;-) A user should not have to read the test suite to understand how the thing works - that's only for developers (conveniently ignoring for the sake of this argument that I am occasionally a git developer too ;-)

> The next person is unlikely to read your sample in
> contrib/ but will roll his own,

Not if the man page says "if you wish to experiment with these options yourself, you can easily recreate the repository in this example by running the script contrib/foo bundled in the source distribution".

> which is probably more efficient way
> than learning from a series of commands.

The goal of sharing the series of commands is not to educate users through reading them, but simply to save them the time they would have to spend manually recreating the example scenario given in the man page. After all, the useful information is not how to set up a repository reflecting the scenario, but rather, how the various git-log options affect behaviour when run on that repository.

Show 5 quoted lines

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

Again, this has the flaw of requiring non-developer users to read the test suite. On most distributions, the test suite code isn't even installed, so this means they would have to accurately recreate the source from which their installed binary packages were built. Surely that is considerably more effort than most users should reasonably be expected to spend. In contrast, it would be trivial to extend standard distro packages to include a file e.g.

  /usr/share/git-core/examples/git-log-history-simplification.sh