Re: [PATCH 06/11] git fetch doc: add a new section to explain the ins & outs of pruning

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Jan 19, 2018, 00:46 UTC
Message-ID: <CAPig+cRVHQQR_V+GH1X-KVBtCRkGq=PewOQJu6WcnVa6N+sRNA@mail.gmail.com>
In-Reply-To: <20180119000027.28898-7-avarab@gmail.com>

On Thu, Jan 18, 2018 at 7:00 PM, Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:

Show 16 quoted lines

> Add a new section to canonically explain how remote reference pruning
> works, and how users should be careful about using it in conjunction
> with tag refspecs in particular.
>
> A subsequent commit will update the git-remote documentation to refer
> to this section, and details the motivation for writing this in the
> first place.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
> @@ -99,6 +99,55 @@ The latter use of the `remote.<repository>.fetch` values can be
> +PRUNING
> +-------
> +
> +Git has a default disposition to keeping data unless it's explicitly

s/keeping/keep/ or s/to keeping/of keeping/

> +thrown away, this extends to keeping a hold of local references to

s/away,/away;/ s/to keeping a hold of/holding onto/

> +branches on remotes that have themselves deleted those branches.
> +
> +If left to accumulate these stale references might make performance

s/accumulate/&,/

Show 15 quoted lines

> +worse on big and busy repos that have a lot of branch churn, and
> +e.g. make the output of commands like `git branch -a --contains
> +<commit>` needlessly verbose, as well as impacting anything else
> +that'll work with the complete set of known references.
> +
> +These remote tracking references can be deleted as a one-off with
> +either of:
> +
> +------------------------------------------------
> +# While fetching
> +$ git fetch --prune <name>
> +
> +# Only prune, don't fetch
> +$ git remote <name>
> +------------------------------------------------

Did you mean "git remote prune <name>"?

> +To prune references on a remote as part of your normal workflow

This reads as if it's possible to prune something on the remote machine itself. Maybe just say:

    To prune references as part of your normal workflow...

> +without needing to remember to run that set `fetch.prune` globally, or
> +`remote.<name>.prune` per-remote in the config. See
> +linkgit:git-config[1].