What is a branch?

[Stuart W. Marks]

>> (BTW what tool do you use for diagrams?)
> 
> The one Matt has installed on the wiki :-). I just stole/adapted the raw 
> wiki text from the page UnderstandingMercurial.

Aha... I thought somebody had rendered the diagrams in SVG or something....

>> The big problem I see is that it still tries to support both usages of 
>> the word "branch", that is, (a) a fork in the history graph, and (b) a 
>> cloned repo. In particular the section starting with "The creation of 
>> a branch can also happen in two different repositories R1 and R2..." 
>> is a rather odd description of usage (b). I think that some people 
>> really refer to the creation of clone as "branching" regardless of 
>> whether any commits have been made to either repo. I'd suggest 
>> removing this section entirely.
> 
> Hmm. If you must remove that section feel free to do so. I think it 
> would be helpful to leave it for completeness sake. My motivation was to 
> document existing uses of the term "branch" and not imposing The Correct 
> One.

I felt it would be a bit antisocial for me to just take it out without some 
discussion first.

I agree, I don't think it's possible for any of us to declare some Globally 
Correct definition for some term. But within Mercurial's semi-official docs, it 
would be good to have a crisp definition of each term and to have it used 
consistently throughout.

It might be worthwhile to have a discussion page about the different meanings 
of "branch" in different contexts, perhaps as an appendix or on a different page.

> BTW Bazaar uses "branch" in yet another way. I suppose some people look 
> at Bazaar *and* Mercurial anyway (I did it myself and choose Mercurial). 
> I wouldn't be surprised if some branch/clone confusion comes from that 
> anyway.
> 
> BTW on the Branch wiki page, I didn't write that a clone is a branch. 

Yes, I understand that. I was referring to other writings. For example, on the 
QuickStart page

http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart

The "Branching and merging" example has the following line:

     $ hg clone project project-work    # create a new branch

This is clearly using the "clone is a branch" definition.

> The branching on the cloned repo does not happen until you *commit* two 
> differing changesets in both clones. So, effectively, there is no 
> difference to the single repo case. Semantically, that branching already 
> happened on the commit of C2 in R2. Not just when you pull it into R1.

This differs yet again from the "clone is a branch" definition. I hadn't heard 
"branch" used in this sense before, but I see what you're driving at. This is 
sort of a latent branch, in that you can't necessarily see it until changes are 
propagated.

> The history graph is in fact a "distributed history graph". So the 
> branch exists earlier. Per your terminology, the branch would not exist 
> until I pull it into a  combining repo. So I'm not sure if your approach 
> really does help to reduce any (supposed) confusion.

Sure, since you and I are using different definitions of "branch" it's 
understandable that we'd say they are created at different times.

But I do think there is real confusion out there arising from ambiguity around 
the word "branch". The recent thread "mercurial tip not visible" is rife with 
this ambiguity.

Well, maybe I'll just edit some of the wiki pages and see if people like what I 
come up with.

s'marks