named heads

[Faheem Mitha]

Dear People,

I've been reviewing and testing hgs named heads, with a view to using them. I 
have a few comments.

1) hg view branchname

works as expected (shows only changesets corresponding to branchname), but is 
undocumented. Also, I cannot find any discussion of this option.

2) I have a repos with two heads, one of them corresponding to a branch (temp) 
which is closed. I get

faheem at orwell:/tmp/test$ hg heads -a

changeset:   8:db4fd6f88ebb
branch:      temp
tag:         tip
[...]
summary:     Close branch temp.

changeset:   3:98c0d9bde0f2
parent:      1:f7cf0b6e18f1
[...]
summary:     Add foobar.

The -a option clearly states

-a --active    show only the active branch heads from open branches

so this is wrong.

3) Someone commented on IRC that the hgweb urls include the names of branches, 
so just tossing this in here.

4) In hg help branches below

a) Why is only -a in brackets and not -c?

b) It says

"List the repository's named branches, indicating which ones are inactive."

This is immediately followed by

"If -c/--closed is specified, also list branches which have been marked 
closed."

So, in fact, the help should read something like

"List the repository's open named branches, indicating which ones are 
inactive."

c) Also the help says

"If -a/--active is specified, only show active branches. A branch is considered 
active if it contains repository heads."

However, I see the following:

faheem at orwell:/tmp/test$ hg branches -c
default                        3:98c0d9bde0f2
temp                           8:db4fd6f88ebb (closed)

faheem at orwell:/tmp/test$ hg branches -a
default                        3:98c0d9bde0f2

By the defn of active, temp is still active, since it contains a repos head, 
but is not shown. So, either change the behavior of "hg branches -c" or change 
the defn of active in the help to say

"A branch is considered active if it is open and contains repository heads."

5) I dislike the command

hg --close-branch ci

--close-branch is an option to commit, which doesn't feel natural. It is not in 
line with the other usages of commit, which are entirely generic. Also, most 
commands in hg are two step. First you mark something, then do the commit. Not 
in one step as with 'hg --close-branch ci'. This is for example in contrast 
with

hg branch foo

where a branch is marked as opened and then the commit is made. Why not do 
something like

hg --close-branch branch foo

6) I dislike that 'hg heads' by default shows heads that correspond to closed 
branches. I suppose this is for backward compatibility, but for named branches 
to be useful, they should by default be as invisible as possible once closed.

7)a) In a similar vein, the following doesn't seem terribly consistent.

faheem at orwell:/tmp/test$ hg heads
changeset:   8:db4fd6f88ebb
branch:      temp
tag:         tip
user:        faheem at email.unc.edu
date:        Sat Jul 25 22:16:49 2009 -0400
summary:     Close branch temp.

changeset:   3:98c0d9bde0f2
parent:      1:f7cf0b6e18f1
user:        faheem at email.unc.edu
date:        Fri Jul 24 17:28:28 2009 -0400
summary:     Add foobar.

faheem at orwell:/tmp/test$ hg heads temp
no open branch heads on branch temp

So, without a branchname argument, it shows the closed branch head on temp, but 
given the branchname argument 'temp', it doesn't? Why the difference? Again 
backward compatibility?

b) Also, hg help heads

doesn't show a branch name as an argument. It does show revisions, but 
that is not the same thing. This is also true of 'hg update' and probably 
other commands.

8)
faheem at orwell:/tmp/test$ hg st
A foofum
faheem at orwell:/tmp/test$ hg branch
temp
faheem at orwell:/tmp/test$ hg up default
abort: crosses named branches (use 'hg update -C' to discard changes)
faheem at orwell:/tmp/test$ hg up -c default
abort: uncommitted local changes

The first error message is unclear (though the solution works), since the 
problem is that there are uncommitted local changes, as shown more clearly 
by the second error message. Without the uncommitted local change, 'hg up 
default' works fine. For consistency, it would be best to make these error 
messages more similar.

9) One question - is it recommended usage to close a branch before 
merging, so it doesn't show up so visibly in 'hg heads' etc. with current 
usage? Or is this just a matter of taste?

**********************************************************************

This seems like enough for the moment. I haven't filed any issues wrt to these, 
but would be happy to do so if given feedback on what to file. Please CC me on 
any reply - I'm subscribed but don't receive mail from the list. I do follow 
the mailing list via gmane, though.

                                                           Regards, Faheem.

************************************************************************

hg branches [-a]

list repository named branches

     List the repository's named branches, indicating which ones are
     inactive. If -c/--closed is specified, also list branches which have
     been marked closed (see hg commit --close-branch).

     If -a/--active is specified, only show active branches. A branch
     is considered active if it contains repository heads.

     Use the command 'hg update' to switch to an existing branch.

options:

  -a --active  show only branches that have unmerged heads
  -c --closed  show normal and closed branches

use "hg -v help branches" to show global options
**************************************************************

hg heads [-r STARTREV] [REV]...

show current repository heads or show branch heads

     With no arguments, show all repository head changesets.

     Repository "heads" are changesets that don't have child
     changesets. They are where development generally takes place and
     are the usual targets for update and merge operations.

     If one or more REV is given, the "branch heads" will be shown for
     the named branch associated with that revision. The name of the
     branch is called the revision's branch tag.

     Branch heads are revisions on a given named branch that do not have
     any descendants on the same branch. A branch head could be a true head
     or it could be the last changeset on a branch before a new branch
     was created. If none of the branch heads are true heads, the branch
     is considered inactive. If -c/--closed is specified, also show branch
     heads marked closed (see hg commit --close-branch).

     If STARTREV is specified only those heads (or branch heads) that
     are descendants of STARTREV will be displayed.

options:

  -r --rev       show only heads which are descendants of REV
  -a --active    show only the active branch heads from open branches
  -c --closed    show normal and closed branch heads
     --style     display using template map file
     --template  display with template