threads / patch / 45477

patchbranch doc: Change `git branch <pattern>` to use `<branchname>`

Subject: [PATCH] branch doc: Change `git branch <pattern>` to use `<branchname>`

## tl;dr

10 messages between Mar 23, 2017 and Mar 24, 2017. Diffs are folded; open one to read it.

replies: 9people: 4as markdown or json

Ævar Arnfjörð Bjarmason· Mar 23, 2017, 12:03 UTC · lore

Change an example for `git branch <pattern>` to say `git branch <branchname>` to be consistent with the synopsis. This changes documentation added in d8d33736b5 ("branch: allow pattern arguments", 2011-08-28).

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/git-branch.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to Documentation/git-branch.txt +1 −1
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 092f1bcf9f..e65e5c0dee 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -142,7 +142,7 @@ This option is only applicable in non-verbose mode.
 	List both remote-tracking branches and local branches.
 
 --list::
-	Activate the list mode. `git branch <pattern>` would try to create a branch,
+	Activate the list mode. `git branch <branchname>` would try to create a branch,
 	use `git branch --list <pattern>` to list matching branches.
 
 -v::

-- 
2.11.0
Junio C Hamano· Mar 23, 2017, 17:01 UTC · re: Ævar Arnfjörð Bjarmason · lore

Re: [PATCH] branch doc: Change `git branch <pattern>` to use `<branchname>`

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
Show 21 quoted lines
> Change an example for `git branch <pattern>` to say `git branch
> <branchname>` to be consistent with the synopsis. This changes
> documentation added in d8d33736b5 ("branch: allow pattern arguments",
> 2011-08-28).
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
>  Documentation/git-branch.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 092f1bcf9f..e65e5c0dee 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -142,7 +142,7 @@ This option is only applicable in non-verbose mode.
>  	List both remote-tracking branches and local branches.
>  
>  --list::
> -	Activate the list mode. `git branch <pattern>` would try to create a branch,
> +	Activate the list mode. `git branch <branchname>` would try to create a branch,
>  	use `git branch --list <pattern>` to list matching branches.
This makes the description more correct.

I am not sure if it makes that much sense to have that sentence here in the first place (after all, it is describing a behaviour of a mode that is *not* the list mode), but I guess that it may be a common mistake to forget to specify "-l" while asking for branches that match the pattern? If we were writing this today from scratch, I would perhaps write something entirely different, e.g.

	--list::
		List branches.  With optional <pattern>... at the
		end of the command line, list only the branches that
		match any of the given patterns.  Do not forget '-l'
		and say "git branch <pattern>", as it will instead
		try to create a new branch whose name is <pattern>,
		which is a common mistake.
though.
Thanks.
Ramsay Jones· Mar 23, 2017, 17:44 UTC · re: Junio C Hamano · lore

Re: [PATCH] branch doc: Change `git branch <pattern>` to use `<branchname>`

On 23/03/17 17:01, Junio C Hamano wrote:
Show 40 quoted lines
> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
> 
>> Change an example for `git branch <pattern>` to say `git branch
>> <branchname>` to be consistent with the synopsis. This changes
>> documentation added in d8d33736b5 ("branch: allow pattern arguments",
>> 2011-08-28).
>>
>> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
>> ---
>>  Documentation/git-branch.txt | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
>> index 092f1bcf9f..e65e5c0dee 100644
>> --- a/Documentation/git-branch.txt
>> +++ b/Documentation/git-branch.txt
>> @@ -142,7 +142,7 @@ This option is only applicable in non-verbose mode.
>>  	List both remote-tracking branches and local branches.
>>  
>>  --list::
>> -	Activate the list mode. `git branch <pattern>` would try to create a branch,
>> +	Activate the list mode. `git branch <branchname>` would try to create a branch,
>>  	use `git branch --list <pattern>` to list matching branches.
> 
> This makes the description more correct.
> 
> I am not sure if it makes that much sense to have that sentence here
> in the first place (after all, it is describing a behaviour of a
> mode that is *not* the list mode), but I guess that it may be a
> common mistake to forget to specify "-l" while asking for branches
> that match the pattern?  If we were writing this today from scratch,
> I would perhaps write something entirely different, e.g.
> 
> 	--list::
> 		List branches.  With optional <pattern>... at the
> 		end of the command line, list only the branches that
> 		match any of the given patterns.  Do not forget '-l'
> 		and say "git branch <pattern>", as it will instead
> 		try to create a new branch whose name is <pattern>,
> 		which is a common mistake.
Hmm, but with git-branch -l means --create-reflog not --list.

I have make the mistake of using -l rather than --list several times ... :D

ATB, Ramsay Jones

Junio C Hamano· Mar 23, 2017, 19:01 UTC · re: Ramsay Jones · lore

Re: [PATCH] branch doc: Change `git branch <pattern>` to use `<branchname>`

