Re: questions / suggestions about history simplification

[Adam Spiers <git@adamspiers.org>]

On Sat, Dec 21, 2013 at 10:44:43PM -0800, Junio C Hamano wrote:
> 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 ;-)