[PATCH 0/4] you-still-use-that??: improve breaking changes troubleshooting

[PATCH 0/4] you-still-use-that??: improve breaking changes troubleshooting

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Based on the recent i-still-use-that reports about whatchanged, improve
the error reporting with this command in mind:

1. Give more possible actions instead of just (only) asking them to send
   an email
2. Hint how to replace their git-whatchanged(1) use with git-log(1)
3. Minor documentation changes

I don’t know how much does matters now that 2.51.0 is out.  I guess it
depends on when the next maintenance release is and how many platforms
will upgrade it?  I don’t know anything about that.  (But maybe they
will do it straight away since they are releasing for the latest
version?)

Kristoffer Haugsbakk (4):
  usage: help the user help themselves
  whatchanged: tell users the git-log(1) equivalent
  whatchanged: remove not-even-shorter clause
  BreakingChanges: remove claim about whatchanged reports

 Documentation/BreakingChanges.adoc |  2 +-
 Documentation/git-whatchanged.adoc |  8 ++++++--
 builtin/log.c                      |  8 ++++++--
 builtin/pack-redundant.c           |  2 +-
 git-compat-util.h                  |  2 +-
 usage.c                            | 31 +++++++++++++++++++++++-------
 6 files changed, 39 insertions(+), 14 deletions(-)


base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
-- 
2.51.0.11.g23cedd8a747

[PATCH 1/4] usage: help the user help themselves

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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]: git-scm 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.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    An alternative to linking to git-scm is to move this document to a
    regular installed man page:
    
        gitbreaking-changes(7)
    
    What do you think?
    
    I would then have to base my topic on the in-flight
    pw/3.0-commentchar-auto-deprecation, which in turn depends on
    ps/config-wo-the-repository.
    
    Or just wait a bit for these to settle in.

 usage.c | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/usage.c b/usage.c
index 81913236a4a..29988395f19 100644
--- 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,22 @@ 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>\n"
+		  "\n"),
+		command_name, percent_encoded.buf);
+	strbuf_release(&percent_encoded);
 	die(_("refusing to run without --i-still-use-this"));
 }
-- 
2.51.0.11.g23cedd8a747

[PATCH 2/4] whatchanged: tell users the git-log(1) equivalent

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

There have been quite a few `--i-still-use-this` user reports since Git
2.51.0 was released.[1][2]  And it doesn’t seem like they are reading
the man page about the git-log(1) equivalent.

Tell them what options to plug into git-log(1).  That template produces
almost the same output[3] and is arguably a plug-in replacement.
Concretely, add an optional `hint` argument so that we can use it right
after the initial error line.

Also mention the same concrete options in the documentation while we’re
at it.

[1]: E.g.,
    • https://lore.kernel.org/git/e1a69dea-bcb6-45fc-83d3-9e50d32c410b@5y5.one/
    • https://lore.kernel.org/git/1011073f-9930-4360-a42f-71eb7421fe3f@chrispalmer.uk/#t
    • https://lore.kernel.org/git/9fcbfcc4-79f9-421f-b9a4-dc455f7db485@acm.org/#t
    • https://lore.kernel.org/git/83241BDE-1E0D-489A-9181-C608E9FCC17B@gmail.com/
[2] The error message on 2.51.0 does tell them to report it, unconditionally
[3]: https://lore.kernel.org/git/20250825085428.GA367101@coredump.intra.peff.net/

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-whatchanged.adoc |  6 +++++-
 builtin/log.c                      |  8 ++++++--
 builtin/pack-redundant.c           |  2 +-
 git-compat-util.h                  |  2 +-
 usage.c                            | 14 ++++++++++----
 5 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-whatchanged.adoc b/Documentation/git-whatchanged.adoc
index d21484026fe..e71d2aa2d27 100644
--- a/Documentation/git-whatchanged.adoc
+++ b/Documentation/git-whatchanged.adoc
@@ -24,7 +24,11 @@ Shows commit logs and diff output each commit introduces.
 
 New users are encouraged to use linkgit:git-log[1] instead.  The
 `whatchanged` command is essentially the same as linkgit:git-log[1]
-but defaults to showing the raw format diff output and skipping merges.
+but defaults to showing the raw format diff output and skipping merges:
+
+----
+git log --raw --no-merges
+----
 
 The command is primarily kept for historical reasons; fingers of
 many people who learned Git long before `git log` was invented by
diff --git a/builtin/log.c b/builtin/log.c
index c2f8bbf8630..2f9e5e5a898 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -542,8 +542,12 @@ int cmd_whatchanged(int argc,
 	opt.revarg_opt = REVARG_COMMITTISH;
 	cmd_log_init(argc, argv, prefix, &rev, &opt, &cfg);
 
-	if (!cfg.i_still_use_this)
-		you_still_use_that("git whatchanged");
+        if (!cfg.i_still_use_this)
+		you_still_use_that("git whatchanged",
+				   _("\n"
+				     "hint: You can replace 'git whatchanged <opts>' with:\n"
+				     "    git log <opts> --raw --no-merges\n"
+				     "\n"));
 
 	if (!rev.diffopt.output_format)
 		rev.diffopt.output_format = DIFF_FORMAT_RAW;
diff --git a/builtin/pack-redundant.c b/builtin/pack-redundant.c
index fe81c293e3a..5d5ae4afa28 100644
--- a/builtin/pack-redundant.c
+++ b/builtin/pack-redundant.c
@@ -626,7 +626,7 @@ int cmd_pack_redundant(int argc, const char **argv, const char *prefix UNUSED, s
 	}
 
 	if (!i_still_use_this)
-		you_still_use_that("git pack-redundant");
+		you_still_use_that("git pack-redundant", NULL);
 
 	if (load_all_packs)
 		load_all();
diff --git a/git-compat-util.h b/git-compat-util.h
index 9408f463e31..398e0fac4fa 100644
--- a/git-compat-util.h
+++ b/git-compat-util.h
@@ -460,7 +460,7 @@ void warning_errno(const char *err, ...) __attribute__((format (printf, 1, 2)));
 
 void show_usage_if_asked(int ac, const char **av, const char *err);
 
-NORETURN void you_still_use_that(const char *command_name);
+NORETURN void you_still_use_that(const char *command_name, const char *hint);
 
 #ifndef NO_OPENSSL
 #ifdef APPLE_COMMON_CRYPTO
diff --git a/usage.c b/usage.c
index 29988395f19..c661561b149 100644
--- a/usage.c
+++ b/usage.c
@@ -376,7 +376,8 @@ void bug_fl(const char *file, int line, const char *fmt, ...)
 	va_end(ap);
 }
 
