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

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

[Ævar Arnfjörð Bjarmason]

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.
 
 -v::
-- 
2.11.0

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

[Junio C Hamano]

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

though.

Thanks.

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

[Ramsay Jones]

On 23/03/17 17:01, Junio C Hamano wrote:
> Æ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

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

[Junio C Hamano]

Ramsay Jones <ramsay@ramsayjones.plus.com> writes:

>> 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 ;-).

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

[Ævar Arnfjörð Bjarmason]

On Thu, Mar 23, 2017 at 6:01 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Æ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...

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

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

[Junio C Hamano]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

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

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

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

[Jonathan Nieder]

Junio C Hamano wrote:

> 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

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

[Junio C Hamano]

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.
 
 -v::
 -vv::
-- 
2.12.1-432-gf364f02724

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

[Jonathan Nieder]

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.

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

[Ævar Arnfjörð Bjarmason]

On Fri, Mar 24, 2017 at 5:56 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 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.
>  -v::
>  -vv::
> --
> 2.12.1-432-gf364f02724
>