name-rev: make --stdin hidden

PATCH In review John Cai via GitGitGadget 5 participants 9 messages Mar 8, 2022 – May 6, 2023 Documentation

lore

Share & tools

lore

John Cai via GitGitGadget

author

2022-03-08 21:24 UTC #0 lore raw

PATCH 1/1 name-rev: make --stdin hidden

From: John Cai <[email protected]>

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" <[email protected]>

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

Documentation/git-name-rev.txt +2 -6

index ec8a27ce8bf..5f196c03708 100644
@@ -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

@@ -107,7 +103,7 @@ Now you are wiser, because you know that it happened 940 revisions before v0.99.
 Another nice thing you can do is:
 
 ------------
-% git log | git name-rev --stdin
+% git log | git name-rev --annotate-stdin
 ------------
 
 GIT

builtin/name-rev.c +5 -1

index 929591269dd..2389e7f752d 100644
@@ -538,7 +538,11 @@ int cmd_name_rev(int argc, const char **argv, const char *prefix)
 				   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_F(0,
+			   "stdin",
+			   &transform_stdin,
+			   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)")),
 		OPT_BOOL(0, "always",     &always,

base-commit: c2162907e9aa884bdb70208389cb99b181620d51

Signature · 1 line

gitgitgadget

Junio C Hamano

2022-03-09 18:55 UTC #1 lore raw

Quoted 6 lines · John Cai via GitGitGadget

From: John Cai <[email protected]>
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.

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.

John Cai

2022-03-09 19:21 UTC #2 lore raw

Hi Junio

Quoted 4 lines · Junio C Hamano

Quoted 2 lines · John Cai via GitGitGadget
From: John Cai <[email protected]>

Quoted 8 lines

Quoted 4 lines
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.
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?

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

Quoted 2 lines

Thanks.

John Cai via GitGitGadget

author

2023-05-05 19:17 UTC #3 lore raw

PATCH v2 1/1 name-rev: make --stdin hidden

In reply to John Cai via GitGitGadget

From: John Cai <[email protected]>

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

Signed-off-by "John Cai" <[email protected]>

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

Documentation/git-name-rev.txt +2 -6

index ec8a27ce8bf..5f196c03708 100644
@@ -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

@@ -107,7 +103,7 @@ Now you are wiser, because you know that it happened 940 revisions before v0.99.
 Another nice thing you can do is:
 
 ------------
-% git log | git name-rev --stdin
+% git log | git name-rev --annotate-stdin
 ------------
 
 GIT

builtin/name-rev.c +5 -1

index 593f0506a10..4d15a23fc4d 100644
@@ -573,7 +573,11 @@ int cmd_name_rev(int argc, const char **argv, const char *prefix)
 				   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_F(0,
+			   "stdin",
+			   &transform_stdin,
+			   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)")),
 		OPT_BOOL(0, "always",     &always,

base-commit: 69c786637d7a7fe3b2b8f7d989af095f5f49c3a8

Signature · 1 line

gitgitgadget

Eric Sunshine

2023-05-05 19:32 UTC #4 lore raw

Quoted 7 lines · John Cai via GitGitGadget

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.

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.

Quoted 1 line

Signed-off-by "John Cai" <[email protected]>

Junio C Hamano

2023-05-05 19:37 UTC #5 lore raw

In reply to John Cai via GitGitGadget

Quoted 10 lines · John Cai via GitGitGadget

From: John Cai <[email protected]>
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.

Quoted 8 lines

Signed-off-by "John Cai" <[email protected]>
---
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.

Quoted 2 lines

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

Quoted 16 lines

      +			   PARSE_OPT_HIDDEN),

Documentation/git-name-rev.txt +1 -1

index ec8a27ce8bf..5f196c03708 100644
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [verse]
 'git name-rev' [--tags] [--refs=<pattern>]
-	       ( --all | --stdin | <commit-ish>... )
+	       ( --all | --annotate-stdin | <commit-ish>... )
 
 DESCRIPTION
 -----------

Documentation/git-name-rev.txt The full name after substitution is master, · line 75

Quoted 10 lines

Documentation/git-name-rev.txt +0 -4

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

Documentation/git-name-rev.txt +2 -1

index 5f196c0370..1173deae57 100644
@@ -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:
 +

John Cai

2023-05-05 21:44 UTC #6 lore raw

Hi Junio,

Quoted 61 lines · Junio C Hamano

Quoted 10 lines · John Cai via GitGitGadget
From: John Cai <[email protected]>
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.
Quoted 8 lines
Signed-off-by "John Cai" <[email protected]>
---
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.
Quoted 2 lines
-+ 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.
Quoted 16 lines
      +			   PARSE_OPT_HIDDEN),
Documentation/git-name-rev.txt +1 -1
index ec8a27ce8bf..5f196c03708 100644
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [verse]
 'git name-rev' [--tags] [--refs=<pattern>]
-	       ( --all | --stdin | <commit-ish>... )
+	       ( --all | --annotate-stdin | <commit-ish>... )
 
 DESCRIPTION
 -----------
Documentation/git-name-rev.txt The full name after substitution is master, · line 75
Quoted 10 lines
Documentation/git-name-rev.txt +0 -4
@@ -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.

Quoted 5 lines

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.

Yeah, that's valid.

Quoted 11 lines

Will queue as is. Thanks.
 Documentation/git-name-rev.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/git-name-rev.txt +0 -0
index 5f196c0370..1173deae57 100644

Documentation/git-name-rev.txt OPTIONS · line 53

Quoted 9 lines

Documentation/git-name-rev.txt +2 -1

@@ -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:
 +

Sounds good to me. Will add this in

thanks!
John

John Cai via GitGitGadget

author

2023-05-06 04:14 UTC #7 lore raw

PATCH v3 1/1 name-rev: make --stdin hidden

In reply to John Cai via GitGitGadget

From: John Cai <[email protected]>

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

Signed-off-by "John Cai" <[email protected]>

---
name-rev: make --stdin hidden

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

Documentation/git-name-rev.txt +4 -7

index ec8a27ce8bf..5c56c870253 100644
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [verse]
 'git name-rev' [--tags] [--refs=<pattern>]
-	       ( --all | --stdin | <commit-ish>... )
+	       ( --all | --annotate-stdin | <commit-ish>... )
 
 DESCRIPTION
 -----------

@@ -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:
 +

@@ -70,10 +71,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

@@ -107,7 +104,7 @@ Now you are wiser, because you know that it happened 940 revisions before v0.99.
 Another nice thing you can do is:
 
 ------------
-% git log | git name-rev --stdin
+% git log | git name-rev --annotate-stdin
 ------------
 
 GIT

builtin/name-rev.c +5 -1

index 593f0506a10..4d15a23fc4d 100644
@@ -573,7 +573,11 @@ int cmd_name_rev(int argc, const char **argv, const char *prefix)
 				   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_F(0,
+			   "stdin",
+			   &transform_stdin,
+			   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)")),
 		OPT_BOOL(0, "always",     &always,

base-commit: 69c786637d7a7fe3b2b8f7d989af095f5f49c3a8

Signature · 1 line

gitgitgadget

Teng Long

2023-05-06 12:38 UTC #8 lore raw

PATCH v2 1/1 name-rev: make --stdin hidden

In reply to John Cai via GitGitGadget

Quoted 9 lines · John Cai

builtin/name-rev.c +5 -1
-		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"),
+			   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)")),
OPT_BOOL(0, "always", &always,

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

Thanks.