Re: questions / suggestions about history simplification

From: Adam Spiers <git@adamspiers.org>
Date: Dec 22, 2013, 13:41 UTC
Message-ID: <20131222134156.GM23496@pacific.linksys.moosehall>
In-Reply-To: <7vr495jsf8.fsf@alter.siamese.dyndns.org>

On Sat, Dec 21, 2013 at 10:44:43PM -0800, Junio C Hamano wrote:

Show 27 quoted lines

> Adam Spiers <git@adamspiers.org> writes:
> 
> >> 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.
> > ...
> > 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 ;-)
> 
> Oh, that part I would agree, but then ...
> 
> > 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".
> > ...
> > 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.
> 
> ... this part could be even easier if distro ships a sample repository,
> not a recipe to create such a sample repository, no?

It could ship either or both, but shipping a repository only saves the user from having to run a single command to create the repository from the script, and even that advantage is negated if the user wishes the repository to be read/write (since then they would need "cp -a ...").

However, the question of how the distro should ship it is separate to the question of how the git source repository and release tarballs should provide it. Including a script (e.g. in contrib/) means that any changes to the man page can trivially be mirrored in that script within a single commit, giving all the normal advantages git offers for tracking source. And then the distro can easily create the sample repository from the script at package build-time, if they want to.

OTOH, including a sample repository embedded within the git repository is either impossible or very ugly (e.g. having a non-default value of GIT_DIR for the embedded repository). But I doubt you were suggesting that ;-)