Ramsay Jones <ramsay@ramsayjones.plus.com> writes:
Show 19 quoted lines
>> I am not sure if it makes that much sense to have that sentence here
>> in the first place (after all, it is describing a behaviour of a
>> mode that is *not* the list mode), but I guess that it may be a
>> common mistake to forget to specify "-l" while asking for branches
>> that match the pattern?  If we were writing this today from scratch,
>> I would perhaps write something entirely different, e.g.
>> 
>> 	--list::
>> 		List branches.  With optional <pattern>... at the
>> 		end of the command line, list only the branches that
>> 		match any of the given patterns.  Do not forget '-l'
>> 		and say "git branch <pattern>", as it will instead
>> 		try to create a new branch whose name is <pattern>,
>> 		which is a common mistake.
>
> Hmm, but with git-branch -l means --create-reflog not --list.
>
> I have make the mistake of using -l rather than --list several
> times ... :D

That too. With "Do not forget '--list'..." and it will make it correct again ;-).

Ævar Arnfjörð Bjarmason· Mar 23, 2017, 21:07 UTC · re: Junio C Hamano · lore

Re: [PATCH] branch doc: Change `git branch <pattern>` to use `<branchname>`

On Thu, Mar 23, 2017 at 6:01 PM, Junio C Hamano <gitster@pobox.com> wrote:
Show 32 quoted lines
> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>
>> Change an example for `git branch <pattern>` to say `git branch
>> <branchname>` to be consistent with the synopsis. This changes
>> documentation added in d8d33736b5 ("branch: allow pattern arguments",
>> 2011-08-28).
>>
>> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
>> ---
>>  Documentation/git-branch.txt | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
>> index 092f1bcf9f..e65e5c0dee 100644
>> --- a/Documentation/git-branch.txt
>> +++ b/Documentation/git-branch.txt
>> @@ -142,7 +142,7 @@ This option is only applicable in non-verbose mode.
>>       List both remote-tracking branches and local branches.
>>
>>  --list::
>> -     Activate the list mode. `git branch <pattern>` would try to create a branch,
>> +     Activate the list mode. `git branch <branchname>` would try to create a branch,
>>       use `git branch --list <pattern>` to list matching branches.
>
> This makes the description more correct.
>
> I am not sure if it makes that much sense to have that sentence here
> in the first place (after all, it is describing a behaviour of a
> mode that is *not* the list mode), but I guess that it may be a
> common mistake to forget to specify "-l" while asking for branches
> that match the pattern?  If we were writing this today from scratch,
> I would perhaps write something entirely different, e.g.

I'm just doing s/pattern/branchname/ on the existing documentation. If you'd like to entirely reword this to make that unnecessary that sounds good, but makes sense that you then submit that patch & just drop this one, rather than me copy/pasting your proposal, sending that as my own patch etc...

Show 7 quoted lines
>         --list::
>                 List branches.  With optional <pattern>... at the
>                 end of the command line, list only the branches that
>                 match any of the given patterns.  Do not forget '-l'
>                 and say "git branch <pattern>", as it will instead
>                 try to create a new branch whose name is <pattern>,
>                 which is a common mistake.

I like the old one better. It has 3 actual command examples you can readily see. This turns that into more prose that requires the reader to mentally parse most of it and mentally insert the mentioned command line switches into the equivalent of those 3 examples we just provided before.

> though.
>
> Thanks.
Junio C Hamano· Mar 23, 2017, 21:31 UTC · re: Ævar Arnfjörð Bjarmason · lore

Re: [PATCH] branch doc: Change `git branch <pattern>` to use `<branchname>`

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
Show 19 quoted lines
>>>  --list::
>>> -     Activate the list mode. `git branch <pattern>` would try to create a branch,
>>> +     Activate the list mode. `git branch <branchname>` would try to create a branch,
>>>       use `git branch --list <pattern>` to list matching branches.
>>
>> This makes the description more correct.
>>
>> I am not sure if it makes that much sense to have that sentence here
>> in the first place (after all, it is describing a behaviour of a
>> mode that is *not* the list mode), but I guess that it may be a
>> common mistake to forget to specify "-l" while asking for branches
>> that match the pattern?  If we were writing this today from scratch,
>> I would perhaps write something entirely different, e.g.
>
> I'm just doing s/pattern/branchname/ on the existing documentation. If
> you'd like to entirely reword this to make that unnecessary that
> sounds good, but makes sense that you then submit that patch & just
> drop this one, rather than me copy/pasting your proposal, sending that
> as my own patch etc...

That is sensible. I've already queued yours as-is a few hours ago, and the remainder of this message is in preparation for a follow-up patch that is a separate topic.

Show 10 quoted lines
>>         --list::
>>                 List branches.  With optional <pattern>... at the
>>                 end of the command line, list only the branches that
>>                 match any of the given patterns.  Do not forget '-l'
>>                 and say "git branch <pattern>", as it will instead
>>                 try to create a new branch whose name is <pattern>,
>>                 which is a common mistake.
>
> I like the old one better. It has 3 actual command examples you can
> readily see.

