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