patchname-rev: make --stdin hidden

From: John Cai <johncai86@gmail.com>

In 34ae3b70 (name-rev: deprecate --stdin in favor of --annotate-stdin), we renamed --stdin to --annotate-stdin for the sake of a clearer name for the option, and added text that indicates --stdin is deprecated. The next step is to hide --stdin completely.

Make the option hidden. Also, update documentation to remove all mentions of --stdin.

Signed-off-by: "John Cai" <johncai86@gmail.com>
---
    name-rev: make --stdin hidden
    
    The next step of replacing name-rev --stdin with --annotate-stdin is to
    make --stdin hidden. This patch also updates documentation to get rid of
    any mention of --stdin.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1225%2Fjohn-cai%2Fjc%2Fhide-name-rev-stdin-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1225/john-cai/jc/hide-name-rev-stdin-v1
Pull-Request: https://github.com/git/git/pull/1225

 Documentation/git-name-rev.txt | 8 ++------
 builtin/name-rev.c             | 6 +++++-
 2 files changed, 7 insertions(+), 7 deletions(-)

"John Cai via GitGitGadget" <gitgitgadget@gmail.com> writes:

May be. As 34ae3b70 is not even in any released version yet, it is a bit premature to talk about "The next step". Perhaps hold onto this change for a few releases?

Thanks.

Hi Junio

On 9 Mar 2022, at 13:55, Junio C Hamano wrote:

Sounds good. I may have been over-eager :)

From: John Cai <johncai86@gmail.com>

In 34ae3b70 (name-rev: deprecate --stdin in favor of --annotate-stdin), we renamed --stdin to --annotate-stdin for the sake of a clearer name for the option, and added text that indicates --stdin is deprecated. The next step is to hide --stdin completely.

Make the option hidden. Also, update documentation to remove all mentions of --stdin.

Signed-off-by: "John Cai" <johncai86@gmail.com>
---
    name-rev: make --stdin hidden
    
    Now that --stdin has been deprecated for several releases, the next step
    of replacing name-rev --stdin with --annotate-stdin is to make --stdin
    hidden. This patch also updates documentation to get rid of any mention
    of --stdin.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1225%2Fjohn-cai%2Fjc%2Fhide-name-rev-stdin-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1225/john-cai/jc/hide-name-rev-stdin-v2
Pull-Request: https://github.com/git/git/pull/1225

Range-diff vs v1:

 1:  32c8db2f03a ! 1:  904cd2c3572 name-rev: make --stdin hidden
     @@ builtin/name-rev.c: int cmd_name_rev(int argc, const char **argv, const char *pr
       				   N_("ignore refs matching <pattern>")),
       		OPT_GROUP(""),
       		OPT_BOOL(0, "all", &all, N_("list all commits reachable from all refs")),
     --		OPT_BOOL(0, "stdin", &transform_stdin, N_("deprecated: use annotate-stdin instead")),
     +-		OPT_BOOL(0, "stdin", &transform_stdin, N_("deprecated: use --annotate-stdin instead")),
      +		OPT_BOOL_F(0,
      +			   "stdin",
      +			   &transform_stdin,
     -+			   N_("deprecated: use annotate-stdin instead"),
     ++			   N_("deprecated: use --annotate-stdin instead"),
      +			   PARSE_OPT_HIDDEN),
       		OPT_BOOL(0, "annotate-stdin", &annotate_stdin, N_("annotate text from stdin")),
       		OPT_BOOL(0, "undefined", &allow_undefined, N_("allow to print `undefined` names (default)")),

 Documentation/git-name-rev.txt | 8 ++------
 builtin/name-rev.c             | 6 +++++-
 2 files changed, 7 insertions(+), 7 deletions(-)

On Fri, May 5, 2023 at 3:19 PM John Cai via GitGitGadget <gitgitgadget@gmail.com> wrote:

Eradicating all mention of --stdin from the documentation makes it more hostile for end-users, doesn't it? If someone runs across --stdin in a blog post or in some in-the-wild script, then this makes it more difficult to learn what the option does. In other such cases, rather than purging all mention from documentation, we've instead mentioned the deprecated option only as a minor aside of the option which replaces it. For instance:

    --annotate-stdin::
        Transform stdin by ... omitting $hex altogether.
        `--stdin` is a deprecated synonym.

"John Cai via GitGitGadget" <gitgitgadget@gmail.com> writes:

Nice.  It has been a year, and I agree that it is about time.

Thanks for not forgetting about the topic.

And of course this one is a very nice touch, relative to the previous round.

I agree with the main thrust of the change, but I am not sure if it is a good idea to "completely" remove the mention.

Even after we stop talking about it, people find old scriptlets that use "name-rev --stdin" from various random places on the Internet, and wonder if they are buggy. I wonder if having something like this for a year or two may help? We would need to scan for "was called" and decide to clean them up once in a while, of course.

Will queue as is.  Thanks.

 Documentation/git-name-rev.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

Hi Junio,

On 5 May 2023, at 15:37, Junio C Hamano wrote:

Yeah, that's valid.

Sounds good to me. Will add this in

thanks! John

From: John Cai <johncai86@gmail.com>

In 34ae3b70 (name-rev: deprecate --stdin in favor of --annotate-stdin), we renamed --stdin to --annotate-stdin for the sake of a clearer name for the option, and added text that indicates --stdin is deprecated. The next step is to hide --stdin completely.

Make the option hidden. Also, update documentation to remove all mentions of --stdin.

Signed-off-by: "John Cai" <johncai86@gmail.com>
---
    name-rev: make --stdin hidden
    
    Now that --stdin has been deprecated for several releases, the next step
    of replacing name-rev --stdin with --annotate-stdin is to make --stdin
    hidden. This patch also updates documentation to get rid of any mention
    of --stdin.
    
    Changes since v2:
    
     * Added a reference to --stdin in the docs

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1225%2Fjohn-cai%2Fjc%2Fhide-name-rev-stdin-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1225/john-cai/jc/hide-name-rev-stdin-v3
Pull-Request: https://github.com/git/git/pull/1225

Range-diff vs v2:

 1:  904cd2c3572 ! 1:  dbba7c4373b name-rev: make --stdin hidden
     @@ Documentation/git-name-rev.txt: SYNOPSIS
       
       DESCRIPTION
       -----------
     +@@ Documentation/git-name-rev.txt: OPTIONS
     + 	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.
     ++	altogether. This option was called `--stdin` in older versions
     ++	of Git.
     + +
     + For example:
     + +
      @@ Documentation/git-name-rev.txt: The full name after substitution is master,
       while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
       -----------

 Documentation/git-name-rev.txt | 11 ++++-------
 builtin/name-rev.c             |  6 +++++-
 2 files changed, 9 insertions(+), 8 deletions(-)

 John Cai <johncai86@gmail.com> writes:

It seems like there is an odd indent before "&always", of course, it's not introduced by this patch.

Thanks.