[PATCH] help: document branch template keyword

[Christian Boos]

On 2/27/2011 3:02 PM, Adrian Buehlmann wrote:
> On 2011-02-27 14:39, timeless wrote:
>> On Sun, Feb 27, 2011 at 3:34 PM, Adrian Buehlmann<adrian at cadifra.com>  wrote:
>>> Near as I can tell, each changeset has exactly one branch name
>>>
>>> See also function branch() of changectx
>>>
>>> http://selenic.com/repo/hg/file/tip/mercurial/context.py#l111
>> then perhaps<branches>  should be documented as a botch? and its
>> language corrected to indicate that it isn't really a list?
> Why do you comment on that at all? It is outside of the scope of my patch!
>
> My patch doesn't change anything on the branches keyword documentation,
> so can you please send a separate patch or start a thread of your own
> next time?
>
> Now to your perceived non-issue:
>
> branches is a historic keyword and its semantics need to be backward
> compatible. It is was probably described as a list because it can be
> empty, due to the fact that if a changeset is on the default branch,
> then default will not be emitted. That list can thus be empty or just
> contain one string, which is the name of a branch if it's not the
> default branch.
>
> But again, this is outside the scope of my patch.
>

Not completely, the two will also come one next to the other when you 
read the help, and one will likely end up confused.
So perhaps it would be worth writing something like:

:branch: String. The name of the branch on which the changeset was
      committed (supersedes the historical "branches" keyword).


-- Christian