On Thu, Jan 18, 2018 at 7:00 PM, Ævar Arnfjörð Bjarmason
<avarab@xxxxxxxxx> wrote:
> 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@xxxxxxxxx>
> ---
> 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/&,/
> +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].
