On Sat, Dec 21, 2013 at 10:44:43PM -0800, Junio C Hamano wrote:
> Adam Spiers <g...@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
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html