Re: [PATCH] Add commands that git-gc runs underneath

[Theodore Tso <tytso@mit.edu>]

On Thu, Aug 30, 2007 at 12:58:00PM +0100, Johannes Schindelin wrote:
> On Thu, 30 Aug 2007, Andreas Ericsson wrote:
> 
> > I kinda like it [listing the commands git-gc calls], and it might be 
> > helpful if someone's got a large repo and one part of gc for some reason 
> > didn't complete so they want to start at whatever step it broke off on.
> 
> Let me clarify: I do not like the listing in the man page.  This suggests 
> to the user to delve into plumbing areas where it is all too easy to shoot 
> yourself in the foot.

I'm somewhat sympathetic to that argument, but at the same time, we're
still telling users to read the man page for plumbing areas in order
to understand to get the listing valid command-line options to git
commands.  In addition, the main git(1) man page is dedicating talking
about all sorts of low-level on-disk storage details that arguably
should be in the Documentation/technical that you suggested.  I also
don't quite see how commands like git-repack, git-prune,
git-pack-refs, et. al., are likely to get the user into trouble, any
more than git-gc --prune might.  Those commands are all relatively
safe, and indeed, they are all listed in the git-gc's "SEE ALSO"
section of its man page, so users are already being encouraged to
delve into plumbing areas.

That being said, given the SEE ALSO section, I don't think it adds a
huge amount of value to list the exact set of commands and options by
git-gc.  Also, if we add more functionality to git-gc in the future,
it would be pain to have to keep upgrading to man page uptodate.

   	    	    	    	 	      - Ted