-NORETURN void you_still_use_that(const char *command_name)
+
+NORETURN void you_still_use_that(const char *command_name, const char *hint)
 {
 	struct strbuf percent_encoded = STRBUF_INIT;
 	strbuf_add_percentencode(&percent_encoded,
@@ -384,8 +385,13 @@ NORETURN void you_still_use_that(const char *command_name)
 				 STRBUF_ENCODE_SLASH);
 
 	fprintf(stderr,
-		_("'%s' is nominated for removal.\n"
-		  "If you still use this command, here's what you can do:\n"
+		_("'%s' is nominated for removal.\n"), command_name);
+
+	if (hint)
+		fputs(hint, stderr);
+
+	fprintf(stderr,
+		_("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"
@@ -393,7 +399,7 @@ NORETURN void you_still_use_that(const char *command_name)
 		  "  help you: https://lore.kernel.org/git/?q=%s\n"
 		  "- send an email to <git@vger.kernel.org>\n"
 		  "\n"),
-		command_name, percent_encoded.buf);
+		percent_encoded.buf);
 	strbuf_release(&percent_encoded);
 	die(_("refusing to run without --i-still-use-this"));
 }
-- 
2.51.0.11.g23cedd8a747

[PATCH 3/4] whatchanged: remove not-even-shorter clause

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

The closest equivalent is `git log --raw --no-merges`.

Also change to “defaults” (implicit plural).

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-whatchanged.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-whatchanged.adoc b/Documentation/git-whatchanged.adoc
index e71d2aa2d27..436e219b7d0 100644
--- a/Documentation/git-whatchanged.adoc
+++ b/Documentation/git-whatchanged.adoc
@@ -15,7 +15,7 @@ WARNING
 -------
 `git whatchanged` has been deprecated and is scheduled for removal in
 a future version of Git, as it is merely `git log` with different
-default; `whatchanged` is not even shorter to type than `log --raw`.
+defaults.
 
 DESCRIPTION
 -----------
-- 
2.51.0.11.g23cedd8a747

[PATCH 4/4] BreakingChanges: remove claim about whatchanged reports

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This was written in e836757e14b (whatschanged: list it in
BreakingChanges document, 2025-05-12) which was on the same
topic that added the `--i-still-use-this` requirement.[1]

Maybe it was a work-in-progress comment/status.

[1]: jc/you-still-use-whatchanged

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    Footnote solely to avoid awkward paragraph wrapping...

 Documentation/BreakingChanges.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc
index f8d2eba061c..c4985163c3c 100644
--- a/Documentation/BreakingChanges.adoc
+++ b/Documentation/BreakingChanges.adoc
@@ -235,7 +235,7 @@ These features will be removed.
   equivalent `git log --raw`.  We have nominated the command for
   removal, have changed the command to refuse to work unless the
   `--i-still-use-this` option is given, and asked the users to report
-  when they do so.  So far there hasn't been a single complaint.
+  when they do so.
 +
 The command will be removed.
 
-- 
2.51.0.11.g23cedd8a747

Re: [PATCH 0/4] you-still-use-that??: improve breaking changes troubleshooting

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> Based on the recent i-still-use-that reports about whatchanged, improve
> the error reporting with this command in mind:
>
> 1. Give more possible actions instead of just (only) asking them to send
>    an email
> 2. Hint how to replace their git-whatchanged(1) use with git-log(1)
> 3. Minor documentation changes

Nice.  Especially the attention to minor details shown in [3/4] and [4/4]
is very much appreciated.

