Re: [PATCH] Documentation: point git-prune users to git-gc

From: Jeff King <peff@peff.net>
Date: Apr 29, 2008, 23:19 UTC
Message-ID: <20080429231917.GB22646@sigill.intra.peff.net>
In-Reply-To: <7vskx45ncg.fsf@gitster.siamese.dyndns.org>

On Tue, Apr 29, 2008 at 03:05:03PM -0700, Junio C Hamano wrote:

Show 12 quoted lines

> Jeff King <peff@peff.net> writes:
> 
> > Yes, I don't think there is any reason for most people to use git-prune
> > at all, unless they are trying specifically to prune and don't want the
> > other gc effects to happen.
> >
> > Junio, please correct me if I'm wrong there.
> 
> Well, this is a hard statement to make corrections to.  If A is defined to
> be a subset of B, and A is generally useful, the only reason to do B is
> when you want the effect of B without anything else.  So your statement
> cannot be incorrect.

Heh. Sorry, I got very sloppy with my wording...there was an 11-month-old child yelling in my ear. :)

My meaning was: "people who want to clean up their repo but don't know the right command stumble upon git-prune. They probably should be using git-gc instead. People who know that they want to prune presumably know enough to ignore the warning note."

> However, in order to help people decide when to run B (or, if there ever
> be a case where they might want to), there needs a discussion what other
> things that _might_ be unwanted A does in addition to B.

Fair enough.

Show 13 quoted lines

> > --- a/Documentation/git-prune.txt
> > +++ b/Documentation/git-prune.txt
> > @@ -13,6 +13,9 @@ SYNOPSIS
> >  DESCRIPTION
> >  -----------
> >  
> > +NOTE: In most cases, users should run linkgit:git-gc[1], which calls
> > +git-prune. See the section "NOTES", below.
> > +
> 
> I think this note upfront is not helping readers very much (this is
> git-prune documentation after all -- they are interested in the command
> and not gc), but ...

I'm not so sure that they are interested in the prune command. At first I started with just a note near the end, but the point of this is specifically to deal with users who "stumble" upon prune, either from reading the command list (i.e., trying to match a command to the objective they want to perform) or from pre-gc tutorials or emails which mention it.

Show 9 quoted lines

> > +Notes
> > +-----
> > +
> > +In most cases, users will not need to call git-prune directly, but
> > +should instead call linkgit:git-gc[1], which handles pruning along with
> > +many other housekeeping tasks.
> 
> ... this paragraph should be made a bit fatter by mentioning what "other
> housekeeping tasks" are.

OK, I was trying to imply "go look at git-gc for those tasks" so they didn't have to be repeated. Would you prefer it be spelled out explicitly here, or is a more firm pointer OK?

-Peff