[PATCH] pack-redundant: document deprecation

[Jeff King <peff@peff.net>]

On Thu, Mar 23, 2023 at 02:23:46PM -0700, Junio C Hamano wrote:

> I notice that "git pack-redundant --help" does not say anything
> about its deprecation.  We probably should add one together with
> the patch in question, and then consider that the count-down timer
> has finally started.

Good thinking. Here is a patch.

-- >8 --
Subject: [PATCH] pack-redundant: document deprecation

Running the command itself has generated a warning for several versions,
which has recently been upgraded to an error. Let's also make sure the
documentation mentions what is going on. This also gives us a good spot
to explain the reasoning and recommend alternatives.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/git-pack-redundant.txt | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt
index 99ef13839d4..13c3eb5ec96 100644
--- a/Documentation/git-pack-redundant.txt
+++ b/Documentation/git-pack-redundant.txt
@@ -11,6 +11,20 @@ SYNOPSIS
 [verse]
 'git pack-redundant' [--verbose] [--alt-odb] (--all | <pack-filename>...)
 
+WARNING
+-------
+`git pack-redundant` has been deprecated and is scheduled for removal in
+a future version of Git. Because it can only remove entire duplicate
+packs and not individual duplicate objects, it is generally not a useful
+tool for reducing repository size. You are better off using `git gc` to
+do so, which will put objects into a new pack, removing duplicates.
+
+Running `pack-redundant` without the `--i-still-use-this` flag will fail
+in this release. If you believe you have a use case for which
+`pack-redundant` is better suited and oppose this removal, please
+contact the Git mailing list at git@vger.kernel.org. More information
+about the list is available at https://git-scm.com/community.
+
 DESCRIPTION
 -----------
 This program computes which packs in your repository
-- 
2.40.0.616.gf524ec75088