Having the _wrong_ example `git branch <branchname>` that is readily available for cutting and pasting is the worst of the three reasons why I think the current text is bad (the other two being "it does not even help in explaining the `--list` option" and "The argument to the other mode is not <pattern> but is <branchname>").

I can go without "Do not forget ..." and everything that follows, though, and if we are going to do so, then

	--list::
		List branches.  With optional <pattern>...,
		e.g. `git branch --list 'maint-*`, list only the
		branches that match the pattern(s).

would be fine. I am not opposed to having an visually distinctive example--I just do not want to have one that is wrong without clearly marking it as such.

Jonathan Nieder· Mar 24, 2017, 00:48 UTC · re: Junio C Hamano · lore

Re: [PATCH] branch doc: Change `git branch <pattern>` to use `<branchname>`

Junio C Hamano wrote:
Show 11 quoted lines
> I can go without "Do not forget ..." and everything that follows,
> though, and if we are going to do so, then
>
> 	--list::
> 		List branches.  With optional <pattern>...,
> 		e.g. `git branch --list 'maint-*`, list only the
> 		branches that match the pattern(s).
>
> would be fine.  I am not opposed to having an visually distinctive
> example--I just do not want to have one that is wrong without
> clearly marking it as such.

I like this one. I haven't witnessed "git branch maint-*" being a common mistake.

For comparison, "git branch -l maint-*" does seem to be a common mistake. It's a shame that the short-and-sweet "-l" was taken for that purpose. Perhaps it's worth calling that out here?

	--list::
	--list <pattern>::
		List branches.  If <pattern> is specified (e.g.,
		"git branch --list 'maint-*'), list only the
		branches that match the pattern.
	+
	This should not be confused with `git branch -l <branchname>`,
	which creates a branch named `<branchname>` with a reflog.
	See `--create-reflog` above for details.

Thanks, Jonathan

Junio C Hamano· Mar 24, 2017, 04:56 UTC · re: Jonathan Nieder · lore

[PATCH] branch doc: update description for `--list`

The paragraph begins with a sample command line `git branch <name>` that has nothing to do with the option being described. Remove it, but use the space to instead show that multiple patterns can be given.

Also mention the unfortunate `-l` that can be easily confused with it.

Helped-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-branch.txt | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)
Show changes to Documentation/git-branch.txt +7 −2
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 6a17ca591a..514b0d0b91 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -142,8 +142,13 @@ This option is only applicable in non-verbose mode.
 	List both remote-tracking branches and local branches.
 
 --list::
-	Activate the list mode. `git branch <branchname>` would try to create a branch,
-	use `git branch --list <pattern>` to list matching branches.
+	List branches.  With optional `<pattern>...`, e.g. `git
+	branch --list 'maint-*'`, list only the branches that match
+	the pattern(s).
++
+This should not be confused with `git branch -l <branchname>`,
+which creates a branch named `<branchname>` with a reflog.
+See `--create-reflog` above for details.
 
 -v::
 -vv::

-- 
2.12.1-432-gf364f02724
Jonathan Nieder· Mar 24, 2017, 05:00 UTC · re: Junio C Hamano · lore

Re: [PATCH] branch doc: update description for `--list`

Junio C Hamano wrote:
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/git-branch.txt | 9 +++++++--
>  1 file changed, 7 insertions(+), 2 deletions(-)
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
Thanks.
Ævar Arnfjörð Bjarmason· Mar 24, 2017, 11:06 UTC · re: Junio C Hamano · lore

Re: [PATCH] branch doc: update description for `--list`

On Fri, Mar 24, 2017 at 5:56 AM, Junio C Hamano <gitster@pobox.com> wrote:
Show 31 quoted lines
> The paragraph begins with a sample command line `git branch <name>`
> that has nothing to do with the option being described.  Remove it,
> but use the space to instead show that multiple patterns can be
> given.
>
> Also mention the unfortunate `-l` that can be easily confused with
> it.
>
> Helped-by: Jonathan Nieder <jrnieder@gmail.com>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/git-branch.txt | 9 +++++++--
>  1 file changed, 7 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 6a17ca591a..514b0d0b91 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -142,8 +142,13 @@ This option is only applicable in non-verbose mode.
>         List both remote-tracking branches and local branches.
>
>  --list::
> -       Activate the list mode. `git branch <branchname>` would try to create a branch,
> -       use `git branch --list <pattern>` to list matching branches.
> +       List branches.  With optional `<pattern>...`, e.g. `git
> +       branch --list 'maint-*'`, list only the branches that match
> +       the pattern(s).
> ++
> +This should not be confused with `git branch -l <branchname>`,
> +which creates a branch named `<branchname>` with a reflog.
> +See `--create-reflog` above for details.
Looks good to me.
Show 5 quoted lines
>  -v::
>  -vv::
> --
> 2.12.1-432-gf364f02724
>

← back to recent threads