Re: [PATCH v2 13/17] git remote doc: correct dangerous lies about what prune does

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Feb 9, 2018, 05:33 UTC
Message-ID: <CAPig+cQCuMyWYrsMq8=FDJC5D+EuZk=eoK6ri3Lgs62VPzAX2A@mail.gmail.com>
In-Reply-To: <20180208161936.8196-14-avarab@gmail.com>

On Thu, Feb 8, 2018 at 11:19 AM, Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:

Show 10 quoted lines

> The "git remote prune <name>" command uses the same machinery as "git
> fetch <name> --prune", and shares all the same caveats, but its
> documentation has suggested that it'll just "delete stale
> remote-tracking branches under <name>".
>
> This isn't true, and hasn't been true since at least v1.8.5.6 (the
> oldest version I could be bothered to test).
>
> E.g. if "refs/tags/*:refs/tags/*" is explicitly set in the refspec of
> the remote it'll delete all local tags <name> doesn't know about.

Not worth a re-roll as this is only the commit message: s/remote/&,/

More below...

Show 14 quoted lines

> Instead, briefly give the reader just enough of a hint that this
> option might constitute a shotgun aimed at their foot, and point them
> to the new PRUNING section in the git-fetch documentation which
> explains all the nuances of what this facility does.
> [...]
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
> @@ -172,10 +172,14 @@ With `-n` option, the remote heads are not queried first with
> -Deletes all stale remote-tracking branches under <name>.
> -These stale branches have already been removed from the remote repository
> -referenced by <name>, but are still locally available in
> -"remotes/<name>".
> +Deletes stale references associated with <name>. By default stale

Nit: s/default/&,/

> +remote-tracking branches under <name>, but depending on global
> +configuration and the configuration of the remote we might even prune
> +local tags that haven't been pushed there.

This is a bit difficult to digest grammatically due to the phrase being incomplete. It could say either:

    By default, stale ... under <name> _are deleted_, but
    depending...

or:

    Deletes stale ... <name>; by default, stale...