help: branch names primarily denote the tipmost unclosed branch head

Was the behavior correct and the description wrong so it should be updated as
in this patch? Or should the code work as the documentation says?

Both ways could make some sense ... but none of them are obvious in all cases.

One place where it currently cause problems is when the current revision has
another branch head that is closer to tip but closed. 'hg rebase' refuses to
rebase to that as it only see the tip-most unclosed branch head which is the
current revision.

/me kind of likes named branches, but no so much how branch closing works ...

mercurial/branchmap.py

@@ -167,6 +167,8 b' class branchcache(dict):'
             return False
 
     def _branchtip(self, heads):
+        '''Return tuple with last open head in heads and false,
+        otherwise return last closed head and true.'''
         tip = heads[-1]
         closed = True
         for h in reversed(heads):
@@ -177,6 +179,9 b' class branchcache(dict):'
         return tip, closed
 
     def branchtip(self, branch):
+        '''Return the tipmost open head on branch head, otherwise return the
+        tipmost closed head on branch.
+        Raise KeyError for unknown branch.'''
         return self._branchtip(self[branch])[0]
 
     def branchheads(self, branch, closed=False):

mercurial/help/revisions.txt

@@ -14,9 +14,9 b' of exactly one full-length identifier.'
 
 Any other string is treated as a bookmark, tag, or branch name. A
 bookmark is a movable pointer to a revision. A tag is a permanent name
-associated with a revision. A branch name denotes the tipmost revision
-of that branch. Bookmark, tag, and branch names must not contain the ":"
-character.
+associated with a revision. A branch name denotes the tipmost open branch head
+of that branch - or if they are all closed, the tipmost closed head of the
+branch. Bookmark, tag, and branch names must not contain the ":" character.
 
 The reserved name "tip" always identifies the most recent revision.
 

mercurial/localrepo.py

@@ -655,7 +655,8 b' class localrepository(object):'
         return sorted(marks)
 
     def branchmap(self):
-        '''returns a dictionary {branch: [branchheads]}'''
+        '''returns a dictionary {branch: [branchheads]} with branchheads
+        ordered by increasing revision number'''
         branchmap.updatecache(self)
         return self._branchcaches[self.filtername]
 

tests/test-help.t

@@ -723,7 +723,8 b' Test a help topic'
   
       Any other string is treated as a bookmark, tag, or branch name. A bookmark
       is a movable pointer to a revision. A tag is a permanent name associated
-      with a revision. A branch name denotes the tipmost revision of that
+      with a revision. A branch name denotes the tipmost open branch head of
+      that branch - or if they are all closed, the tipmost closed head of the
       branch. Bookmark, tag, and branch names must not contain the ":"
       character.
   
@@ -1878,9 +1879,9 b' Dish up an empty repo; serve it cold.'
   <p>
   Any other string is treated as a bookmark, tag, or branch name. A
   bookmark is a movable pointer to a revision. A tag is a permanent name
-  associated with a revision. A branch name denotes the tipmost revision
-  of that branch. Bookmark, tag, and branch names must not contain the &quot;:&quot;
-  character.
+  associated with a revision. A branch name denotes the tipmost open branch head
+  of that branch - or if they are all closed, the tipmost closed head of the
+  branch. Bookmark, tag, and branch names must not contain the &quot;:&quot; character.
   </p>
   <p>
   The reserved name &quot;tip&quot; always identifies the most recent revision.