git fetch doc: add a new section to explain the ins & outs of pruning
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Feb 9, 2018 at 20:32 UTC
2c72ed740f302bf51e6cd0824b8e7cbde1b1e8c2
1 file changed
+49
Documentation/git-fetch.txt
+49
@@ -99,6 +99,55 @@ The latter use of the `remote.<repository>.fetch` values can be
99
overridden by giving the `--refmap=<refspec>` parameter(s) on the
100
command line.
101
102
+PRUNING
103
+-------
104
+
105
+Git has a default disposition of keeping data unless it's explicitly
106
+thrown away; this extends to holding onto local references to branches
107
+on remotes that have themselves deleted those branches.
108
+
109
+If left to accumulate, these stale references might make performance
110
+worse on big and busy repos that have a lot of branch churn, and
111
+e.g. make the output of commands like `git branch -a --contains
112
+<commit>` needlessly verbose, as well as impacting anything else
113
+that'll work with the complete set of known references.
114
+
115
+These remote-tracking references can be deleted as a one-off with
116
+either of:
117
+
118
+------------------------------------------------
119
+# While fetching
120
+$ git fetch --prune <name>
121
+
122
+# Only prune, don't fetch
123
+$ git remote prune <name>
124
+------------------------------------------------
125
+
126
+To prune references as part of your normal workflow without needing to
127
+remember to run that, set `fetch.prune` globally, or
128
+`remote.<name>.prune` per-remote in the config. See
129
+linkgit:git-config[1].
130
+
131
+Here's where things get tricky and more specific. The pruning feature
132
+doesn't actually care about branches, instead it'll prune local <->
133
+remote-references as a function of the refspec of the remote (see
134
+`<refspec>` and <<CRTB,CONFIGURED REMOTE-TRACKING BRANCHES>> above).
135
+
136
+Therefore if the refspec for the remote includes
137
+e.g. `refs/tags/*:refs/tags/*`, or you manually run e.g. `git fetch
138
+--prune <name> "refs/tags/*:refs/tags/*"` it won't be stale remote
139
+tracking branches that are deleted, but any local tag that doesn't
140
+exist on the remote.
141
+
142
+This might not be what you expect, i.e. you want to prune remote
143
+`<name>`, but also explicitly fetch tags from it, so when you fetch
144
+from it you delete all your local tags, most of which may not have
145
+come from the `<name>` remote in the first place.
146
+
147
+So be careful when using this with a refspec like
148
+`refs/tags/*:refs/tags/*`, or any other refspec which might map
149
+references from multiple remotes to the same local namespace.
150
+
151
OUTPUT
152
------
153