{"thread":{"id":"45477","subject":"[PATCH] branch doc: Change `git branch ` to use ``","startedAt":"2017-03-23T12:09:55Z","lastAt":"2017-03-24T11:07:49Z","messageCount":10,"participants":["Ævar Arnfjörð Bjarmason","Junio C Hamano","Ramsay Jones","Jonathan Nieder"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"315047","messageId":"20170323120326.19051-1-avarab@gmail.com","threadId":"45477","inReplyTo":null,"subject":"[PATCH] branch doc: Change `git branch ` to use ``","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2017-03-23T12:03:26Z","receivedAt":"2017-03-23T12:09:55Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change an example for `git branch ` to say `git branch\n` to be consistent with the synopsis. This changes\ndocumentation added in d8d33736b5 (\"branch: allow pattern arguments\",\n2011-08-28).\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-branch.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex 092f1bcf9f..e65e5c0dee 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -142,7 +142,7 @@ This option is only applicable in non-verbose mode.\n \tList both remote-tracking branches and local branches.\n \n --list::\n-\tActivate the list mode. `git branch ` would try to create a branch,\n+\tActivate the list mode. `git branch ` would try to create a branch,\n \tuse `git branch --list ` to list matching branches.\n \n -v::\n-- \n2.11.0\n\n"},{"id":"315115","messageId":"xmqq1stoexmb.fsf@gitster.mtv.corp.google.com","threadId":"45477","inReplyTo":"20170323120326.19051-1-avarab@gmail.com","subject":"Re: [PATCH] branch doc: Change `git branch ` to use ``","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-03-23T17:01:00Z","receivedAt":"2017-03-23T17:03:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Change an example for `git branch ` to say `git branch\n> ` to be consistent with the synopsis. This changes\n> documentation added in d8d33736b5 (\"branch: allow pattern arguments\",\n> 2011-08-28).\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/git-branch.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\n> index 092f1bcf9f..e65e5c0dee 100644\n> --- a/Documentation/git-branch.txt\n> +++ b/Documentation/git-branch.txt\n> @@ -142,7 +142,7 @@ This option is only applicable in non-verbose mode.\n> \tList both remote-tracking branches and local branches.\n> \n> --list::\n> -\tActivate the list mode. `git branch ` would try to create a branch,\n> +\tActivate the list mode. `git branch ` would try to create a branch,\n> \tuse `git branch --list ` to list matching branches.\n\nThis makes the description more correct.\n\nI am not sure if it makes that much sense to have that sentence here\nin the first place (after all, it is describing a behaviour of a\nmode that is *not* the list mode), but I guess that it may be a\ncommon mistake to forget to specify \"-l\" while asking for branches\nthat match the pattern? If we were writing this today from scratch,\nI would perhaps write something entirely different, e.g.\n\n\t--list::\n\t\tList branches. With optional ... at the\n\t\tend of the command line, list only the branches that\n\t\tmatch any of the given patterns. Do not forget '-l'\n\t\tand say \"git branch \", as it will instead\n\t\ttry to create a new branch whose name is ,\n\t\twhich is a common mistake.\n\nthough.\n\nThanks.\n"},{"id":"315126","messageId":"5d04c82c-45a4-5d5e-0317-511587ee3474@ramsayjones.plus.com","threadId":"45477","inReplyTo":"xmqq1stoexmb.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] branch doc: Change `git branch ` to use ``","fromName":"Ramsay Jones","fromEmail":"ramsay@ramsayjones.plus.com","sentAt":"2017-03-23T17:44:07Z","receivedAt":"2017-03-23T17:44:14Z","isPatch":true,"sender":{"key":"ramsay@ramsayjones.plus.com","avatar":"https://avatars.githubusercontent.com/u/33702710?v=4"},"body":"\n\nOn 23/03/17 17:01, Junio C Hamano wrote:\n> Ævar Arnfjörð Bjarmason writes:\n> \n>> Change an example for `git branch ` to say `git branch\n>> ` to be consistent with the synopsis. This changes\n>> documentation added in d8d33736b5 (\"branch: allow pattern arguments\",\n>> 2011-08-28).\n>>\n>> Signed-off-by: Ævar Arnfjörð Bjarmason \n>> ---\n>> Documentation/git-branch.txt | 2 +-\n>> 1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\n>> index 092f1bcf9f..e65e5c0dee 100644\n>> --- a/Documentation/git-branch.txt\n>> +++ b/Documentation/git-branch.txt\n>> @@ -142,7 +142,7 @@ This option is only applicable in non-verbose mode.\n>> \tList both remote-tracking branches and local branches.\n>> \n>> --list::\n>> -\tActivate the list mode. `git branch ` would try to create a branch,\n>> +\tActivate the list mode. `git branch ` would try to create a branch,\n>> \tuse `git branch --list ` to list matching branches.\n> \n> This makes the description more correct.\n> \n> I am not sure if it makes that much sense to have that sentence here\n> in the first place (after all, it is describing a behaviour of a\n> mode that is *not* the list mode), but I guess that it may be a\n> common mistake to forget to specify \"-l\" while asking for branches\n> that match the pattern? If we were writing this today from scratch,\n> I would perhaps write something entirely different, e.g.\n> \n> \t--list::\n> \t\tList branches. With optional ... at the\n> \t\tend of the command line, list only the branches that\n> \t\tmatch any of the given patterns. Do not forget '-l'\n> \t\tand say \"git branch \", as it will instead\n> \t\ttry to create a new branch whose name is ,\n> \t\twhich is a common mistake.\n\nHmm, but with git-branch -l means --create-reflog not --list.\n\nI have make the mistake of using -l rather than --list several\ntimes ... :D\n\nATB,\nRamsay Jones\n\n\n"},{"id":"315146","messageId":"xmqqo9wrddgv.fsf@gitster.mtv.corp.google.com","threadId":"45477","inReplyTo":"5d04c82c-45a4-5d5e-0317-511587ee3474@ramsayjones.plus.com","subject":"Re: [PATCH] branch doc: Change `git branch ` to use ``","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-03-23T19:01:36Z","receivedAt":"2017-03-23T19:01:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramsay Jones writes:\n\n>> I am not sure if it makes that much sense to have that sentence here\n>> in the first place (after all, it is describing a behaviour of a\n>> mode that is *not* the list mode), but I guess that it may be a\n>> common mistake to forget to specify \"-l\" while asking for branches\n>> that match the pattern? If we were writing this today from scratch,\n>> I would perhaps write something entirely different, e.g.\n>> \n>> \t--list::\n>> \t\tList branches. With optional ... at the\n>> \t\tend of the command line, list only the branches that\n>> \t\tmatch any of the given patterns. Do not forget '-l'\n>> \t\tand say \"git branch \", as it will instead\n>> \t\ttry to create a new branch whose name is ,\n>> \t\twhich is a common mistake.\n>\n> Hmm, but with git-branch -l means --create-reflog not --list.\n>\n> I have make the mistake of using -l rather than --list several\n> times ... :D\n\nThat too. With \"Do not forget '--list'...\" and it will make it\ncorrect again ;-).\n"},{"id":"315179","messageId":"CACBZZX7vW0TkbrBvLvKWnY=UpHNHzzQ7wuwhEhNOjCCjzPVMjA@mail.gmail.com","threadId":"45477","inReplyTo":"xmqq1stoexmb.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] branch doc: Change `git branch ` to use ``","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2017-03-23T21:07:55Z","receivedAt":"2017-03-23T21:08:22Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Thu, Mar 23, 2017 at 6:01 PM, Junio C Hamano wrote:\n> Ævar Arnfjörð Bjarmason writes:\n>\n>> Change an example for `git branch ` to say `git branch\n>> ` to be consistent with the synopsis. This changes\n>> documentation added in d8d33736b5 (\"branch: allow pattern arguments\",\n>> 2011-08-28).\n>>\n>> Signed-off-by: Ævar Arnfjörð Bjarmason \n>> ---\n>> Documentation/git-branch.txt | 2 +-\n>> 1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\n>> index 092f1bcf9f..e65e5c0dee 100644\n>> --- a/Documentation/git-branch.txt\n>> +++ b/Documentation/git-branch.txt\n>> @@ -142,7 +142,7 @@ This option is only applicable in non-verbose mode.\n>> List both remote-tracking branches and local branches.\n>>\n>> --list::\n>> - Activate the list mode. `git branch ` would try to create a branch,\n>> + Activate the list mode. `git branch ` would try to create a branch,\n>> use `git branch --list ` to list matching branches.\n>\n> This makes the description more correct.\n>\n> I am not sure if it makes that much sense to have that sentence here\n> in the first place (after all, it is describing a behaviour of a\n> mode that is *not* the list mode), but I guess that it may be a\n> common mistake to forget to specify \"-l\" while asking for branches\n> that match the pattern? If we were writing this today from scratch,\n> I would perhaps write something entirely different, e.g.\n\nI'm just doing s/pattern/branchname/ on the existing documentation. If\nyou'd like to entirely reword this to make that unnecessary that\nsounds good, but makes sense that you then submit that patch & just\ndrop this one, rather than me copy/pasting your proposal, sending that\nas my own patch etc...\n\n> --list::\n> List branches. With optional ... at the\n> end of the command line, list only the branches that\n> match any of the given patterns. Do not forget '-l'\n> and say \"git branch \", as it will instead\n> try to create a new branch whose name is ,\n> which is a common mistake.\n\nI like the old one better. It has 3 actual command examples you can\nreadily see. This turns that into more prose that requires the reader\nto mentally parse most of it and mentally insert the mentioned command\nline switches into the equivalent of those 3 examples we just provided\nbefore.\n\n> though.\n>\n> Thanks.\n"},{"id":"315190","messageId":"xmqq37e3brxz.fsf@gitster.mtv.corp.google.com","threadId":"45477","inReplyTo":"CACBZZX7vW0TkbrBvLvKWnY=UpHNHzzQ7wuwhEhNOjCCjzPVMjA@mail.gmail.com","subject":"Re: [PATCH] branch doc: Change `git branch ` to use ``","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-03-23T21:31:52Z","receivedAt":"2017-03-23T21:31:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n>>> --list::\n>>> - Activate the list mode. `git branch ` would try to create a branch,\n>>> + Activate the list mode. `git branch ` would try to create a branch,\n>>> use `git branch --list ` to list matching branches.\n>>\n>> This makes the description more correct.\n>>\n>> I am not sure if it makes that much sense to have that sentence here\n>> in the first place (after all, it is describing a behaviour of a\n>> mode that is *not* the list mode), but I guess that it may be a\n>> common mistake to forget to specify \"-l\" while asking for branches\n>> that match the pattern? If we were writing this today from scratch,\n>> I would perhaps write something entirely different, e.g.\n>\n> I'm just doing s/pattern/branchname/ on the existing documentation. If\n> you'd like to entirely reword this to make that unnecessary that\n> sounds good, but makes sense that you then submit that patch & just\n> drop this one, rather than me copy/pasting your proposal, sending that\n> as my own patch etc...\n\nThat is sensible. I've already queued yours as-is a few hours ago,\nand the remainder of this message is in preparation for a follow-up\npatch that is a separate topic.\n\n>> --list::\n>> List branches. With optional ... at the\n>> end of the command line, list only the branches that\n>> match any of the given patterns. Do not forget '-l'\n>> and say \"git branch \", as it will instead\n>> try to create a new branch whose name is ,\n>> which is a common mistake.\n>\n> I like the old one better. It has 3 actual command examples you can\n> readily see.\n\nHaving the _wrong_ example `git branch ` that is readily\navailable for cutting and pasting is the worst of the three reasons\nwhy I think the current text is bad (the other two being \"it does\nnot even help in explaining the `--list` option\" and \"The argument\nto the other mode is not but is \").\n\nI can go without \"Do not forget ...\" and everything that follows,\nthough, and if we are going to do so, then\n\n\t--list::\n\t\tList branches. With optional ...,\n\t\te.g. `git branch --list 'maint-*`, list only the\n\t\tbranches that match the pattern(s).\n\nwould be fine. I am not opposed to having an visually distinctive\nexample--I just do not want to have one that is wrong without\nclearly marking it as such.\n"},{"id":"315214","messageId":"20170324004858.GE20794@aiede.mtv.corp.google.com","threadId":"45477","inReplyTo":"xmqq37e3brxz.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] branch doc: Change `git branch ` to use ``","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-03-24T00:48:58Z","receivedAt":"2017-03-24T00:49:18Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Junio C Hamano wrote:\n\n> I can go without \"Do not forget ...\" and everything that follows,\n> though, and if we are going to do so, then\n>\n> \t--list::\n> \t\tList branches. With optional ...,\n> \t\te.g. `git branch --list 'maint-*`, list only the\n> \t\tbranches that match the pattern(s).\n>\n> would be fine. I am not opposed to having an visually distinctive\n> example--I just do not want to have one that is wrong without\n> clearly marking it as such.\n\nI like this one. I haven't witnessed \"git branch maint-*\" being a\ncommon mistake.\n\nFor comparison, \"git branch -l maint-*\" does seem to be a common\nmistake. It's a shame that the short-and-sweet \"-l\" was taken for\nthat purpose. Perhaps it's worth calling that out here?\n\n\t--list::\n\t--list ::\n\t\tList branches. If is specified (e.g.,\n\t\t\"git branch --list 'maint-*'), list only the\n\t\tbranches that match the pattern.\n\t+\n\tThis should not be confused with `git branch -l `,\n\twhich creates a branch named `` with a reflog.\n\tSee `--create-reflog` above for details.\n\nThanks,\nJonathan\n"},{"id":"315226","messageId":"xmqqtw6j8e7f.fsf_-_@gitster.mtv.corp.google.com","threadId":"45477","inReplyTo":"20170324004858.GE20794@aiede.mtv.corp.google.com","subject":"[PATCH] branch doc: update description for `--list`","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-03-24T04:56:52Z","receivedAt":"2017-03-24T04:57:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"The paragraph begins with a sample command line `git branch `\nthat has nothing to do with the option being described. Remove it,\nbut use the space to instead show that multiple patterns can be\ngiven.\n\nAlso mention the unfortunate `-l` that can be easily confused with\nit.\n\nHelped-by: Jonathan Nieder \nSigned-off-by: Junio C Hamano \n---\n Documentation/git-branch.txt | 9 +++++++--\n 1 file changed, 7 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex 6a17ca591a..514b0d0b91 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -142,8 +142,13 @@ This option is only applicable in non-verbose mode.\n \tList both remote-tracking branches and local branches.\n \n --list::\n-\tActivate the list mode. `git branch ` would try to create a branch,\n-\tuse `git branch --list ` to list matching branches.\n+\tList branches. With optional `...`, e.g. `git\n+\tbranch --list 'maint-*'`, list only the branches that match\n+\tthe pattern(s).\n++\n+This should not be confused with `git branch -l `,\n+which creates a branch named `` with a reflog.\n+See `--create-reflog` above for details.\n \n -v::\n -vv::\n-- \n2.12.1-432-gf364f02724\n\n"},{"id":"315227","messageId":"20170324050030.GA7558@aiede.mtv.corp.google.com","threadId":"45477","inReplyTo":"xmqqtw6j8e7f.fsf_-_@gitster.mtv.corp.google.com","subject":"Re: [PATCH] branch doc: update description for `--list`","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-03-24T05:00:30Z","receivedAt":"2017-03-24T05:01:11Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Junio C Hamano wrote:\n\n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/git-branch.txt | 9 +++++++--\n> 1 file changed, 7 insertions(+), 2 deletions(-)\n\nReviewed-by: Jonathan Nieder \n\nThanks.\n"},{"id":"315234","messageId":"CACBZZX5xKaOBY8nWAbnLGyRiHW0MnFsEeF5ehpVCviyWc1mb3w@mail.gmail.com","threadId":"45477","inReplyTo":"xmqqtw6j8e7f.fsf_-_@gitster.mtv.corp.google.com","subject":"Re: [PATCH] branch doc: update description for `--list`","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2017-03-24T11:06:41Z","receivedAt":"2017-03-24T11:07:49Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Fri, Mar 24, 2017 at 5:56 AM, Junio C Hamano wrote:\n> The paragraph begins with a sample command line `git branch `\n> that has nothing to do with the option being described. Remove it,\n> but use the space to instead show that multiple patterns can be\n> given.\n>\n> Also mention the unfortunate `-l` that can be easily confused with\n> it.\n>\n> Helped-by: Jonathan Nieder \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/git-branch.txt | 9 +++++++--\n> 1 file changed, 7 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\n> index 6a17ca591a..514b0d0b91 100644\n> --- a/Documentation/git-branch.txt\n> +++ b/Documentation/git-branch.txt\n> @@ -142,8 +142,13 @@ This option is only applicable in non-verbose mode.\n> List both remote-tracking branches and local branches.\n>\n> --list::\n> - Activate the list mode. `git branch ` would try to create a branch,\n> - use `git branch --list ` to list matching branches.\n> + List branches. With optional `...`, e.g. `git\n> + branch --list 'maint-*'`, list only the branches that match\n> + the pattern(s).\n> ++\n> +This should not be confused with `git branch -l `,\n> +which creates a branch named `` with a reflog.\n> +See `--create-reflog` above for details.\nLooks good to me.\n> -v::\n> -vv::\n> --\n> 2.12.1-432-gf364f02724\n>\n"}]}