git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date
Feb 9, 2018, 20:32 UTC
Message-ID
<20180209203216.11560-14-avarab@gmail.com>
In-Reply-To
<20180209203216.11560-1-avarab@gmail.com>

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.

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.

See "[BUG] git remote prune removes local tags, depending on fetch config" (CACi5S_39wNrbfjLfn0xhCY+uewtFN2YmnAcRc86z6pjUTjWPHQ@mail.gmail.com) by Michael Giuffrida for the initial report.

Reported-by: Michael Giuffrida <michaelpg@chromium.org>
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/git-remote.txt | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index 577b969c1b..4feddc0293 100644
--- 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
 
 'prune'::
 
-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
+remote-tracking branches under <name> are deleted, but depending on
+global configuration and the configuration of the remote we might even
+prune local tags that haven't been pushed there. Equivalent to `git
+fetch --prune <name>`, except that no new references will be fetched.
++
+See the PRUNING section of linkgit:git-fetch[1] for what it'll prune
+depending on various configuration.
 +
 With `--dry-run` option, report what branches will be pruned, but do not
 actually prune them.
@@ -189,7 +193,7 @@ remotes.default is not defined, all remotes which do not have the
 configuration parameter remote.<name>.skipDefaultUpdate set to true will
 be updated.  (See linkgit:git-config[1]).
 +
-With `--prune` option, prune all the remotes that are updated.
+With `--prune` option, run pruning against all the remotes that are updated.
 
 
 DISCUSSION

-- 
2.15.1.424.g9478a66081
Previous: Ævar Arnfjörð BjarmasonNext: Ævar Arnfjörð Bjarmason
Message 103 of 118 in “[BUG] git remote prune removes local tags, depending on fetch config”
  1. Michael GiuffridaJan 15, 2018
  2. Ævar Arnfjörð BjarmasonJan 16, 2018
  3. Michael GiuffridaJan 16, 2018
  4. Ævar Arnfjörð BjarmasonJan 16, 2018
  5. 00/11 document & test fetch pruning + WIP fetch.pruneTagsÆvar Arnfjörð Bjarmason, Jan 19, 2018
  6. 01/11 fetch tests: refactor in preparation for testing tag pruningÆvar Arnfjörð Bjarmason, Jan 19, 2018
  7. 02/11 fetch tests: arrange arguments for future readabilityÆvar Arnfjörð Bjarmason, Jan 19, 2018
  8. 03/11 fetch tests: add a tag to be deleted to the pruning testsÆvar Arnfjörð Bjarmason, Jan 19, 2018
  9. 04/11 fetch tests: double quote a variable for interpolationÆvar Arnfjörð Bjarmason, Jan 19, 2018
  10. 05/11 fetch tests: test --prune and refspec interactionÆvar Arnfjörð Bjarmason, Jan 19, 2018
  11. 06/11 git fetch doc: add a new section to explain the ins & outs of pruningÆvar Arnfjörð Bjarmason, Jan 19, 2018
  12. Eric SunshineJan 19, 2018
  13. 07/11 git remote doc: correct dangerous lies about what prune doesÆvar Arnfjörð Bjarmason, Jan 19, 2018
  14. 08/11 git-fetch & config doc: link to the new PRUNING sectionÆvar Arnfjörð Bjarmason, Jan 19, 2018
  15. 09/11 fetch: don't redundantly null something calloc() gave usÆvar Arnfjörð Bjarmason, Jan 19, 2018
  16. 10/11 fetch tests: add scaffolding for the new fetch.pruneTagsÆvar Arnfjörð Bjarmason, Jan 19, 2018
  17. 11/11 WIP fetch: add a --fetch-prune option and fetch.pruneTags configÆvar Arnfjörð Bjarmason, Jan 19, 2018
  18. 00/12 document & test fetch pruning & add fetch.pruneTagsÆvar Arnfjörð Bjarmason, Jan 21, 2018
  19. 01/12 fetch tests: refactor in preparation for testing tag pruningÆvar Arnfjörð Bjarmason, Jan 21, 2018
  20. 02/12 fetch tests: arrange arguments for future readabilityÆvar Arnfjörð Bjarmason, Jan 21, 2018
  21. 03/12 fetch tests: add a tag to be deleted to the pruning testsÆvar Arnfjörð Bjarmason, Jan 21, 2018
  22. 04/12 fetch tests: double quote a variable for interpolationÆvar Arnfjörð Bjarmason, Jan 21, 2018
  23. Junio C HamanoJan 22, 2018
  24. Ævar Arnfjörð BjarmasonJan 22, 2018
  25. 05/12 fetch tests: test --prune and refspec interactionÆvar Arnfjörð Bjarmason, Jan 21, 2018
  26. 06/12 git fetch doc: add a new section to explain the ins & outs of pruningÆvar Arnfjörð Bjarmason, Jan 21, 2018
  27. 07/12 git remote doc: correct dangerous lies about what prune doesÆvar Arnfjörð Bjarmason, Jan 21, 2018
  28. Junio C HamanoJan 22, 2018
  29. Ævar Arnfjörð BjarmasonJan 22, 2018
  30. 08/12 git-fetch & config doc: link to the new PRUNING sectionÆvar Arnfjörð Bjarmason, Jan 21, 2018
  31. 09/12 fetch: don't redundantly NULL something calloc() gave usÆvar Arnfjörð Bjarmason, Jan 21, 2018
  32. Ævar Arnfjörð BjarmasonJan 21, 2018
  33. 10/12 fetch: stop accessing "remote" variable indirectlyÆvar Arnfjörð Bjarmason, Jan 21, 2018
  34. 11/12 fetch tests: add scaffolding for the new fetch.pruneTagsÆvar Arnfjörð Bjarmason, Jan 21, 2018
  35. 12/12 fetch: add a --fetch-prune option and fetch.pruneTags configÆvar Arnfjörð Bjarmason, Jan 21, 2018
  36. Junio C HamanoJan 22, 2018
  37. Ævar Arnfjörð BjarmasonJan 22, 2018
  38. 00/11 document & test fetch pruning & add fetch.pruneTagsÆvar Arnfjörð Bjarmason, Jan 23, 2018
  39. 01/11 fetch: don't redundantly NULL something calloc() gave usÆvar Arnfjörð Bjarmason, Jan 23, 2018
  40. 03/11 fetch tests: refactor in preparation for testing tag pruningÆvar Arnfjörð Bjarmason, Jan 23, 2018
  41. 02/11 fetch: stop accessing "remote" variable indirectlyÆvar Arnfjörð Bjarmason, Jan 23, 2018
  42. Junio C HamanoJan 24, 2018
  43. 06/11 fetch tests: test --prune and refspec interactionÆvar Arnfjörð Bjarmason, Jan 23, 2018
  44. 07/11 git fetch doc: add a new section to explain the ins & outs of pruningÆvar Arnfjörð Bjarmason, Jan 23, 2018
  45. 09/11 git-fetch & config doc: link to the new PRUNING sectionÆvar Arnfjörð Bjarmason, Jan 23, 2018
  46. 10/11 fetch tests: add scaffolding for the new fetch.pruneTagsÆvar Arnfjörð Bjarmason, Jan 23, 2018
  47. 11/11 fetch: add a --fetch-prune option and fetch.pruneTags configÆvar Arnfjörð Bjarmason, Jan 23, 2018
  48. Junio C HamanoJan 24, 2018
  49. Ævar Arnfjörð BjarmasonJan 24, 2018
  50. Junio C HamanoJan 24, 2018
  51. 05/11 fetch tests: add a tag to be deleted to the pruning testsÆvar Arnfjörð Bjarmason, Jan 23, 2018
  52. 08/11 git remote doc: correct dangerous lies about what prune doesÆvar Arnfjörð Bjarmason, Jan 23, 2018
  53. 04/11 fetch tests: re-arrange arguments for future readabilityÆvar Arnfjörð Bjarmason, Jan 23, 2018
  54. Junio C HamanoJan 24, 2018
  55. Ævar Arnfjörð BjarmasonJan 24, 2018
  56. Ævar Arnfjörð BjarmasonFeb 6, 2018
  57. 00/17 document & test fetch pruning & add fetch.pruneTagsÆvar Arnfjörð Bjarmason, Feb 8, 2018
  58. 01/17 fetch: don't redundantly NULL something calloc() gave usÆvar Arnfjörð Bjarmason, Feb 8, 2018
  59. Eric SunshineFeb 9, 2018
  60. Ævar Arnfjörð BjarmasonFeb 9, 2018
  61. 02/17 fetch: trivially refactor assignment to ref_nrÆvar Arnfjörð Bjarmason, Feb 8, 2018
  62. Eric SunshineFeb 9, 2018
  63. 03/17 fetch: stop accessing "remote" variable indirectlyÆvar Arnfjörð Bjarmason, Feb 8, 2018
  64. 05/17 fetch tests: refactor in preparation for testing tag pruningÆvar Arnfjörð Bjarmason, Feb 8, 2018
  65. 07/17 fetch tests: add a tag to be deleted to the pruning testsÆvar Arnfjörð Bjarmason, Feb 8, 2018
  66. 11/17 fetch tests: fetch <url> <spec> as well as fetch [<remote>]Ævar Arnfjörð Bjarmason, Feb 8, 2018
  67. Eric SunshineFeb 9, 2018
  68. Ævar Arnfjörð BjarmasonFeb 9, 2018
  69. Jeff KingFeb 9, 2018
  70. Eric SunshineFeb 9, 2018
  71. Junio C HamanoFeb 9, 2018
  72. Junio C HamanoFeb 9, 2018
  73. 12/17 git fetch doc: add a new section to explain the ins & outs of pruningÆvar Arnfjörð Bjarmason, Feb 8, 2018
  74. Eric SunshineFeb 9, 2018
  75. 13/17 git remote doc: correct dangerous lies about what prune doesÆvar Arnfjörð Bjarmason, Feb 8, 2018
  76. Eric SunshineFeb 9, 2018
  77. 16/17 fetch: add a --fetch-prune option and fetch.pruneTags configÆvar Arnfjörð Bjarmason, Feb 8, 2018
  78. Eric SunshineFeb 9, 2018
  79. Ævar Arnfjörð BjarmasonFeb 9, 2018
  80. 15/17 fetch tests: add scaffolding for the new fetch.pruneTagsÆvar Arnfjörð Bjarmason, Feb 8, 2018
  81. 14/17 git-fetch & config doc: link to the new PRUNING sectionÆvar Arnfjörð Bjarmason, Feb 8, 2018
  82. 17/17 fetch: make the --fetch-prune work with <url>Ævar Arnfjörð Bjarmason, Feb 8, 2018
  83. Eric SunshineFeb 9, 2018
  84. Ævar Arnfjörð BjarmasonFeb 9, 2018
  85. 10/17 fetch tests: expand case/esac for later changeÆvar Arnfjörð Bjarmason, Feb 8, 2018
  86. 09/17 fetch tests: double quote a variable for interpolationÆvar Arnfjörð Bjarmason, Feb 8, 2018
  87. 06/17 fetch tests: re-arrange arguments for future readabilityÆvar Arnfjörð Bjarmason, Feb 8, 2018
  88. 08/17 fetch tests: test --prune and refspec interactionÆvar Arnfjörð Bjarmason, Feb 8, 2018
  89. 04/17 remote: add a macro for "refs/tags/*:refs/tags/*"Ævar Arnfjörð Bjarmason, Feb 8, 2018
  90. Ævar Arnfjörð BjarmasonFeb 8, 2018
  91. Junio C HamanoFeb 8, 2018
  92. Ævar Arnfjörð BjarmasonFeb 9, 2018
  93. 00/17 document & test fetch pruning & add fetch.pruneTagsÆvar Arnfjörð Bjarmason, Feb 9, 2018
  94. 01/17 fetch: don't redundantly NULL something calloc() gave usÆvar Arnfjörð Bjarmason, Feb 9, 2018
  95. 02/17 fetch: trivially refactor assignment to ref_nrÆvar Arnfjörð Bjarmason, Feb 9, 2018
  96. 03/17 fetch: stop accessing "remote" variable indirectlyÆvar Arnfjörð Bjarmason, Feb 9, 2018
  97. 04/17 remote: add a macro for "refs/tags/*:refs/tags/*"Ævar Arnfjörð Bjarmason, Feb 9, 2018
  98. 05/17 fetch tests: refactor in preparation for testing tag pruningÆvar Arnfjörð Bjarmason, Feb 9, 2018
  99. 08/17 fetch tests: test --prune and refspec interactionÆvar Arnfjörð Bjarmason, Feb 9, 2018
  100. 09/17 fetch tests: double quote a variable for interpolationÆvar Arnfjörð Bjarmason, Feb 9, 2018
  101. 10/17 fetch tests: expand case/esac for later changeÆvar Arnfjörð Bjarmason, Feb 9, 2018
  102. 11/17 fetch tests: fetch <url> <spec> as well as fetch [<remote>]Ævar Arnfjörð Bjarmason, Feb 9, 2018
  103. 13/17 git remote doc: correct dangerous lies about what prune doesÆvar Arnfjörð Bjarmason, Feb 9, 2018
  104. 12/17 git fetch doc: add a new section to explain the ins & outs of pruningÆvar Arnfjörð Bjarmason, Feb 9, 2018
  105. 06/17 fetch tests: re-arrange arguments for future readabilityÆvar Arnfjörð Bjarmason, Feb 9, 2018
  106. 07/17 fetch tests: add a tag to be deleted to the pruning testsÆvar Arnfjörð Bjarmason, Feb 9, 2018
  107. 14/17 git-fetch & config doc: link to the new PRUNING sectionÆvar Arnfjörð Bjarmason, Feb 9, 2018
  108. 15/17 fetch tests: add scaffolding for the new fetch.pruneTagsÆvar Arnfjörð Bjarmason, Feb 9, 2018
  109. 16/17 fetch: add a --prune-tags option and fetch.pruneTags configÆvar Arnfjörð Bjarmason, Feb 9, 2018
  110. 17/17 fetch: make the --prune-tags work with <url>Ævar Arnfjörð Bjarmason, Feb 9, 2018
  111. Junio C HamanoFeb 22, 2018
  112. Ævar Arnfjörð BjarmasonFeb 22, 2018
  113. Junio C HamanoFeb 22, 2018
  114. Ævar Arnfjörð BjarmasonFeb 23, 2018
  115. Junio C HamanoFeb 23, 2018
  116. Ævar Arnfjörð BjarmasonFeb 24, 2018
  117. Andreas SchwabJan 16, 2018
  118. Kevin DaudtJan 18, 2018

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.