you-still-use-that??: help the user help themselves

Give the user a list of suggestions for what to do when they run a
deprecated command.

The first order of action will be to check the breaking changes
document;[1] this short error message says nothing about why this
command is deprecated, and in any case going into any kind of detail
might overwhelm the user.

Then they can find out if this has been discussed on the mailing list.
Then users who e.g. are using git-whatchanged(1) can learn that this is
arguably a plug-in replacement:

    git log <opts> --raw --no-merges

Finally they are invited to send an email to the mailing list.

Also drop the “please add” part in favor of just using the “refusing”
die-message; these two would have been right after each other in this
new version.

Also drop “Thanks” since it now would require a new paragraph.

[1]: www.git-scm.com has a disclaimer for these internal documents that
    says that “This information is specific to the Git project”.  That’s
    misleading in this particular case.  But users are unlikely to get
    discouraged from reading about why they (or their programs) cannot run a
    command any more; it clearly concerns them.

Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/usage.c b/usage.c
index 81913236a4a2ab90bac8655061830ea863d4ed3b..35dc57eb07ef8ea7e53a66678cfa40f7748e91e0 100644 (file)
--- a/usage.c
+++ b/usage.c
@@ -7,6 +7,7 @@
 #include "git-compat-util.h"
 #include "gettext.h"
 #include "trace2.h"
+#include "strbuf.h"
 
 static void vfreportf(FILE *f, const char *prefix, const char *err, va_list params)
 {
@@ -377,12 +378,24 @@ void bug_fl(const char *file, int line, const char *fmt, ...)
 
 NORETURN void you_still_use_that(const char *command_name)
 {
+       struct strbuf percent_encoded = STRBUF_INIT;
+       strbuf_add_percentencode(&percent_encoded,
+                                command_name,
+                                STRBUF_ENCODE_SLASH);
+
        fprintf(stderr,
                _("'%s' is nominated for removal.\n"
-                 "If you still use this command, please add an extra\n"
-                 "option, '--i-still-use-this', on the command line\n"
-                 "and let us know you still use it by sending an e-mail\n"
-                 "to <git@vger.kernel.org>.  Thanks.\n"),
-               command_name);
+                 "If you still use this command, here's what you can do:\n"
+                 "\n"
+                 "- read https://git-scm.com/docs/BreakingChanges.html\n"
+                 "- check if anyone has discussed this on the mailing\n"
+                 "  list and if they came up with something that can\n"
+                 "  help you: https://lore.kernel.org/git/?q=%s\n"
+                 "- send an email to <git@vger.kernel.org> to let us\n"
+                 "  know that you still use this command and were unable\n"
+                 "  to determine a suitable replacement\n"
+                 "\n"),
+               command_name, percent_encoded.buf);
+       strbuf_release(&percent_encoded);
        die(_("refusing to run without --i-still-use-this"));
 }