{"thread":{"id":"61835","subject":"[PATCH 1/1] show-ref: improve short help messages of options","startedAt":"2024-07-24T11:11:42Z","lastAt":"2024-07-26T15:46:37Z","messageCount":5,"participants":["Alexander Shopov","Patrick Steinhardt","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":1},"messages":[{"id":"499250","messageId":"20240724111116.91615-1-ash@kambanaria.org","threadId":"61835","inReplyTo":null,"subject":"[PATCH 1/1] show-ref: improve short help messages of options","fromName":"Alexander Shopov","fromEmail":"ash@kambanaria.org","sentAt":"2024-07-24T11:11:11Z","receivedAt":"2024-07-24T11:11:42Z","isPatch":true,"sender":{"key":"ash@kambanaria.org","avatar":"https://avatars.githubusercontent.com/u/449359?v=4"},"body":"Trivial change to indicate that branches and tags are real options\nthat can be used combined to get more information. This helps with\nlinting translations and prompting the user that the terms represent\noptions.\n\nSigned-off-by: Alexander Shopov \n---\n builtin/show-ref.c | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/show-ref.c b/builtin/show-ref.c\nindex 839a5c29f3..85700caae9 100644\n--- a/builtin/show-ref.c\n+++ b/builtin/show-ref.c\n@@ -293,8 +293,8 @@ int cmd_show_ref(int argc, const char **argv, const char *prefix)\n \tstruct show_one_options show_one_opts = {0};\n \tint verify = 0, exists = 0;\n \tconst struct option show_ref_options[] = {\n-\t\tOPT_BOOL(0, \"tags\", &patterns_opts.tags_only, N_(\"only show tags (can be combined with branches)\")),\n-\t\tOPT_BOOL(0, \"branches\", &patterns_opts.branches_only, N_(\"only show branches (can be combined with tags)\")),\n+\t\tOPT_BOOL(0, \"tags\", &patterns_opts.tags_only, N_(\"only show tags (can be combined with --branches)\")),\n+\t\tOPT_BOOL(0, \"branches\", &patterns_opts.branches_only, N_(\"only show branches (can be combined with --tags)\")),\n \t\tOPT_HIDDEN_BOOL(0, \"heads\", &patterns_opts.branches_only,\n \t\t\t\tN_(\"deprecated synonym for --branches\")),\n \t\tOPT_BOOL(0, \"exists\", &exists, N_(\"check for reference existence without resolving\")),\n-- \n2.45.2\n\n"},{"id":"499312","messageId":"ZqH7mDh73vkX4bPT@tanuki","threadId":"61835","inReplyTo":"20240724111116.91615-1-ash@kambanaria.org","subject":"Re: [PATCH 1/1] show-ref: improve short help messages of options","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-07-25T07:15:36Z","receivedAt":"2024-07-25T07:15:41Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Wed, Jul 24, 2024 at 02:11:11PM +0300, Alexander Shopov wrote:\n> diff --git a/builtin/show-ref.c b/builtin/show-ref.c\n> index 839a5c29f3..85700caae9 100644\n> --- a/builtin/show-ref.c\n> +++ b/builtin/show-ref.c\n> @@ -293,8 +293,8 @@ int cmd_show_ref(int argc, const char **argv, const char *prefix)\n> \tstruct show_one_options show_one_opts = {0};\n> \tint verify = 0, exists = 0;\n> \tconst struct option show_ref_options[] = {\n> -\t\tOPT_BOOL(0, \"tags\", &patterns_opts.tags_only, N_(\"only show tags (can be combined with branches)\")),\n> -\t\tOPT_BOOL(0, \"branches\", &patterns_opts.branches_only, N_(\"only show branches (can be combined with tags)\")),\n> +\t\tOPT_BOOL(0, \"tags\", &patterns_opts.tags_only, N_(\"only show tags (can be combined with --branches)\")),\n> +\t\tOPT_BOOL(0, \"branches\", &patterns_opts.branches_only, N_(\"only show branches (can be combined with --tags)\")),\n> \t\tOPT_HIDDEN_BOOL(0, \"heads\", &patterns_opts.branches_only,\n> \t\t\t\tN_(\"deprecated synonym for --branches\")),\n> \t\tOPT_BOOL(0, \"exists\", &exists, N_(\"check for reference existence without resolving\")),\n\nAgreed, I think that this is a sensible change. In practice, this\nfeature can also be combined with `--head`, so in that spirit we might\neven change it to:\n\n \"only show tags (can be combined with --branches and --head)\"\n\nNot sure though whether this is getting too noisy?\n\nPatrick\n"},{"id":"499346","messageId":"xmqqr0bhldjp.fsf@gitster.g","threadId":"61835","inReplyTo":"ZqH7mDh73vkX4bPT@tanuki","subject":"Re: [PATCH 1/1] show-ref: improve short help messages of options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-25T15:03:06Z","receivedAt":"2024-07-25T15:03:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> Agreed, I think that this is a sensible change. In practice, this\n> feature can also be combined with `--head`, so in that spirit we might\n> even change it to:\n>\n> \"only show tags (can be combined with --branches and --head)\"\n>\n> Not sure though whether this is getting too noisy?\n\nIt is somewhat an oxymoron that \"*only* show X\" can be combined with\n\"*only* show Y\" in the first place.\n\nFor a reader to accept it without finding it awkward, the reader\nmust understand that\n\n (1) the command shows by default everything, but\n\n (2) if any of these \"only show\" options are given, the command\n stops showing everything and the user can pick which subset of\n \"only show\" options to give, which work additively.\n\nBut if the reader knows that much already, it is redundant to say\n\"can be combined with\", isn't it?\n\nSo, I dunno.\n"},{"id":"499438","messageId":"ZqOWUrynjUN2A5TM@tanuki","threadId":"61835","inReplyTo":"xmqqr0bhldjp.fsf@gitster.g","subject":"Re: [PATCH 1/1] show-ref: improve short help messages of options","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-07-26T12:28:02Z","receivedAt":"2024-07-26T12:28:29Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Thu, Jul 25, 2024 at 08:03:06AM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt writes:\n> \n> > Agreed, I think that this is a sensible change. In practice, this\n> > feature can also be combined with `--head`, so in that spirit we might\n> > even change it to:\n> >\n> > \"only show tags (can be combined with --branches and --head)\"\n> >\n> > Not sure though whether this is getting too noisy?\n> \n> It is somewhat an oxymoron that \"*only* show X\" can be combined with\n> \"*only* show Y\" in the first place.\n\nYeah, this is the root of the problem why those braces are required in\nthe first place. But that being said, the option is somewhat funny\nbecause it indeed limits what we show to only show tags. The fact that\nit can be combined with other options to expand on what it shows doesn't\nchange that, so I think \"only\" is okay-ish even though it certainly is\nnot perfect.\n\n> For a reader to accept it without finding it awkward, the reader\n> must understand that\n> \n> (1) the command shows by default everything, but\n> \n> (2) if any of these \"only show\" options are given, the command\n> stops showing everything and the user can pick which subset of\n> \"only show\" options to give, which work additively.\n> \n> But if the reader knows that much already, it is redundant to say\n> \"can be combined with\", isn't it?\n\nHum. I personally find the way that this is worded intuitive and think\nthat I would find it helpful when reading it as a less-knowledgeable\nuser. But naturally, I'm quite biased and may be too unimaginative to\ncome up with a better wording.\n\nMeanwhile, I think that the proposed change strictly improves this\nmessage and thus don't see a reason not to take it. Unless we see\nsomebody come up with a less-awkward solution, that is.\n\nPatrick\n"},{"id":"499452","messageId":"xmqqle1oxijr.fsf@gitster.g","threadId":"61835","inReplyTo":"ZqOWUrynjUN2A5TM@tanuki","subject":"Re: [PATCH 1/1] show-ref: improve short help messages of options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-26T15:46:32Z","receivedAt":"2024-07-26T15:46:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> Meanwhile, I think that the proposed change strictly improves this\n> message and thus don't see a reason not to take it. Unless we see\n> somebody come up with a less-awkward solution, that is.\n\nOh, that part is uncontroversial.\n\nThe wording without double-dashes has been with us forever since the\ncommand was updated to use the parse-options API by 69932bc6\n(show-ref: migrate to parse-options, 2009-06-20), and so far nobody\ncomplained about it, so while \"strictly improves\" may be true (i.e.\nthe delta may not be negative), the degree of improvement may not be\nall that much to be worth the combined brain cycles we are spending\non this topic. Taking the patch would not make the future work any\nharder to truly improve it further, so I do not see any reason not\nto take it.\n\nThanks.\n\n\n\n"}]}