Re: [PATCH v2] name-rev: make --stdin hidden

[Junio C Hamano <gitster@pobox.com>]

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

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

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

Thanks for not forgetting about the topic.

>      -+			   N_("deprecated: use annotate-stdin instead"),
>      ++			   N_("deprecated: use --annotate-stdin instead"),

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

>       +			   PARSE_OPT_HIDDEN),

> diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt
> index ec8a27ce8bf..5f196c03708 100644
> --- a/Documentation/git-name-rev.txt
> +++ b/Documentation/git-name-rev.txt
> @@ -10,7 +10,7 @@ SYNOPSIS
>  --------
>  [verse]
>  'git name-rev' [--tags] [--refs=<pattern>]
> -	       ( --all | --stdin | <commit-ish>... )
> +	       ( --all | --annotate-stdin | <commit-ish>... )
>  
>  DESCRIPTION
>  -----------
> @@ -70,10 +70,6 @@ The full name after substitution is master,
>  while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
>  -----------
>  
> ---stdin::
> -	This option is deprecated in favor of 'git name-rev --annotate-stdin'.
> -	They are functionally equivalent.
> -
>  --name-only::
>  	Instead of printing both the SHA-1 and the name, print only
>  	the name.  If given with --tags the usual tag prefix of

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

diff --git c/Documentation/git-name-rev.txt w/Documentation/git-name-rev.txt
index 5f196c0370..1173deae57 100644
--- c/Documentation/git-name-rev.txt
+++ w/Documentation/git-name-rev.txt
@@ -46,7 +46,8 @@ 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:
 +