Re: [PATCH 2/4] whatchanged: tell users the git-log(1) equivalent

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> -	if (!cfg.i_still_use_this)
> -		you_still_use_that("git whatchanged");
> +        if (!cfg.i_still_use_this)
> +		you_still_use_that("git whatchanged",

I spot a whitespace breakage here.  I didn't check if there are
other instances.  Please check your editor settings (or run "git
diff --check --cached" before committing yoru changes, or both).

Thanks.

Re: [PATCH 2/4] whatchanged: tell users the git-log(1) equivalent

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> kristofferhaugsbakk@fastmail.com writes:
>
>> -	if (!cfg.i_still_use_this)
>> -		you_still_use_that("git whatchanged");
>> +        if (!cfg.i_still_use_this)
>> +		you_still_use_that("git whatchanged",
>
> I spot a whitespace breakage here.  I didn't check if there are

Sorry, I read the patch backwards.  You are fixing an existing
whitespace breakage, which is very much appreciated, as this is
immediate vicinity of the real change of this topic.

Thanks.

Re: [PATCH 2/4] whatchanged: tell users the git-log(1) equivalent

[Kristoffer Haugsbakk]

On Wed, Aug 27, 2025, at 18:48, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> kristofferhaugsbakk@fastmail.com writes:
>>
>>> -	if (!cfg.i_still_use_this)
>>> -		you_still_use_that("git whatchanged");
>>> +        if (!cfg.i_still_use_this)
>>> +		you_still_use_that("git whatchanged",
>>
>> I spot a whitespace breakage here.  I didn't check if there are
>
> Sorry, I read the patch backwards.  You are fixing an existing
> whitespace breakage, which is very much appreciated, as this is
> immediate vicinity of the real change of this topic.

No, I did inadvertently replace the tab indents with spaces.  I’ll have
to configure my editor better.  I’ll fix it.

(`ci/check-whitespace.sh v2.51.0` turned out to be helpful for me here)

-- 
Kristoffer Haugsbakk

Re: [PATCH 1/4] usage: help the user help themselves

[Kristoffer Haugsbakk]

> usage: help the user help themselves

I think I’ll change the area to the more pointed:

    you-still-use-that??:

On Wed, Aug 27, 2025, at 18:29, kristofferhaugsbakk@fastmail.com wrote:
> @@ -377,12 +378,22 @@ 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>\n"

Maybe (thinking out loud) this should retain some part of the “let us
know you still use this” spirit:

    - send an email to <git@vger.kernel.org> and let us know
      that you still use this command

> +		  "\n"),
> +		command_name, percent_encoded.buf);
> +	strbuf_release(&percent_encoded);
>  	die(_("refusing to run without --i-still-use-this"));
>  }
> --
> 2.51.0.11.g23cedd8a747

Re: [PATCH 1/4] usage: help the user help themselves

[Eric Sunshine]

On Wed, Aug 27, 2025 at 4:36 PM Kristoffer Haugsbakk
<code@khaugsbakk.name> wrote:
> On Wed, Aug 27, 2025, at 18:29, kristofferhaugsbakk@fastmail.com wrote:
> >       fprintf(stderr,
> >               _("'%s' is nominated for removal.\n"
> > +               "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>\n"
>
> Maybe (thinking out loud) this should retain some part of the “let us
> know you still use this” spirit:
>
>     - send an email to <git@vger.kernel.org> and let us know
>       that you still use this command

That's still inviting unnecessary emails, isn't it? It would probably
be better add the qualification that people should send the email only
if they were unable to find any workable replacement. Perhaps:

    - send an email to <git@...> to let us know
      that you still use this command and were unable
      to determine a suitable replacement

Re: [PATCH 1/4] usage: help the user help themselves

[Junio C Hamano]

"Kristoffer Haugsbakk" <code@khaugsbakk.name> writes:

>> usage: help the user help themselves
>
> I think I’ll change the area to the more pointed:
>
>     you-still-use-that??:

Ah, that makes sense.

> On Wed, Aug 27, 2025, at 18:29, kristofferhaugsbakk@fastmail.com wrote:
>> @@ -377,12 +378,22 @@ 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>\n"
>
> Maybe (thinking out loud) this should retain some part of the “let us
> know you still use this” spirit:
>
>     - send an email to <git@vger.kernel.org> and let us know
>       that you still use this command

We do not actually want to bother individual users about reporting.

We may want to catch third-party tools (like we heard a problem with
Jenkins from its users), so

    - notify <git@vger.kernel.org> mailing list if you are a lead
      developer of a widely used tool, especially if you heard a
      breakage report on your tool from your users due to this
      message.

perhaps?  If we know that version A of tool X (or older) hasn't
migrated, users of the same tool will see the same breakage, and
some of them may come to this list.  If we know about their problem
ahead of time, we'd be better prepared to give them a definitive
"Yes, we know version A of tool X (or older) still uses it, and the
developer of tool X is aware of the problem."

Hopefully ;-)

Re: [PATCH 1/4] usage: help the user help themselves

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

> That's still inviting unnecessary emails, isn't it? It would probably
> be better add the qualification that people should send the email only
> if they were unable to find any workable replacement. Perhaps:
>
>     - send an email to <git@...> to let us know
>       that you still use this command and were unable
>       to determine a suitable replacement

In practice, people will respond to such an instruction by always
sending an e-mail.  Asking others who sound as if they are promising
to give answers when asked is cheaper than investigating themselves
;-).

Re: [PATCH 1/4] usage: help the user help themselves

[Eric Sunshine]

On Wed, Aug 27, 2025 at 5:20 PM Junio C Hamano <gitster@pobox.com> wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
> > That's still inviting unnecessary emails, isn't it? It would probably
> > be better add the qualification that people should send the email only
> > if they were unable to find any workable replacement. Perhaps:
> >
> >     - send an email to <git@...> to let us know
> >       that you still use this command and were unable
> >       to determine a suitable replacement
>
> In practice, people will respond to such an instruction by always
> sending an e-mail.  Asking others who sound as if they are promising
> to give answers when asked is cheaper than investigating themselves

Thanks for pointing out that my final editing made my suggested
wording too succinct. What I really had in mind -- in conjunction with
Kristoffer's patch [2/4] which provides hint(s) for replacing the
command being retired -- was to reference the provided hints. So,
something like this:

  - send an email to <...> to let us know
    that you still use this command and were unable
    to determine a suitable replacement using the hints
    provided here

Re: [PATCH 1/4] usage: help the user help themselves

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

> command being retired -- was to reference the provided hints. So,
> something like this:
>
>   - send an email to <...> to let us know
>     that you still use this command and were unable
>     to determine a suitable replacement using the hints
>     provided here

Ah, of course, yes, with Kristoffer's update to tell what the
alternative is, your phrasing is perfect.

Thanks.

Re: [PATCH 1/4] usage: help the user help themselves

[Kristoffer Haugsbakk]

On Thu, Aug 28, 2025, at 00:26, Junio C Hamano wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
>
>> command being retired -- was to reference the provided hints. So,
>> something like this:
>>
>>   - send an email to <...> to let us know
>>     that you still use this command and were unable
>>     to determine a suitable replacement using the hints
>>     provided here
>
> Ah, of course, yes, with Kristoffer's update to tell what the
> alternative is, your phrasing is perfect.

I think so too.  Just keep in mind that pack-redundant does not have
that part.

I think I’ll use that suggestion verbatim.

-- 
Kristoffer

Re: [PATCH 2/4] whatchanged: tell users the git-log(1) equivalent

[Kristoffer Haugsbakk]

On Wed, Aug 27, 2025, at 18:29, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>[snip]
> [1]: E.g.,
>     •
> https://lore.kernel.org/git/e1a69dea-bcb6-45fc-83d3-9e50d32c410b@5y5.one/
>     •
> https://lore.kernel.org/git/1011073f-9930-4360-a42f-71eb7421fe3f@chrispalmer.uk/#t
>     •
> https://lore.kernel.org/git/9fcbfcc4-79f9-421f-b9a4-dc455f7db485@acm.org/#t
>     •
> https://lore.kernel.org/git/83241BDE-1E0D-489A-9181-C608E9FCC17B@gmail.com/
> [2] The error message on 2.51.0 does tell them to report it, unconditionally

Missing colon.

> [3]: https://lore.kernel.org/git/20250825085428.GA367101@coredump.intra.peff.net/

I’ll expand on this.

    [3]: You only get different outputs if you happen to have empty
         commits (no changes)[4]
    [4]: https://lore.kernel.org/git/20250825085428.GA367101@coredump.intra.peff.net/

-- 
Kristoffer

Re: [PATCH 1/4] usage: help the user help themselves

[Junio C Hamano]

"Kristoffer Haugsbakk" <code@khaugsbakk.name> writes:

> On Thu, Aug 28, 2025, at 00:26, Junio C Hamano wrote:
>> Eric Sunshine <sunshine@sunshineco.com> writes:
>>
>>> command being retired -- was to reference the provided hints. So,
>>> something like this:
>>>
>>>   - send an email to <...> to let us know
>>>     that you still use this command and were unable
>>>     to determine a suitable replacement using the hints
>>>     provided here
>>
>> Ah, of course, yes, with Kristoffer's update to tell what the
>> alternative is, your phrasing is perfect.
>
> I think so too.  Just keep in mind that pack-redundant does not have
> that part.

For pack-redundant, isn't it because there is no need to find
suitable replacement?  That is, instead of finding a redundant pack,
all of whose objects are contained in some other packs, which
practically is impossible to exist in a non-toy repository, and deal
with it yourself, you can let the normal "repack" to eject redundant
objects from all the non-kept packs.

> I think I’ll use that suggestion verbatim.

Sounds good.

[PATCH v2 0/4] you-still-use-that??: improve breaking changes troubleshooting

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Based on the recent i-still-use-that reports about whatchanged, improve
the error reporting with this command in mind:

1. Give more possible actions instead of just (only) asking them to send
   an email
2. Hint how to replace their git-whatchanged(1) use with git-log(1)
3. Minor documentation changes

Also:[1] an alternative to linking to www.git-scm.com (in patch 1/4) is
to move this document to a regular installed man page:

    gitbreaking-changes(7)

[1]: Not mentioned on the v1 cover letter

§ What the errors now look like

    $ ./git pack-redundant
    'git pack-redundant' is nominated for removal.
    If you still use this command, here's what you can do:

    - read https://git-scm.com/docs/BreakingChanges.html
    - check if anyone has discussed this on the mailing
      list and if they came up with something that can
      help you: https://lore.kernel.org/git/?q=git%20pack-redundant
    - send an email to <git@vger.kernel.org> to let us
      know that you still use this command and were unable
      to determine a suitable replacement

    fatal: refusing to run without --i-still-use-this
    $ ./git whatchanged
    'git whatchanged' is nominated for removal.

    hint: You can replace 'git whatchanged <opts>' with:
        git log <opts> --raw --no-merges

    If you still use this command, here's what you can do:

    - read https://git-scm.com/docs/BreakingChanges.html
    - check if anyone has discussed this on the mailing
      list and if they came up with something that can
      help you: https://lore.kernel.org/git/?q=git%20whatchanged
    - send an email to <git@vger.kernel.org> to let us
      know that you still use this command and were unable
      to determine a suitable replacement

    fatal: refusing to run without --i-still-use-this

§ Changes in v2

These are also posted on the patches.

• Patch 1/4:
  • Change send-an-email bullet point
  • Change the area
  • Use www.git-scm.com, not simply git-scm
• Patch 2/4:
  • Fix whitespace error (I should have used `ci/check-whitespace.sh
    v2.51.0`)
  • Add missing colon (:) to footnote
  • Expand on footnote; a sentence is enough to summarize the difference

Kristoffer Haugsbakk (4):
  you-still-use-that??: help the user help themselves
  whatchanged: tell users the git-log(1) equivalent
  whatchanged: remove not-even-shorter clause
  BreakingChanges: remove claim about whatchanged reports

 Documentation/BreakingChanges.adoc |  2 +-
 Documentation/git-whatchanged.adoc |  8 ++++++--
 builtin/log.c                      |  6 +++++-
 builtin/pack-redundant.c           |  2 +-
 git-compat-util.h                  |  2 +-
 usage.c                            | 33 +++++++++++++++++++++++-------
 6 files changed, 40 insertions(+), 13 deletions(-)

Interdiff against v1:
diff --git a/builtin/log.c b/builtin/log.c
index 2f9e5e5a898..5dbb90c014d 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -542,7 +542,7 @@ int cmd_whatchanged(int argc,
 	opt.revarg_opt = REVARG_COMMITTISH;
 	cmd_log_init(argc, argv, prefix, &rev, &opt, &cfg);
 
-        if (!cfg.i_still_use_this)
+	if (!cfg.i_still_use_this)
 		you_still_use_that("git whatchanged",
 				   _("\n"
 				     "hint: You can replace 'git whatchanged <opts>' with:\n"
diff --git a/usage.c b/usage.c
index c661561b149..7545a616453 100644
--- a/usage.c
+++ b/usage.c
@@ -397,7 +397,9 @@ NORETURN void you_still_use_that(const char *command_name, const char *hint)
 		  "- 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>\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"),
 		percent_encoded.buf);
 	strbuf_release(&percent_encoded);
Range-diff against v1:
1:  e81023edb2d ! 1:  6803e2cc6c3 usage: help the user help themselves
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    usage: help the user help themselves
    +    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.
    @@ Commit message
     
         Also drop “Thanks” since it now would require a new paragraph.
     
    -    [1]: git-scm has a disclaimer for these internal documents that says
    -        that “This information is specific to the Git project”.  That’s
    +    [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.
    +        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>
     
     
      ## Notes (series) ##
    -    An alternative to linking to git-scm is to move this document to a
    -    regular installed man page:
    +    v2:
    +
    +    I had second thoughts about the bullet point about send-an-email.
    +    Change it to the one Eric Sunshine proposed;[1] make sure to spell
    +    out that you can send an email conditioned on not finding a suitable
    +    replacement.
    +
    +    Also change the area to something more pointed.
    +
    +    And also use a clear URL to refer to www.git-scm.com.
    +
    +    [1]: https://lore.kernel.org/git/CAPig+cQkVP57n_FE6dJ0uxvai-J7usxKFp8gzfEbPY=Ytsd6=Q@mail.gmail.com/
    +
    +    • Change send-an-email bullet point
    +    • Change the area
    +    • Use www.git-scm.com, not simply git-scm
    +
    +    v1:
    +
    +    An alternative to linking to www.git-scm.com is to move this document to
    +    a regular installed man page:
     
             gitbreaking-changes(7)
     
    @@ usage.c: void bug_fl(const char *file, int line, const char *fmt, ...)
     +		  "- 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>\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);
2:  5407c0955af ! 2:  2f3ac952980 whatchanged: tell users the git-log(1) equivalent
    @@ Commit message
             • https://lore.kernel.org/git/1011073f-9930-4360-a42f-71eb7421fe3f@chrispalmer.uk/#t
             • https://lore.kernel.org/git/9fcbfcc4-79f9-421f-b9a4-dc455f7db485@acm.org/#t
             • https://lore.kernel.org/git/83241BDE-1E0D-489A-9181-C608E9FCC17B@gmail.com/
    -    [2] The error message on 2.51.0 does tell them to report it, unconditionally
    -    [3]: https://lore.kernel.org/git/20250825085428.GA367101@coredump.intra.peff.net/
    +    [2]: The error message on 2.51.0 does tell them to report it, unconditionally
    +    [3]: You only get different outputs if you happen to have empty
    +         commits (no changes)[4]
    +    [4]: https://lore.kernel.org/git/20250825085428.GA367101@coredump.intra.peff.net/
     
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
    +
    + ## Notes (series) ##
    +    v2:
    +
    +    Review found a whitespace error in the prev. patch version.  I found a
    +    broken footnote and wanted to expand on the last footnote.
    +
    +    • Fix whitespace error (I should have used `ci/check-whitespace.sh
    +      v2.51.0`)
    +    • Add missing colon (:) to footnote
    +    • Expand on footnote; a sentence is enough to summarize the difference
    +
      ## Documentation/git-whatchanged.adoc ##
     @@ Documentation/git-whatchanged.adoc: Shows commit logs and diff output each commit introduces.
      
    @@ Documentation/git-whatchanged.adoc: Shows commit logs and diff output each commi
     
      ## builtin/log.c ##
     @@ builtin/log.c: int cmd_whatchanged(int argc,
    - 	opt.revarg_opt = REVARG_COMMITTISH;
      	cmd_log_init(argc, argv, prefix, &rev, &opt, &cfg);
      
    --	if (!cfg.i_still_use_this)
    + 	if (!cfg.i_still_use_this)
     -		you_still_use_that("git whatchanged");
    -+        if (!cfg.i_still_use_this)
     +		you_still_use_that("git whatchanged",
     +				   _("\n"
     +				     "hint: You can replace 'git whatchanged <opts>' with:\n"
    @@ usage.c: NORETURN void you_still_use_that(const char *command_name)
      		  "- read https://git-scm.com/docs/BreakingChanges.html\n"
      		  "- check if anyone has discussed this on the mailing\n"
     @@ usage.c: NORETURN void you_still_use_that(const char *command_name)
    - 		  "  help you: https://lore.kernel.org/git/?q=%s\n"
    - 		  "- send an email to <git@vger.kernel.org>\n"
    + 		  "  know that you still use this command and were unable\n"
    + 		  "  to determine a suitable replacement\n"
      		  "\n"),
     -		command_name, percent_encoded.buf);
     +		percent_encoded.buf);
3:  5fad164d7d1 = 3:  a074e7be422 whatchanged: remove not-even-shorter clause
4:  f1bf0ea3846 = 4:  9196c3c7e33 BreakingChanges: remove claim about whatchanged reports

base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
-- 
2.51.0.16.gcd94ab5bf81

[PATCH v2 1/4] you-still-use-that??: help the user help themselves

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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>
---

Notes (series):
    v2:
    
    I had second thoughts about the bullet point about send-an-email.
    Change it to the one Eric Sunshine proposed;[1] make sure to spell
    out that you can send an email conditioned on not finding a suitable
    replacement.
    
    Also change the area to something more pointed.
    
    And also use a clear URL to refer to www.git-scm.com.
    
    [1]: https://lore.kernel.org/git/CAPig+cQkVP57n_FE6dJ0uxvai-J7usxKFp8gzfEbPY=Ytsd6=Q@mail.gmail.com/
    
    • Change send-an-email bullet point
    • Change the area
    • Use www.git-scm.com, not simply git-scm
    
    v1:
    
    An alternative to linking to www.git-scm.com is to move this document to
    a regular installed man page:
    
        gitbreaking-changes(7)
    
    What do you think?
    
    I would then have to base my topic on the in-flight
    pw/3.0-commentchar-auto-deprecation, which in turn depends on
    ps/config-wo-the-repository.
    
    Or just wait a bit for these to settle in.

 usage.c | 23 ++++++++++++++++++-----
 1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/usage.c b/usage.c
index 81913236a4a..35dc57eb07e 100644
--- 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"));
 }
-- 
2.51.0.16.gcd94ab5bf81

[PATCH v2 2/4] whatchanged: tell users the git-log(1) equivalent

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

There have been quite a few `--i-still-use-this` user reports since Git
2.51.0 was released.[1][2]  And it doesn’t seem like they are reading
the man page about the git-log(1) equivalent.

Tell them what options to plug into git-log(1).  That template produces
almost the same output[3] and is arguably a plug-in replacement.
Concretely, add an optional `hint` argument so that we can use it right
after the initial error line.

Also mention the same concrete options in the documentation while we’re
at it.

[1]: E.g.,
    • https://lore.kernel.org/git/e1a69dea-bcb6-45fc-83d3-9e50d32c410b@5y5.one/
    • https://lore.kernel.org/git/1011073f-9930-4360-a42f-71eb7421fe3f@chrispalmer.uk/#t
    • https://lore.kernel.org/git/9fcbfcc4-79f9-421f-b9a4-dc455f7db485@acm.org/#t
    • https://lore.kernel.org/git/83241BDE-1E0D-489A-9181-C608E9FCC17B@gmail.com/
[2]: The error message on 2.51.0 does tell them to report it, unconditionally
[3]: You only get different outputs if you happen to have empty
     commits (no changes)[4]
[4]: https://lore.kernel.org/git/20250825085428.GA367101@coredump.intra.peff.net/

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    
    Review found a whitespace error in the prev. patch version.  I found a
    broken footnote and wanted to expand on the last footnote.
    
    • Fix whitespace error (I should have used `ci/check-whitespace.sh
      v2.51.0`)
    • Add missing colon (:) to footnote
    • Expand on footnote; a sentence is enough to summarize the difference

 Documentation/git-whatchanged.adoc |  6 +++++-
 builtin/log.c                      |  6 +++++-
 builtin/pack-redundant.c           |  2 +-
 git-compat-util.h                  |  2 +-
 usage.c                            | 14 ++++++++++----
 5 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-whatchanged.adoc b/Documentation/git-whatchanged.adoc
index d21484026fe..e71d2aa2d27 100644
--- a/Documentation/git-whatchanged.adoc
+++ b/Documentation/git-whatchanged.adoc
@@ -24,7 +24,11 @@ Shows commit logs and diff output each commit introduces.
 
 New users are encouraged to use linkgit:git-log[1] instead.  The
 `whatchanged` command is essentially the same as linkgit:git-log[1]
-but defaults to showing the raw format diff output and skipping merges.
+but defaults to showing the raw format diff output and skipping merges:
+
+----
+git log --raw --no-merges
+----
 
 The command is primarily kept for historical reasons; fingers of
 many people who learned Git long before `git log` was invented by
diff --git a/builtin/log.c b/builtin/log.c
index c2f8bbf8630..5dbb90c014d 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -543,7 +543,11 @@ int cmd_whatchanged(int argc,
 	cmd_log_init(argc, argv, prefix, &rev, &opt, &cfg);
 
 	if (!cfg.i_still_use_this)
-		you_still_use_that("git whatchanged");
+		you_still_use_that("git whatchanged",
+				   _("\n"
+				     "hint: You can replace 'git whatchanged <opts>' with:\n"
+				     "    git log <opts> --raw --no-merges\n"
+				     "\n"));
 
 	if (!rev.diffopt.output_format)
 		rev.diffopt.output_format = DIFF_FORMAT_RAW;
diff --git a/builtin/pack-redundant.c b/builtin/pack-redundant.c
index fe81c293e3a..5d5ae4afa28 100644
--- a/builtin/pack-redundant.c
+++ b/builtin/pack-redundant.c
@@ -626,7 +626,7 @@ int cmd_pack_redundant(int argc, const char **argv, const char *prefix UNUSED, s
 	}
 
 	if (!i_still_use_this)
-		you_still_use_that("git pack-redundant");
+		you_still_use_that("git pack-redundant", NULL);
 
 	if (load_all_packs)
 		load_all();
diff --git a/git-compat-util.h b/git-compat-util.h
index 9408f463e31..398e0fac4fa 100644
--- a/git-compat-util.h
+++ b/git-compat-util.h
@@ -460,7 +460,7 @@ void warning_errno(const char *err, ...) __attribute__((format (printf, 1, 2)));
 
 void show_usage_if_asked(int ac, const char **av, const char *err);
 
-NORETURN void you_still_use_that(const char *command_name);
+NORETURN void you_still_use_that(const char *command_name, const char *hint);
 
 #ifndef NO_OPENSSL
 #ifdef APPLE_COMMON_CRYPTO
diff --git a/usage.c b/usage.c
index 35dc57eb07e..7545a616453 100644
--- a/usage.c
+++ b/usage.c
@@ -376,7 +376,8 @@ void bug_fl(const char *file, int line, const char *fmt, ...)
 	va_end(ap);
 }
 
-NORETURN void you_still_use_that(const char *command_name)
+
+NORETURN void you_still_use_that(const char *command_name, const char *hint)
 {
 	struct strbuf percent_encoded = STRBUF_INIT;
 	strbuf_add_percentencode(&percent_encoded,
@@ -384,8 +385,13 @@ NORETURN void you_still_use_that(const char *command_name)
 				 STRBUF_ENCODE_SLASH);
 
 	fprintf(stderr,
-		_("'%s' is nominated for removal.\n"
-		  "If you still use this command, here's what you can do:\n"
+		_("'%s' is nominated for removal.\n"), command_name);
+
+	if (hint)
+		fputs(hint, stderr);
+
+	fprintf(stderr,
+		_("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"
@@ -395,7 +401,7 @@ NORETURN void you_still_use_that(const char *command_name)
 		  "  know that you still use this command and were unable\n"
 		  "  to determine a suitable replacement\n"
 		  "\n"),
-		command_name, percent_encoded.buf);
+		percent_encoded.buf);
 	strbuf_release(&percent_encoded);
 	die(_("refusing to run without --i-still-use-this"));
 }
-- 
2.51.0.16.gcd94ab5bf81

[PATCH v2 3/4] whatchanged: remove not-even-shorter clause

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

The closest equivalent is `git log --raw --no-merges`.

Also change to “defaults” (implicit plural).

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-whatchanged.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-whatchanged.adoc b/Documentation/git-whatchanged.adoc
index e71d2aa2d27..436e219b7d0 100644
--- a/Documentation/git-whatchanged.adoc
+++ b/Documentation/git-whatchanged.adoc
@@ -15,7 +15,7 @@ WARNING
 -------
 `git whatchanged` has been deprecated and is scheduled for removal in
 a future version of Git, as it is merely `git log` with different
-default; `whatchanged` is not even shorter to type than `log --raw`.
+defaults.
 
 DESCRIPTION
 -----------
-- 
2.51.0.16.gcd94ab5bf81

[PATCH v2 4/4] BreakingChanges: remove claim about whatchanged reports

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This was written in e836757e14b (whatschanged: list it in
BreakingChanges document, 2025-05-12) which was on the same
topic that added the `--i-still-use-this` requirement.[1]

Maybe it was a work-in-progress comment/status.

[1]: jc/you-still-use-whatchanged

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    Footnote solely to avoid awkward paragraph wrapping...

 Documentation/BreakingChanges.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc
index f8d2eba061c..c4985163c3c 100644
--- a/Documentation/BreakingChanges.adoc
+++ b/Documentation/BreakingChanges.adoc
@@ -235,7 +235,7 @@ These features will be removed.
   equivalent `git log --raw`.  We have nominated the command for
   removal, have changed the command to refuse to work unless the
   `--i-still-use-this` option is given, and asked the users to report
-  when they do so.  So far there hasn't been a single complaint.
+  when they do so.
 +
 The command will be removed.
 
-- 
2.51.0.16.gcd94ab5bf81

Re: [PATCH 1/4] usage: help the user help themselves

[Eric Sunshine]

On Wed, Aug 27, 2025 at 5:27 PM Eric Sunshine <sunshine@sunshineco.com> wrote:
> On Wed, Aug 27, 2025 at 5:20 PM Junio C Hamano <gitster@pobox.com> wrote:
> > Eric Sunshine <sunshine@sunshineco.com> writes:
> > > That's still inviting unnecessary emails, isn't it? It would probably
> > > be better add the qualification that people should send the email only
> > > if they were unable to find any workable replacement. Perhaps:
> > >
> > >     - send an email to <git@...> to let us know
> > >       that you still use this command and were unable
> > >       to determine a suitable replacement
> >
> > In practice, people will respond to such an instruction by always
> > sending an e-mail.  Asking others who sound as if they are promising
> > to give answers when asked is cheaper than investigating themselves
>
> Thanks for pointing out that my final editing made my suggested
> wording too succinct. What I really had in mind -- in conjunction with
> Kristoffer's patch [2/4] which provides hint(s) for replacing the
> command being retired -- was to reference the provided hints. So,
> something like this:
>
>   - send an email to <...> to let us know
>     that you still use this command and were unable
>     to determine a suitable replacement using the hints
>     provided here

I realize that the changes made by this series are not in any released
version yet, but from reading the emails still arriving which argue
for retaining the command for reasons of muscle memory or because of
its (strong) mnemonic value, I suspect that the hint(s) this series
adds may not be complete enough. In particular, the advice this series
adds (use `git log --raw --no-merges`) seems to be primarily aimed at
scripted use of the command. But the muscle memory and mnemonic
arguments suggest that advice should be given for interactive use, as
well, such as proposing that the user can create an alias.

Re: [PATCH 1/4] usage: help the user help themselves

[Kristoffer Haugsbakk]

(Sent from mobile, might have mistakes)

On Wed, Sep 3, 2025, at 18:50, Eric Sunshine wrote:
> I realize that the changes made by this series are not in any released
> version yet, but from reading the emails still arriving which argue
> for retaining the command for reasons of muscle memory or because of
> its (strong) mnemonic value, I suspect that the hint(s) this series
> adds may not be complete enough. In particular, the advice this series
> adds (use `git log --raw --no-merges`) seems to be primarily aimed at
> scripted use of the command. But the muscle memory and mnemonic
> arguments suggest that advice should be given for interactive use, as
> well, such as proposing that the user can create an alias.

Good point. I would suggest discussing it in the 
breaking changes doc under a new "For Users"
section. I would like to avoid expanding the error
message too much due to the already mentioned
fear of overwhelming folks.

I've seen  "troubleshooting" questions from git users
who got one of those long and well-described Hints
like e.g. detached head and default git init branch
when either the msg already spelled eveything out
or the msg was purely informational.

Cheers

Re: [PATCH 1/4] usage: help the user help themselves

[Eric Sunshine]

On Wed, Sep 3, 2025 at 1:54 PM Kristoffer Haugsbakk
<kristofferhaugsbakk@fastmail.com> wrote:
> On Wed, Sep 3, 2025, at 18:50, Eric Sunshine wrote:
> > I realize that the changes made by this series are not in any released
> > version yet, but from reading the emails still arriving which argue
> > for retaining the command for reasons of muscle memory or because of
> > its (strong) mnemonic value, I suspect that the hint(s) this series
> > adds may not be complete enough. In particular, the advice this series
> > adds (use `git log --raw --no-merges`) seems to be primarily aimed at
> > scripted use of the command. But the muscle memory and mnemonic
> > arguments suggest that advice should be given for interactive use, as
> > well, such as proposing that the user can create an alias.
>
> Good point. I would suggest discussing it in the
> breaking changes doc under a new "For Users"
> section. I would like to avoid expanding the error
> message too much due to the already mentioned
> fear of overwhelming folks.

I have doubts that users will consult a document when presented with
the message.

> I've seen  "troubleshooting" questions from git users
> who got one of those long and well-described Hints
> like e.g. detached head and default git init branch
> when either the msg already spelled eveything out
> or the msg was purely informational.

I didn't spell it out above, but what I had in mind was something very
simple... not at all ong and detailed; for instance:

   For interactive use, define a Git alias `git whatchanged`
   which runs `git log --raw --no-merges`.

Re: [PATCH 1/4] usage: help the user help themselves

[Kristoffer Haugsbakk]

On Wed, Sep 3, 2025, at 23:21, Eric Sunshine wrote:
>> I've seen  "troubleshooting" questions from git users
>> who got one of those long and well-described Hints
>> like e.g. detached head and default git init branch
>> when either the msg already spelled eveything out
>> or the msg was purely informational.
>
> I didn't spell it out above, but what I had in mind was something very
> simple... not at all ong and detailed; for instance:
>
>    For interactive use, define a Git alias `git whatchanged`
>    which runs `git log --raw --no-merges`.

But that won’t work since git-whatchanged(1) is a builtin and you cannot
use an alias to shadow a builtin.  Now you can suggest minor variations
like `whatchange`.  But then people will go back to talking about their
finger memory.[1][2][3]

You would need Peff’s:

https://lore.kernel.org/git/20250830022718.GB567900@coredump.intra.peff.net/

> I wonder if we should loosen the "aliases cannot override builtins" rule
> for deprecated commands. Perhaps something like the patch below.

† 1: If people are adamant about a command staying exactly as it is for
    interactive use, I don’t imagine their tolerance for a slightly
    different invocation will be much higher.
† 2: And I wonder about the audience who has been using a command which
    was deprecated for twelve years who also need to be reminded about
    aliases.
† 3: But there is one `whatchange` conversion: https://lore.kernel.org/git/CAAn3O_2iHVt5TctvwLLSXm5Nw2wS8e9Xk0is1=k=-qRS=gHVMQ@mail.gmail.com/

-- 
Kristoffer Haugsbakk

Re: [PATCH 1/4] usage: help the user help themselves

[Jeff King]

On Wed, Sep 03, 2025 at 05:21:47PM -0400, Eric Sunshine wrote:

> > I've seen  "troubleshooting" questions from git users
> > who got one of those long and well-described Hints
> > like e.g. detached head and default git init branch
> > when either the msg already spelled eveything out
> > or the msg was purely informational.
> 
> I didn't spell it out above, but what I had in mind was something very
> simple... not at all ong and detailed; for instance:
> 
>    For interactive use, define a Git alias `git whatchanged`
>    which runs `git log --raw --no-merges`.

I think that is good advice, but... it won't do anything until we
actually drop the whatchanged command, since until then we'll refuse to
override the command (even the crippled --i-still-use-this one).

We'd need something like the patch here:

  https://lore.kernel.org/git/20250830022718.GB567900@coredump.intra.peff.net/

-Peff

Re: [PATCH 1/4] usage: help the user help themselves

[Eric Sunshine]

On Wed, Sep 3, 2025 at 5:44 PM Jeff King <peff@peff.net> wrote:
> On Wed, Sep 03, 2025 at 05:21:47PM -0400, Eric Sunshine wrote:
> > > I've seen  "troubleshooting" questions from git users
> > > who got one of those long and well-described Hints
> > > like e.g. detached head and default git init branch
> > > when either the msg already spelled eveything out
> > > or the msg was purely informational.
> >
> > I didn't spell it out above, but what I had in mind was something very
> > simple... not at all ong and detailed; for instance:
> >
> >    For interactive use, define a Git alias `git whatchanged`
> >    which runs `git log --raw --no-merges`.
>
> I think that is good advice, but... it won't do anything until we
> actually drop the whatchanged command, since until then we'll refuse to
> override the command (even the crippled --i-still-use-this one).
>
> We'd need something like the patch here:
>
>   https://lore.kernel.org/git/20250830022718.GB567900@coredump.intra.peff.net/

Indeed. I saw your patch in the other thread and had it in mind when
composing my earlier email, even though I didn't specifically mention
it (though I probably should have) since I was more focused on raising
the point that -- given the recent spate of muscle-memory /
mnemonic-value argument emails -- the existing hints in Kristoffer's
patch series may be insufficient to quell future emails.

Re: [PATCH 1/4] usage: help the user help themselves

[Kristoffer Haugsbakk]

On Thu, Sep 4, 2025, at 00:11, Eric Sunshine wrote:
> , even though I didn't specifically mention it (though I probably
> should have)

I thought Sunshine was supposed to illuminate.

Re: [PATCH 1/4] usage: help the user help themselves

[Jeff King]

On Wed, Sep 03, 2025 at 06:11:30PM -0400, Eric Sunshine wrote:

> > > I didn't spell it out above, but what I had in mind was something very
> > > simple... not at all ong and detailed; for instance:
> > >
> > >    For interactive use, define a Git alias `git whatchanged`
> > >    which runs `git log --raw --no-merges`.
> >
> > I think that is good advice, but... it won't do anything until we
> > actually drop the whatchanged command, since until then we'll refuse to
> > override the command (even the crippled --i-still-use-this one).
> >
> > We'd need something like the patch here:
> >
> >   https://lore.kernel.org/git/20250830022718.GB567900@coredump.intra.peff.net/
> 
> Indeed. I saw your patch in the other thread and had it in mind when
> composing my earlier email, even though I didn't specifically mention
> it (though I probably should have) since I was more focused on raising
> the point that -- given the recent spate of muscle-memory /
> mnemonic-value argument emails -- the existing hints in Kristoffer's
> patch series may be insufficient to quell future emails.

Heh, I should have figured. I didn't see any response in that thread, so
this was my attempt to pawn it off on folks who are more interested in
the topic (and working on the advice half). ;)

-Peff