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

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 23, 2017, 17:01 UTC
Message-ID: <xmqq1stoexmb.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20170323120326.19051-1-avarab@gmail.com>

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