On Tue, Apr 29, 2008 at 03:05:03PM -0700, Junio C Hamano wrote: > Jeff King <peff@xxxxxxxx> 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. > > --- 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. > > +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 -- 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
