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

[Junio C Hamano <gitster@pobox.com>]

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.

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.

For that reason,...

> diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt
> index f151cff..f92bb8c 100644
> --- 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 ...

>  This runs `git-fsck --unreachable` using all the refs
>  available in `$GIT_DIR/refs`, optionally with additional set of
>  objects specified on the command line, and prunes all
> @@ -50,6 +53,23 @@ borrows from your repository via its
>  $ git prune $(cd ../another && $(git-rev-parse --all))
>  ------------
>  
> +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.

> +For a description of which objects are considered for pruning, see
> +git-fsck's --unreachable option.
> +
> +See Also
> +--------
> +
> +linkgit:git-fsck[1],
> +linkgit:git-gc[1],
> +linkgit:git-reflog[1]
> +
>  Author
>  ------
>  Written by Linus Torvalds <torvalds@osdl.org>
> -- 
> 1.5.5.1.172.g4dce