{"thread":{"id":"40212","subject":"[PATCH] show-ref: place angle brackets around variables in usage string","startedAt":"2015-08-29T04:18:44Z","lastAt":"2015-08-31T16:33:07Z","messageCount":5,"participants":["Alex Henrie","Philip Oakley","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"268882","messageId":"1440821924-4289-1-git-send-email-alexhenrie24@gmail.com","threadId":"40212","inReplyTo":null,"subject":"[PATCH] show-ref: place angle brackets around variables in usage string","fromName":"Alex Henrie","fromEmail":"alexhenrie24@gmail.com","sentAt":"2015-08-29T04:18:44Z","receivedAt":"2015-08-29T04:18:44Z","isPatch":true,"sender":{"key":"alexhenrie24@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5951993?v=4"},"body":"Signed-off-by: Alex Henrie \n---\n builtin/show-ref.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/show-ref.c b/builtin/show-ref.c\nindex dfbc314..131ef28 100644\n--- a/builtin/show-ref.c\n+++ b/builtin/show-ref.c\n@@ -8,7 +8,7 @@\n \n static const char * const show_ref_usage[] = {\n \tN_(\"git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference] [-s | --hash[=]] [--abbrev[=]] [--tags] [--heads] [--] [...]\"),\n-\tN_(\"git show-ref --exclude-existing[=pattern] < ref-list\"),\n+\tN_(\"git show-ref --exclude-existing[=] < \"),\n \tNULL\n };\n \n-- \n2.5.0\n"},{"id":"268889","messageId":"47B9DE8756F943C0A0985F41D093340F@PhilipOakley","threadId":"40212","inReplyTo":"1440821924-4289-1-git-send-email-alexhenrie24@gmail.com","subject":"Re: [PATCH] show-ref: place angle brackets around variables in usage string","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-08-29T10:21:14Z","receivedAt":"2015-08-29T10:21:14Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Alex Henrie\" \n> Signed-off-by: Alex Henrie \n> ---\n> builtin/show-ref.c | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/builtin/show-ref.c b/builtin/show-ref.c\n> index dfbc314..131ef28 100644\n> --- a/builtin/show-ref.c\n> +++ b/builtin/show-ref.c\n> @@ -8,7 +8,7 @@\n>\n> static const char * const show_ref_usage[] = {\n> N_(\"git show-ref [-q | --quiet] [--verify] [--head] [-d \n> | --dereference] [-s | --hash[=]] [--abbrev[=]] [--tags] \n> [--heads] [--] [...]\"),\n> - N_(\"git show-ref --exclude-existing[=pattern] < ref-list\"),\n> + N_(\"git show-ref --exclude-existing[=] < \"),\n\nShould the '<' stdin redirection be shown?\n\nIt looks (at first glance) as if this gained a double '< <' at the \nbeginning of 'ref-list', rather than being a clean indication of the \nredirection. Perhaps change 'ref-list' to 'ref-list-file' for a slight \nimprovement in clarity - this it's only occurance, and the redirection \nwould best match a file.\n\n\n> NULL\n> };\n>\n> -- \n> 2.5.0\n>\n--\nPhilip\n(will be offline for 4 days) \n"},{"id":"268909","messageId":"CAMMLpeTsL-_e=oGjuqjS5KfBcmd1UKfCOPXmjhaPFv8+qGzRng@mail.gmail.com","threadId":"40212","inReplyTo":"47B9DE8756F943C0A0985F41D093340F@PhilipOakley","subject":"Re: [PATCH] show-ref: place angle brackets around variables in usage string","fromName":"Alex Henrie","fromEmail":"alexhenrie24@gmail.com","sentAt":"2015-08-29T21:09:20Z","receivedAt":"2015-08-29T21:09:20Z","isPatch":true,"sender":{"key":"alexhenrie24@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5951993?v=4"},"body":"2015-08-29 4:21 GMT-06:00 Philip Oakley :\n> Should the '<' stdin redirection be shown?\n>\n> It looks (at first glance) as if this gained a double '< <' at the beginning\n> of 'ref-list', rather than being a clean indication of the redirection.\n> Perhaps change 'ref-list' to 'ref-list-file' for a slight improvement in\n> clarity - this it's only occurance, and the redirection would best match a\n> file.\n\nThis syntax occurs in three other places in Git:\n\ngit cat-file (--batch | --batch-check) [--follow-symlinks] < \n\ngit check-attr --stdin [-z] [-a | --all | ...] < \n\ngit hash-object --stdin-paths < \n\nSo if we need to say for clarity, we should also say\n and for these other commands.\n\nI think the most sane thing to do is to commit this patch as-is, and\nthen someone can submit a separate patch to reword all four usage\nstrings for increased clarity.\n\n-Alex\n"},{"id":"268999","messageId":"xmqqd1y3xx3f.fsf@gitster.mtv.corp.google.com","threadId":"40212","inReplyTo":"47B9DE8756F943C0A0985F41D093340F@PhilipOakley","subject":"Re: [PATCH] show-ref: place angle brackets around variables in usage string","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-08-31T16:05:08Z","receivedAt":"2015-08-31T16:05:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> From: \"Alex Henrie\" \n>> Signed-off-by: Alex Henrie \n>> ---\n>> builtin/show-ref.c | 2 +-\n>> 1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>> diff --git a/builtin/show-ref.c b/builtin/show-ref.c\n>> index dfbc314..131ef28 100644\n>> --- a/builtin/show-ref.c\n>> +++ b/builtin/show-ref.c\n>> @@ -8,7 +8,7 @@\n>>\n>> static const char * const show_ref_usage[] = {\n>> N_(\"git show-ref [-q | --quiet] [--verify] [--head] [-d \n>> | --dereference] [-s | --hash[=]] [--abbrev[=]] [--tags]\n>> [--heads] [--] [...]\"),\n>> - N_(\"git show-ref --exclude-existing[=pattern] < ref-list\"),\n>> + N_(\"git show-ref --exclude-existing[=] < \"),\n>\n> Should the '<' stdin redirection be shown?\n\nHmm, that actually is an interesting thought, because commands that\ntake their input from the standard input in practice would take the\ninput from upstream pipe more often than from a static file on the\nfilesystem, i.e.\n\n $ | git show-ref --exclude-existing[=]\n\nwould be more common, and the \"input from file\" would more likely\nthan not follow this pattern anyway:\n\n $ > \n $ git show-ref --exclude-existing[=] < \n\nA quick \"git grep -e ' < ' Documentation/\" tells me that there\naren't that many ones that take input from stdin.\n\nI am wondering if we can take this one as an example that is among\nthe cleaner and easier to understand:\n\n(GOOD) 'git stripspace' [-s | --strip-comments] < input\n\nand extend its idea further. What is happening here is that \"< input\"\ngives rather a clear sign that it is not saying that the user must\nname her input file \"input\" --- any intelligent user can substitute it\nwith the name of the file she has without being told with a noisy\nand unsightly\n\n(BAD) 'git stripspace' [-s | --strip-comments] < \n\nmostly because \"input\" is so a generic word already. Perhaps we\ncould even drop \"< anything\" as you suggest.\n\n> It looks (at first glance) as if this gained a double '< <' at the\n> beginning of 'ref-list', rather than being a clean indication of the\n> redirection. Perhaps change 'ref-list' to 'ref-list-file' for a slight\n> improvement in clarity - this it's only occurance, and the redirection\n> would best match a file.\n\nOr replace it with \"< input\", together with other ones. Especially\nthe synopsys that says \"git $cmd --stdin < <$anything>\" can be\nreplaced with \"git $cmd --stdin\" without losing any clarity.\n\nThe only thing that it loses is \"what is fed from the standard input\nis a list of refs\", but that should be left to the description of\nthe option that introduces this \"read from the standard input\"\nbehaviour to the command. \"git $cmd --help\" for rev-list and\nupdate-index may serve as examples; they do not have this ugly\n\"< \" business.\n\nHmm?\n"},{"id":"269000","messageId":"xmqq8u8rxvss.fsf@gitster.mtv.corp.google.com","threadId":"40212","inReplyTo":"xmqqd1y3xx3f.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] show-ref: place angle brackets around variables in usage string","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-08-31T16:33:07Z","receivedAt":"2015-08-31T16:33:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n>>> - N_(\"git show-ref --exclude-existing[=pattern] < ref-list\"),\n>>> + N_(\"git show-ref --exclude-existing[=] < \"),\n>>\n>> Should the '<' stdin redirection be shown?\n>\n> Hmm, that actually is an interesting thought,...\n\nHaving said all that (i.e. I agree dropping \"< $anything\" may be a\ngood idea in general), for this particular command, I suspect that\nthe feature may have outlived its usefulness. It was introduced\n(silently) in ed9f7c95 (git-fetch: Avoid reading packed refs over\nand over again, 2006-12-17) as an optimisation that is very specific\nto the way how \"git fetch\" scripted Porcelain happened to be written\nback then.\n\nThe way the feature is misdesigned clearly shows that it was not\ndesigned for general consumption---if it were, we would have made\n\"show-ref\" to be usable as a filter even when we are not excluding\nanything with \"--exclude-existing\" option.\n\nOf course, it is OK and definitely a lot safer to keep the \"can work\nas a filter\" feature for possible third-party uses, but if we were\nto go that route, it is not too late to extend the machinery so that\n\"work as a filter\" is not tied too closely to \"exclude-existing\".\n"}]}