[PATCH] help: document branch template keyword

[Matt Mackall]

On Sun, 2011-02-27 at 15:02 +0100, 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.

Ages ago (2005), we had a very different and ultimately unworkable
approach to named branches that worked vaguely like .hgtags and allowed
multiple branch names per revision.

We should probably hide this last vestige of that approach by dropping
it from the docs and replacing any usage in templates.

-- 
Mathematics is the supreme nostalgia of our time.