Recommend "git gc --prune=now" instead of "git prune"

From: John Lin <[email protected]>

---
Recommend "git gc --prune=now" instead of "git prune"

Fix according to #642.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-652%2Fjohnlinp%2Ffix-git-gc-warning-message-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-652/johnlinp/fix-git-gc-warning-message-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/652

 builtin/gc.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 8e0b9cf41b3..74185eac917 100644
@@ -692,7 +692,7 @@ int cmd_gc(int argc, const char **argv, const char *prefix)
 
 	if (auto_gc && too_many_loose_objects())
 		warning(_("There are too many unreachable loose objects; "
-			"run 'git prune' to remove them."));
+			"run 'git gc --prune=now' to remove them."));
 
 	if (!daemonized)
 		unlink(git_path("gc.log"));

base-commit: 20514004ddf1a3528de8933bc32f284e175e1012

gitgitgadget

Hi John,

Thanks for working on this topic.

The format for subjects is generally "<area>: <description>" so perhaps something like "git gc: recommend use of git gc --prune=now"?

This commit is missing some justification. In the commit message, we should mention that git prune is a plumbing command and in the documentation for it, it mentions that the porcelain git gc command should be used instead.

From: John Lin <[email protected]>

git prune is a plumbing command and should not be run directly by users. The corresponding porcelain command is git gc, which is mentioned in the man page of git prune.

---
Recommend "git gc --prune=now" instead of "git prune"

Fix according to #642.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-652%2Fjohnlinp%2Ffix-git-gc-warning-message-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-652/johnlinp/fix-git-gc-warning-message-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/652

Range-diff vs v1:

1: 83b7137abfd ! 1: 42aa6380067 Recommend "git gc --prune=now" instead of "git prune"
@@ Metadata
Author: John Lin <[email protected]>

## Commit message ##
- Recommend "git gc --prune=now" instead of "git prune"
+ gc: recommend git gc --prune=now instead of git prune
+
+ git prune is a plumbing command and should not be run directly by
+ users. The corresponding porcelain command is git gc, which is
+ mentioned in the man page of git prune.

 builtin/gc.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 8e0b9cf41b3..74185eac917 100644
@@ -692,7 +692,7 @@ int cmd_gc(int argc, const char **argv, const char *prefix)
 
 	if (auto_gc && too_many_loose_objects())
 		warning(_("There are too many unreachable loose objects; "
-			"run 'git prune' to remove them."));
+			"run 'git gc --prune=now' to remove them."));
 
 	if (!daemonized)
 		unlink(git_path("gc.log"));

base-commit: 20514004ddf1a3528de8933bc32f284e175e1012

gitgitgadget

Much better than v1 that came without any justification ;-)

I however wouldn't say "should not"---that feels a bit too strong (I personally use "prune" from the command line once or twice every week and do not see why I should be forbidden from doing so [*1*]), but the users who see this message would not need such a precise control afforded by use of "git prune", so "gc --prune=now" is a better recommendation.

Thanks.

[Footnote]

*1* The command does not even produce a machine readable output.
The reason it is not recommended (but that is different from "should not") to casual users over "git gc" is because it is a very focused tool (it is only about removing loose objects and does not touch other things) and applicable to a very specific condition. Those who can recognize that they are in that situation should not be forbidden from using it with a dogmatic "should not".

This change feels incomplete without a change to git-prune's documentation, see 8d308b3540 ("Documentation: point git-prune users to git-gc", 2008-04-29).

I.e. it still talks about "in most cases you shouldn't run this", but here we are removing a case where it would otherwise make sense because the user shouldn't use it directly.

I think instead the small change that makes the most sense here is to just add "prune" to completions, i.e. I disagree with Denton Liu in
https://github.com/gitgitgadget/git/issues/642#issuecomment-640202110

The "right" change is much harder, there's numerous odd edge cases that "gc" can get into with these loose objects (for the curious [1] and [2] are a nice entry to that rabbit hole).

Fixing that is non-trivial, but in the meantime I don't think it's good to:

a) Recommend an option to "gc" which implies "repack -a", which as noted in gc's docs can produce corruption in a live repository.

I.e. I don't think "let's not recommend this plumbing" should lead us to "let's recommend this thing that could corrupt the repository instead".

b) Even if you don't get the corruption with "a" above "gc --prune=now" will produce a very differently packed repository. This might have unexpected performance etc. trade-offs the user wasn't expecting from a "run this for a quick fix" command.

c) In the cases where "prune" here would help, e.g. on some large repo where something else added a lot of loose unreachable objects during the "gc" for some reason recommending a full "gc" might take a lot more time than just the "prune".

1. https://public-inbox.org/git/[email protected]/
2. https://public-inbox.org/git/[email protected]/

That's perfectly reasonable stance to take.

Hi all,

Thank you Bjarmason & Junio. If Denton doesn't have other concerns, I'll start working on adding bash completion for "git prune".

Best,
John Lin

Junio C Hamano <[email protected]> 於 2020年6月10日 週三 上午12:03寫道：

No concerns. Thanks for contributing!

Thanks Denton!

Best,
John Lin

Denton Liu <[email protected]> 於 2020年6月10日 週三 上午11:48寫道：