named heads

[Stuart W. Marks]

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

(I think you mean "named branches".) Matt already commented on #1, #2, and #4; 
I'll try to answer the other items.

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

Not sure what to make of this comment. Is there a question or issue?

> 5) I dislike the command "hg --close-branch ci"
> [suggests "hg --close-branch branch foo" instead]

This was discussed quite some time ago on the mercurial-devel list. See

http://selenic.com/pipermail/mercurial-devel/2008-March/005107.html

and related messages. Something like "hg branch --close" was proposed, which 
would mark the working copy so the branch would be closed at the next commit. 
Matt suggested moving the function to "hg commit" instead:

<< Moving closing to commit simplifies things a bit - we don't have to do
any special storage of the "close" intent, we don't need a way to
display or erase that intent, and we don't have to check all our other
actions against that intent. >>

I encourage you to read the thread in question. Things have turned out somewhat 
differently since that discussion, though. Subsequent threads occurred in Oct 
and Dec of 2008; see for instance

http://selenic.com/pipermail/mercurial-devel/2008-October/008291.html

and

http://selenic.com/pipermail/mercurial-devel/2008-December/009329.html

There are several rounds of patch review and submission until the patch was 
queued for integration in Jan 2009. Search for "branch closing".

> 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.

It would perhaps be nice to change this, but it's indeed important to preserve 
compatibility. See

http://mercurial.selenic.com/wiki/CompatibilityRules

If you're interested in open branches, you probably want to use "hg branches" 
instead of "hg heads".

> 7)a) In a similar vein, the following doesn't seem terribly consistent.
> ["hg heads" vs "hg heads 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?

Agreed, it doesn't seem very consistent. Others have also found this area to be 
confusing or problematic.

http://selenic.com/pipermail/mercurial/2009-June/026504.html

http://selenic.com/pipermail/mercurial/2009-July/026653.html

http://selenic.com/pipermail/mercurial-devel/2009-July/014050.html

I think the root of the problem is that there are several distinct concepts 
that use confusingly similar terminology:

"head" - a changeset with no children
"branch head" - the latest changeset of a named branch
"active branch" - a branch whose branch head is also a true head
"closed branch" - a branch whose latest changeset has a special closed marker

So "hg heads" lists true heads, whereas "hg heads temp" lists branch heads of 
the named branch "temp", quite a different thing.

There is also the ambiguity over whether the term "branch" refers to a "named 
branch" or to a branch in the purely topological sense (i.e. a changeset with 
more than one child).

> 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.

See "hg help revisions" to see what you can specify when a command takes a 
"revision" argument. But I note that this help text omits any mention of branch 
names....

> 8) [issues with "hg up default" vs "hg up -c default" messages]

This is a different topic, though I agree that there is confusion in this area 
as well. See for example the recent thread

http://selenic.com/pipermail/mercurial/2009-July/026906.html

I didn't see that this thread reached a firm conclusion, though. I think 
there's more to be said on this topic (though I have further investigation to 
do before I say anything further).

> 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?

Good question. I don't have enough experience with closed vs. inactive branches 
to know which mechanism to use. Personally, I think that merging a branch head 
into some other head to which it isn't really related, just to make the branch 
inactive, makes the history confusing and hard to follow. So marking the branch 
closed with "hg commit --close-branch" but leaving it as a true head in the 
repo makes a bit more sense to me.

> 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.

You had pointed out several issues with the help text, and Matt suggested that 
you submit patches for them. It's probably more productive to submit patches 
than to file issues. There appear to be a number of areas where things really 
are confusing and where changes are warranted. But before proposing substantive 
changes it might be wise for you to read through the previous discussions (see 
links above) and of course to be aware of compatibility constraints.

s'marks