From: Jonathan Nieder <jrnieder@gmail.com>
Date: Fri, 24 Mar 2017 00:48:58 GMT
Subject: Re: [PATCH] branch doc: Change `git branch <pattern>` to use `<branchname>`
Message-ID: <20170324004858.GE20794@aiede.mtv.corp.google.com>
In-Reply-To: <xmqq37e3brxz.fsf@gitster.mtv.corp.google.com>

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