On Tue, Jan 4, 2022 at 10:32 AM Philip Oakley [off-list ref] wrote:

On 03/01/2022 14:47, John Cai via GitGitGadget wrote:

quoted

From: John Cai <redacted>
 --stdin::
+     This option is deprecated in favor of 'git name-rev --annotate-stdin'.
+     They are functionally equivalent.
+
+--annotate-stdin::
      Transform stdin by substituting all the 40-character SHA-1
      hexes (say $hex) with "$hex ($rev_name)".  When used with
      --name-only, substitute with "$rev_name", omitting $hex
-     altogether.  Intended for the scripter's use.
+     altogether.

Is there a preferred order for the old/new variant documentation?

It struck me that the docs should offer the new (now 'correct') variant
first.

I didn't see anything about deprecation in the CodingGuidlines or
SubmittingPatches (only a quick search though)

In other cases, we've demoted the deprecated option to a tiny blurb at
the end of the description of the option which replaces it so that the
deprecated option is no longer given a place of prominence but can
still be found with a search in case someone runs across it somewhere
and wants to learn about it.

    --annotate-stdin::
        Transform stdin by substituting all the 40-character SHA-1
        hexes (say $hex) with "$hex ($rev_name)".  When used with
        --name-only, substitute with "$rev_name", omitting $hex
        altogether. --stdin is a deprecated synonym.