What are branches?

What are branches?

[Johannes Schindelin]

Hi,

if you're like me, you used Git for _way_ too long to really understand 
how anybody can say that Git is hard to learn.  The concepts underlying 
Git have sunk so deep that I do not question them anymore.

But it is important to keep in mind that our concept of branches is not 
intuitive:

http://longair.net/blog/2009/04/16/git-fetch-and-merge/

In particular, we have some pretty confusing nomenclature when it comes to 
branches, and we might want to think how to improve the situation.

Food for thought on a lazy Sunday afternoon.

Ciao,
Dscho

Re: What are branches?

[Michael Witten]

On Sun, Apr 19, 2009 at 10:17, Johannes Schindelin
<Johannes.Schindelin@gmx.de> wrote:
> if you're like me, you used Git for _way_ too long to really understand
> how anybody can say that Git is hard to learn.

I think that the human brain struggles with indirection. Consider that
so many programmers have a hard time understanding pointers; no wonder
so many people find git's underlying concepts boggling.

Michael WItten

Re: What are branches?

[Tuncer Ayaz]

On Sun, Apr 19, 2009 at 5:17 PM, Johannes Schindelin
<Johannes.Schindelin@gmx.de> wrote:
> Hi,
>
> if you're like me, you used Git for _way_ too long to really understand
> how anybody can say that Git is hard to learn.  The concepts underlying
> Git have sunk so deep that I do not question them anymore.
>
> But it is important to keep in mind that our concept of branches is not
> intuitive:
>
> http://longair.net/blog/2009/04/16/git-fetch-and-merge/
>
> In particular, we have some pretty confusing nomenclature when it comes to
> branches, and we might want to think how to improve the situation.
>
> Food for thought on a lazy Sunday afternoon.

Probably in the same confusion department:
http://blog.teksol.info/2009/04/15/beware-of-gits-content-tracking.html

Is he right and is this the defined correct behavior?

Re: What are branches?

[Johannes Schindelin]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1055 bytes --]

Hi,

On Mon, 20 Apr 2009, Tuncer Ayaz wrote:

> On Sun, Apr 19, 2009 at 5:17 PM, Johannes Schindelin
> <Johannes.Schindelin@gmx.de> wrote:
>
> > if you're like me, you used Git for _way_ too long to really 
> > understand how anybody can say that Git is hard to learn.  The 
> > concepts underlying Git have sunk so deep that I do not question them 
> > anymore.
> >
> > But it is important to keep in mind that our concept of branches is 
> > not intuitive:
> >
> > http://longair.net/blog/2009/04/16/git-fetch-and-merge/
> >
> > In particular, we have some pretty confusing nomenclature when it 
> > comes to branches, and we might want to think how to improve the 
> > situation.
> >
> > Food for thought on a lazy Sunday afternoon.
> 
> Probably in the same confusion department:
> http://blog.teksol.info/2009/04/15/beware-of-gits-content-tracking.html
> 
> Is he right and is this the defined correct behavior?

Could you please at least change the subject to something like "Something 
else, was Re: ..." when you abduct the thread?

Thanks,
Dscho

Re: What are branches?

[Tuncer Ayaz]

On Mon, Apr 20, 2009 at 12:29 AM, Johannes Schindelin
<Johannes.Schindelin@gmx.de> wrote:
> Hi,
>
> On Mon, 20 Apr 2009, Tuncer Ayaz wrote:
>
>> On Sun, Apr 19, 2009 at 5:17 PM, Johannes Schindelin
>> <Johannes.Schindelin@gmx.de> wrote:
>>
>> > if you're like me, you used Git for _way_ too long to really
>> > understand how anybody can say that Git is hard to learn.  The
>> > concepts underlying Git have sunk so deep that I do not question them
>> > anymore.
>> >
>> > But it is important to keep in mind that our concept of branches is
>> > not intuitive:
>> >
>> > http://longair.net/blog/2009/04/16/git-fetch-and-merge/
>> >
>> > In particular, we have some pretty confusing nomenclature when it
>> > comes to branches, and we might want to think how to improve the
>> > situation.
>> >
>> > Food for thought on a lazy Sunday afternoon.
>>
>> Probably in the same confusion department:
>> http://blog.teksol.info/2009/04/15/beware-of-gits-content-tracking.html
>>
>> Is he right and is this the defined correct behavior?
>
> Could you please at least change the subject to something like "Something
> else, was Re: ..." when you abduct the thread?

sorry, will repost. I have to admit that I was 25% unsure whether
this is related and the right/wrong context. oh and that number is
exact :).

Re: What are branches?

[Dmitry Potapov]

On Sun, Apr 19, 2009 at 05:17:52PM +0200, Johannes Schindelin wrote:
> 
> But it is important to keep in mind that our concept of branches is not 
> intuitive:
> 
> http://longair.net/blog/2009/04/16/git-fetch-and-merge/

I don't see how our concept of branches is any different from what other
version control systems have; but I see why it is so confusing for many
people. We define a branch as a line of development (I'm still think it
is a pretty good and widely accepted definition of branch), yet when a
newcomer runs gitk, what he or she sees is not a line but a graph.

Thus anyone looking at a gitk image may ask you: "Where is this line
that represents the master branch?" Indeed, it is nearly impossible to
see it, but it does not mean this line does not exist. If you run:
gitk --first-parent master
you can see it.

Unfortunately, this line is far from being one straight line drawn in
a single color. Thus, not surprisingly that this line cannot be seen in
the graph, and here is where the mental image that a new user has about
branches (based on different books and diagrams) clashes with the image
presented by gitk. No one will ever draw the mainline like this:

-o--o--o         o--o--o
        \       /
         o--o--o

but it is not uncommon for gitk to display it in this way, and when
this line is intervene with many other branches that forking from and
merging to this mainline, all what you can see a complex graph and
nothing more.

There is one more thing. In Git, all branches are equal and that is a
really good feature from the implementation point of view as it makes
design simpler and more powerful. But the user point of view, branches
are never equal -- there is a _big_ difference between the master and
any feature branch. All diagrams explaining branching and merging will
show the mainline as a thick straight line running through all history
(like a tree trunk) while feature branches fork and merge back to it.

That is the mental image that a new user has, and that image clashes
with what he or she sees in gitk. BTW, when I started to use Git, I
strongly preferred qgit over gitk. Admittedly, gitk displays branches
much better when you have a really bushy tree, but straight lines
displayed by qgit were much easier to understand and to follow.

So, I don't think that we have any conceptual problem here. It may be
a visualization problem, but if you have a really complex tree, it may
be impossible to present it as nice and simple as artificial diagrams
in textbooks.


Dmitry

Re: What are branches?

[Michael J Gruber]

Dmitry Potapov venit, vidit, dixit 20.04.2009 13:32:
> On Sun, Apr 19, 2009 at 05:17:52PM +0200, Johannes Schindelin wrote:
>>
>> But it is important to keep in mind that our concept of branches is not 
>> intuitive:
>>
>> http://longair.net/blog/2009/04/16/git-fetch-and-merge/
> 
> I don't see how our concept of branches is any different from what other
> version control systems have; but I see why it is so confusing for many

It is very different, and for a good reason, indeed.

git's branches really are moving tags. As such, there is no single
branch that a commit would be tied to. A commit does not belong to a
specific branch; you commit on a branch (usually), and it may be
contained in 1 or more branches, of course. Which branch (name) may
actually depend on the repository: branch names are not stored in
commits, only (backward) relations between commits.

This is fundamentally different from what is named "branch" in hg, e.g.
There, a commit stores the branch name, which is why you can't delete
branches easily. [For me, this is also why hg branches are useless, but
I don't want to start flames here - for me they are useless, for others
they may still be perfect.]

Branches in cvs etc. are much like the latter: You commit on a specific
branch, *and* you can't change that later. The branch name at time of
creating a commit is stored in the commit.

Hg is introducing "bookmarks" now, corresponding to git branches. I
think this name describes the nature of git branches very well.

> people. We define a branch as a line of development (I'm still think it
> is a pretty good and widely accepted definition of branch), yet when a
> newcomer runs gitk, what he or she sees is not a line but a graph.
> 
> Thus anyone looking at a gitk image may ask you: "Where is this line
> that represents the master branch?" Indeed, it is nearly impossible to
> see it, but it does not mean this line does not exist. If you run:
> gitk --first-parent master
> you can see it.
> 
> Unfortunately, this line is far from being one straight line drawn in
> a single color. Thus, not surprisingly that this line cannot be seen in
> the graph, and here is where the mental image that a new user has about
> branches (based on different books and diagrams) clashes with the image
> presented by gitk. No one will ever draw the mainline like this:
> 
> -o--o--o         o--o--o
>         \       /
>          o--o--o
> 
> but it is not uncommon for gitk to display it in this way, and when
> this line is intervene with many other branches that forking from and
> merging to this mainline, all what you can see a complex graph and
> nothing more.
> 
> There is one more thing. In Git, all branches are equal and that is a
> really good feature from the implementation point of view as it makes
> design simpler and more powerful. But the user point of view, branches
> are never equal -- there is a _big_ difference between the master and
> any feature branch. All diagrams explaining branching and merging will
> show the mainline as a thick straight line running through all history
> (like a tree trunk) while feature branches fork and merge back to it.
> 
> That is the mental image that a new user has, and that image clashes
> with what he or she sees in gitk. BTW, when I started to use Git, I
> strongly preferred qgit over gitk. Admittedly, gitk displays branches
> much better when you have a really bushy tree, but straight lines
> displayed by qgit were much easier to understand and to follow.
> 
> So, I don't think that we have any conceptual problem here. It may be
> a visualization problem, but if you have a really complex tree, it may
> be impossible to present it as nice and simple as artificial diagrams
> in textbooks.
> 
> 
> Dmitry

Re: What are branches?

[Dmitry Potapov]

On Mon, Apr 20, 2009 at 02:07:50PM +0200, Michael J Gruber wrote:
> Dmitry Potapov venit, vidit, dixit 20.04.2009 13:32:
> > On Sun, Apr 19, 2009 at 05:17:52PM +0200, Johannes Schindelin wrote:
> >>
> >> But it is important to keep in mind that our concept of branches is not 
> >> intuitive:
> >>
> >> http://longair.net/blog/2009/04/16/git-fetch-and-merge/
> > 
> > I don't see how our concept of branches is any different from what other
> > version control systems have; but I see why it is so confusing for many
> 
> It is very different, and for a good reason, indeed.
> 
> git's branches really are moving tags. As such, there is no single
> branch that a commit would be tied to. A commit does not belong to a
> specific branch; you commit on a branch (usually), and it may be
> contained in 1 or more branches, of course.

When you create a new commit, it is always belong to _one_ branch and
never to two or more branches. After that you can create a child branch
that will also contain this commit, but it is so in any other VCS.

Perhaps, the only difference with some other VCSes can be that some VCS
remember name on what branch the commit was initially created, but you
can add that information to Git commit manually if you really want.

But even better approach is to write the branch name only once when
it is merged to the upstream, and Git does that by default. Have you
seen a lot of merge commits like this:

   Merge branch 'bs/maint-1.6.0-tree-walk-prefix' into maint
   ....

though the name of branch does not exist in the upstream repository,
there is no problem to find all commits created on that branch. In fact,
if Git stored those names in the upstream then Git repository would
contain over 2,000 branches already and that number would be only grow.

> 
> This is fundamentally different from what is named "branch" in hg, e.g.
> There, a commit stores the branch name, which is why you can't delete
> branches easily. [For me, this is also why hg branches are useless, but
> I don't want to start flames here - for me they are useless, for others
> they may still be perfect.]

I don't see it as fundamentally different. Basically, Hg has some
restriction that does not let you to remove branches that outlived their
usefulness (and thus polluting name space), but the underlying structure
is the same...

> 
> Branches in cvs etc. are much like the latter: You commit on a specific
> branch, *and* you can't change that later. The branch name at time of
> creating a commit is stored in the commit.

IIRC, it is not. CVS uses numbers which identify each branch. The name
of branch can be changed later, but you cannot change the underlying ID.
You can even remove the name, but branch will remain, and you can follow
it if you know numbers. Incidentally, you can always follow Git branch
in similar way by using --first-parent option...

> 
> Hg is introducing "bookmarks" now, corresponding to git branches. I
> think this name describes the nature of git branches very well.

Honestly, the first thing that comes to my mind when I hear bookmarks
in relation to VCS is unannotated tags... The idea of self advancing
bookmarks is really weird...


Dmitry

Re: What are branches?

[Michael J Gruber]

Dmitry Potapov venit, vidit, dixit 20.04.2009 15:24:
> On Mon, Apr 20, 2009 at 02:07:50PM +0200, Michael J Gruber wrote:
>> Dmitry Potapov venit, vidit, dixit 20.04.2009 13:32:
>>> On Sun, Apr 19, 2009 at 05:17:52PM +0200, Johannes Schindelin wrote:
>>>>
>>>> But it is important to keep in mind that our concept of branches is not 
>>>> intuitive:
>>>>
>>>> http://longair.net/blog/2009/04/16/git-fetch-and-merge/
>>>
>>> I don't see how our concept of branches is any different from what other
>>> version control systems have; but I see why it is so confusing for many
>>
>> It is very different, and for a good reason, indeed.
>>
>> git's branches really are moving tags. As such, there is no single
>> branch that a commit would be tied to. A commit does not belong to a
>> specific branch; you commit on a branch (usually), and it may be
>> contained in 1 or more branches, of course.
> 
> When you create a new commit, it is always belong to _one_ branch and
> never to two or more branches. After that you can create a child branch
> that will also contain this commit, but it is so in any other VCS.

There is nothing in a git commit that ties it to a specific branch; in
that sense, it does not "belong" to any.

A git branch is a pointer to a commit. That commit and its predecessors
are contained in the branch. A commit may be contained in multiple
branches, on equal footing: there is no "prime branch".

> 
> Perhaps, the only difference with some other VCSes can be that some VCS
> remember name on what branch the commit was initially created, but you
> can add that information to Git commit manually if you really want.

I don't want it. I want things the git way ;)

I just want to emphasize that the branch concept is really different.
Emphasizing that helps people who switch from other VCS to git.

In other VCS, a commit always belongs to exactly one branch: the one you
committed it to, which is stored in the commit. It may be contained in
multiple branches, but belongs to the one only.

> 
> But even better approach is to write the branch name only once when
> it is merged to the upstream, and Git does that by default. Have you
> seen a lot of merge commits like this:
> 
>    Merge branch 'bs/maint-1.6.0-tree-walk-prefix' into maint
>    ....
> 
> though the name of branch does not exist in the upstream repository,
> there is no problem to find all commits created on that branch. In fact,
> if Git stored those names in the upstream then Git repository would
> contain over 2,000 branches already and that number would be only grow.
> 
>>
>> This is fundamentally different from what is named "branch" in hg, e.g.
>> There, a commit stores the branch name, which is why you can't delete
>> branches easily. [For me, this is also why hg branches are useless, but
>> I don't want to start flames here - for me they are useless, for others
>> they may still be perfect.]
> 
> I don't see it as fundamentally different. Basically, Hg has some
> restriction that does not let you to remove branches that outlived their
> usefulness (and thus polluting name space), but the underlying structure
> is the same...

The underlying structure is the directed graph, with predecessorship
being the incidence relation. But what's being discussed here is the
various VCS concepts going by the name "branch" (the concept overlaying
the graph structure), and those are inherently different. Not being able
to delete a branch (without taking all its commits down) is one
consequence of a specific concept.

> 
>>
>> Branches in cvs etc. are much like the latter: You commit on a specific
>> branch, *and* you can't change that later. The branch name at time of
>> creating a commit is stored in the commit.
> 
> IIRC, it is not. CVS uses numbers which identify each branch. The name
> of branch can be changed later, but you cannot change the underlying ID.
> You can even remove the name, but branch will remain, and you can follow
> it if you know numbers. 

So, that ID is exactly equivalent to hg's branch name: stored in the
commit; just like svn's branches/paths if you follow a standard layout.

> Incidentally, you can always follow Git branch
> in similar way by using --first-parent option...
> 
>>
>> Hg is introducing "bookmarks" now, corresponding to git branches. I
>> think this name describes the nature of git branches very well.
> 
> Honestly, the first thing that comes to my mind when I hear bookmarks
> in relation to VCS is unannotated tags... The idea of self advancing
> bookmarks is really weird...

... but exactly what git's branches are, and what makes them so useful ;)

Michael

Re: What are branches?

[Michael J Gruber]

Francis Galiegue venit, vidit, dixit 20.04.2009 16:14:
> Le lundi 20 avril 2009, vous avez écrit :
>> Dmitry Potapov venit, vidit, dixit 20.04.2009 15:24:
>>
>> There is nothing in a git commit that ties it to a specific branch; in
>> that sense, it does not "belong" to any.
>>
> 
> Yes there is: the branch you are currently on (shown by, among others, "git 
> branch").

No, there is not.

Proof: Delete that branch and the commit will still be there. QED

> 
>> A git branch is a pointer to a commit. That commit and its predecessors
>> are contained in the branch. A commit may be contained in multiple
>> branches, on equal footing: there is no "prime branch".
>>
> 
> No. A commit's SHA1 depends on all other commits.

...on all predecessors' SHA1s, to be exact.

Now, what does this have to do with the existence of a "prime branch",
which you claim?

> 
> Why do you think the rebase command exists at all?
> 

In order to change the DAG. It rewrites commits.

On the other hand: If I want to change what branch a commit "is on", I
use git branch -m to rename the branch or git reset etc. to change some
*descendant* commits of the commit in question. All of this does not
rewrite the commit in question, but changes the names resp. the number
of branches the commit is on. Which exactly proves my point.

git branches are different. Luckily they are!

Michael

P.S.: Please don't cull cc:
P.P.S.: I'll stop here with this thread. I assume you'll believe at
least Dscho if you don't believe me ;)

Re: What are branches?

[Dmitry Potapov]

On Mon, Apr 20, 2009 at 03:52:59PM +0200, Michael J Gruber wrote:
> Dmitry Potapov venit, vidit, dixit 20.04.2009 15:24:
> > On Mon, Apr 20, 2009 at 02:07:50PM +0200, Michael J Gruber wrote:
> >> Dmitry Potapov venit, vidit, dixit 20.04.2009 13:32:
> >>> On Sun, Apr 19, 2009 at 05:17:52PM +0200, Johannes Schindelin wrote:
> >>>>
> >>>> But it is important to keep in mind that our concept of branches is not 
> >>>> intuitive:
> >>>>
> >>>> http://longair.net/blog/2009/04/16/git-fetch-and-merge/
> >>>
> >>> I don't see how our concept of branches is any different from what other
> >>> version control systems have; but I see why it is so confusing for many
> >>
> >> It is very different, and for a good reason, indeed.
> >>
> >> git's branches really are moving tags. As such, there is no single
> >> branch that a commit would be tied to. A commit does not belong to a
> >> specific branch; you commit on a branch (usually), and it may be
> >> contained in 1 or more branches, of course.
> > 
> > When you create a new commit, it is always belong to _one_ branch and
> > never to two or more branches. After that you can create a child branch
> > that will also contain this commit, but it is so in any other VCS.
> 
> There is nothing in a git commit that ties it to a specific branch; in
> that sense, it does not "belong" to any.

Let's take a look at definition of "branch" in different sources:

"Branching, in revision control and software configuration management,
is the duplication of an object under revision control (such as a source
code file, or a directory tree) so that modifications can happen in
parallel along both branches."
Source: http://en.wikipedia.org/wiki/Branching_(software)

"This is the basic concept of a branch—namely, a line of development
that exists independently of another line, yet still shares a common
history if you look far enough back in time. A branch always begins life
as a copy of something, and moves on from there, generating its own
history."
Source: http://svnbook.red-bean.com/en/1.1/ch04.html#svn-ch-4-sect-1

"When we need to be precise, we will use the word "branch" to mean a
line of development, and "branch head" (or just "head") to mean a
reference to the most recent commit on a branch."
Source: http://www.kernel.org/pub/software/scm/git/docs/v1.6.2.3/user-manual.html#what-is-a-branch

It is not that Git commit is not belong to any, but it may appear as
being to many branches in shared history. Yet, I don't see anything
in definition of branch that would preclude this.

> 
> A git branch is a pointer to a commit. That commit and its predecessors
> are contained in the branch. A commit may be contained in multiple
> branches, on equal footing: there is no "prime branch".

This is not accurate description. The aforementioned pointer is called
"branch head". Branch (in strictly sense) is a line of development,
which is defined by its head. A usual commit has one parent; a merge
commit can have more than one parent, the first parent defines the
branch line while other parents point to branches merged to it.

> 
> In other VCS, a commit always belongs to exactly one branch: the one you
> committed it to, which is stored in the commit. It may be contained in
> multiple branches, but belongs to the one only.

I am not sure that it is the case, but actually it depends how you
define terms "belong", "contained", "branch", etc... Anyway, no commonly
used definition of "branch" implies any idea of exclusiveness ownership
of some commit.

> >>
> >> This is fundamentally different from what is named "branch" in hg, e.g.
> >> There, a commit stores the branch name, which is why you can't delete
> >> branches easily. [For me, this is also why hg branches are useless, but
> >> I don't want to start flames here - for me they are useless, for others
> >> they may still be perfect.]
> > 
> > I don't see it as fundamentally different. Basically, Hg has some
> > restriction that does not let you to remove branches that outlived their
> > usefulness (and thus polluting name space), but the underlying structure
> > is the same...
> 
> The underlying structure is the directed graph, with predecessorship
> being the incidence relation. But what's being discussed here is the
> various VCS concepts going by the name "branch" (the concept overlaying
> the graph structure), and those are inherently different. Not being able
> to delete a branch (without taking all its commits down) is one
> consequence of a specific concept.

I think you confuse two different things branch and its name. It is not
exactly same things in most VCSes, though you usually use branch name to
refer to any branch. In Git (as in CVS and SVN), you can delete branch
name without deleting commits.

> 
> So, that ID is exactly equivalent to hg's branch name: stored in the
> commit; just like svn's branches/paths if you follow a standard layout.

No, ID is just ID. You have commit ID in Git too, and you cannot remove
it without removing commits, and if you have commit ID of the branch
head, you can follow the whole branch line even if it does not have any
name.

> 
> > Incidentally, you can always follow Git branch
> > in similar way by using --first-parent option...
> > 
> >>
> >> Hg is introducing "bookmarks" now, corresponding to git branches. I
> >> think this name describes the nature of git branches very well.
> > 
> > Honestly, the first thing that comes to my mind when I hear bookmarks
> > in relation to VCS is unannotated tags... The idea of self advancing
> > bookmarks is really weird...
> 
> ... but exactly what git's branches are, and what makes them so useful ;)

No, Git branches are branches, anyway "bookmarks" is clearly a wrong
term. If you do not like "branch", there are many other terms that can
be used instead, for example: streams, codelines.

> That's because you're thinking of browser bookmarks instead of a real
> bookmark.  A bookmark in a book would be rather pointless if I couldn't
> advance it as I read pages.  :-D

You can advance them or move backward, but bookmarks do not move on its
own. They always point to the place where you put them. That's why this
term remembers me more unannotated tags.


Dmitry

Re: What are branches?

[Junio C Hamano]

Dmitry Potapov <dpotapov@gmail.com> writes:

> On Mon, Apr 20, 2009 at 03:52:59PM +0200, Michael J Gruber wrote:
> ...
>> A git branch is a pointer to a commit. That commit and its predecessors
>> are contained in the branch. A commit may be contained in multiple
>> branches, on equal footing: there is no "prime branch".
>
> This is not accurate description.

On the contrary, Michael's description is very accurate; its problem may
be that it is too accurate to be useful for people who do not use certain
features.

> The aforementioned pointer is called
> "branch head". Branch (in strictly sense) is a line of development,
> which is defined by its head. A usual commit has one parent; a merge
> commit can have more than one parent, the first parent defines the
> branch line while other parents point to branches merged to it.

Now, that again is technically accurate but is not very useful or even
harmful if you read too much into --first-parent.

Dscho may have been working on this nifty feature while my tree added tons
of changes that conflict with his work based on an older tree of mine.
And then he says "I have a clean history of this new feature; please pull".


         o---o---o---o---o Dscho's changes
        /
    ---o---D---D---D---o My tree
       ^     
       |       D = changes from Dmitry that conflicts with Dscho's branch
    v1.6.2

I may pull, and see a lot of conflicts; being unfamiliar with what he did,
I may say "I tried to pull, and I give up---there are too many conflicts
with what patches from Dmitry did recently since your tree forked, and I
do not know the area affected very well, so I feel uneasy doing the merge
myself."

         o---o---o---o---o Dscho's changes
        /                 .
    ---o---D---D---D---o...X My tree, unable to resolve conflicts
       ^     
       |       D = changes from Dmitry that conflicts with Dscho's branch
    v1.6.2

Dscho can do two things.  One is to rebase, but his code was in use
outside of my tree for some time and doing so will screw up other people.

But he can merge my tree and resolve the conflicts, and then tell me to
pull again.


           Dscho's changes
         o---o---o---o---o---M
        /                   /    
    ---o---D---D---D---o---. My tree
       ^     
       |       D = changes from Dmitry that conflicts with Dscho's branch
    v1.6.2     M = merge made by Dscho for me

Now, if I did the merge, the first parent of X would have been the tip of
my tree that had patches from you, and it would have merged Dscho's
changes as a side branch.  But if Dscho did a merge _for me_, then his
merge M will have his history as the first parent, and your patches
(together with possibly ones from other people) will be merged into the
history as a side branch.

However, especially after I fast-forward my branch tip to M and continue
building on it, it is more useful to treat Dscho's topic as the side
branch that was merged to my mainline that had your patches, for the
purpose of most people.  Your "first parent" rule does not match that
expectation.

If we made it easy for Dscho to create the merge M to record my tree as
the first parent, you _could_ make the "first parent" rule to be more
meaningful than it currently is, but without it, it still is merely one of
the heuristics as people suggested in this discussion.

Re: What are branches?

[Marius Vollmer]

Junio C Hamano <gitster@pobox.com> writes:

> If we made it easy for Dscho to create the merge M to record my tree as
> the first parent, [...]

But it _is_ easy for Dscho to do that, isn't it?  He just needs to
remember to do the merge the other way around, checking out your branch
and merging his into it.

This doesn't change much, of course, since we still can't follow a
branch backwards in time reliably.  Would it make sense to record
additional information in a merge commit, such as the branch name for
each parent?  Then tools could automatically draw the history of the
current branch as a straight line, say.

Re: What are branches?

[Junio C Hamano]

Marius Vollmer <marius.vollmer@gmail.com> writes:

> Junio C Hamano <gitster@pobox.com> writes:
>
>> If we made it easy for Dscho to create the merge M to record my tree as
>> the first parent, [...]
>
> But it _is_ easy for Dscho to do that, isn't it?  He just needs to
> remember to do the merge the other way around, checking out your branch
> and merging his into it.
>
> This doesn't change much, of course, since we still can't follow a
> branch backwards in time reliably.  Would it make sense to record
> additional information in a merge commit, such as the branch name for
> each parent?  Then tools could automatically draw the history of the
> current branch as a straight line, say.

We already have record of that, but I do not think using it is necessarily
healthy.

There are certainly cases where the relationship between the maintainer
and a contributor makes one branch "the primary" in the sense that it is
the integration ground for everything under the sun, as opposed to the
other one that is "the side branch that was merged" in the sense that it
brought in a more narrowly focused set of patches.  If you examine the
merge commit M Dscho makes in the example in my previous message, it shows
that one of the parents was committed by me and the other was committed by
Dscho.  By following my commits over Dscho's, you will identify which one
of the parents of a merge is the mainline.  You would perhaps instead of
"git log --first-parent" use "git log --mainline=gitster" or something
like that.

The point is that a convention to follow my commits over Dscho's commits
is just as valid as a convention to follow the first parent.  It is purely
a social convention.

A more problematic is that in a distributed environment, there doesn't
necessarily such a "mainline vs side branch" relationship exist, and it is
not healthy to try to introduce such a concept like "mainline" when there
is no such thing.

Perhaps Alice and Bob forked at the same point, agreeing between
themselves that Alice works on the code updates while Bob updates the
documentation as a team of two to produce a new feature.  Before they
collectively conclude their work and send a pull request to the project
management, they will merge their branches to produce the end result that
is pullable.  From the overall project's point of view, the merge to get
their work into the mainline will be "the mainline merges one side branch
for the feature", but what about the merges between Alice and Bob while
they work together?  There is no "this is the mainline and this is a side
branch" relationship between what they do.

Re: What are branches?

[Dmitry Potapov]

On Mon, Apr 20, 2009 at 01:58:37PM -0700, Junio C Hamano wrote:
> 
> However, especially after I fast-forward my branch tip to M and continue
> building on it, it is more useful to treat Dscho's topic as the side
> branch that was merged to my mainline that had your patches, for the
> purpose of most people.  Your "first parent" rule does not match that
> expectation.

Yes, it does not work here. However, fast-forward merge is not a real
merge (though it is often very useful, because it avoids useless commits,
yet, it is clearly Git specific thing). Still, what you describe is not
very like to happen in practice, because it usually takes some time for
any branch to "graduate" to master, and in meanwhile some other branches
get merged, so it is not very likely to be fast-forward (and some people
always prefer to merge anything to master with --no-ff).

> 
> If we made it easy for Dscho to create the merge M to record my tree as
> the first parent, you _could_ make the "first parent" rule to be more
> meaningful than it currently is, but without it, it still is merely one of
> the heuristics as people suggested in this discussion.

Agreed. It is merely a heuristic unless it is not reinforced (like using
--no-ff merges to master), but still it is a very good heuristic for most
practical purposes, and it even can be improved based on merge messages.


Dmitry

Re: What are branches?

[Johannes Schindelin]

Hi,

On Mon, 20 Apr 2009, Dmitry Potapov wrote:

> When you create a new commit, it is always belong to _one_ branch and 
> never to two or more branches.

Certainly you forgot about detached HEADs?  And about the ability to 
create new branches which point to the _exact_ same commit as other 
branches?  And about the option to delete the original branch, not 
removing the commit, or the other branches, at all?

No, this all shows: we _have_ a different branch model from most other 
VCSes, and we _obviously_ make that not clear enough.

Meaning, we should point out that our branches are different, _and_ we 
should describe the light-weighted nature of them better in our 
documentation (especially the tutorials).

Ciao,
Dscho

Re: What are branches?

[Björn Steinbrink]

On 2009.04.20 16:25:38 +0200, Johannes Schindelin wrote:
> On Mon, 20 Apr 2009, Dmitry Potapov wrote:
> 
> > When you create a new commit, it is always belong to _one_ branch
> > and never to two or more branches.
> 
> Certainly you forgot about detached HEADs? And about the ability to
> create new branches which point to the _exact_ same commit as other
> branches? And about the option to delete the original branch, not
> removing the commit, or the other branches, at all?
> 
> No, this all shows: we _have_ a different branch model from most other
> VCSes, and we _obviously_ make that not clear enough.

Basically, git has no actual entities that I'd call "branches", it just
has named branch heads. The branches themselves are implicit in the
commit DAG.

If you go out, and look at a tree lit-up by the evil daystar, branches
start at the trunk and end at their tip. The trunk isn't part of the
branch. And as e.g. a SVN user, you can use an analogy and say "There's
branch XYZ and it has these three commits", ignoring commits from the
trunk or other branches leading up to this one. And you can even ask SVN
which commits make up that branch, by using a "stop on copy" feature
(because that copy usually tells where the branching point is).

Let's take this history:

A---B---C---D (refs/heads/master)
 \
  E---F---G (refs/heads/foo)
       \
        H---I---J (refs/heads/bar)

The branches might be thought of to contain these commits:

master: A, B, C, D
foo: E, F, G
bar: H, I, J

Because those commits are (from a task oriented view) what makes those
branches. If branch "bar" implements feature Y, then the commits A, E
and F might not be interesting when talking about the branch in the
context of the feature it implements.

With SVN you could do:
svn log --stop-on-copy .../bar

Which automatically ignores commits that are on other branches.

With git you need:
git log foo..bar

Which gives the same result, but you need to be more explicit about what
you want to ignore. Because git just sees branch heads, not branches.
The same "you need to think a bit more/different" applies to merging
branches. As svn has just glorified cherry-picking, you can ignore the
whole history leading up to a branch, and still think of just "this
branch does this task", and "merge" that branch. For git, that obviously
won't do, you need to see the branch as it's embedded into the history.
I'm not saying this is bad, as it gives you a more useful history, and
more flexibility, but it is definitely different from at least one wide
spread system.

The only thing I'm aware of where git really draws a line between
"branches" and branch heads is git checkout. You can checkout a "branch"
using its name:
	git checkout master

But using the name of the branch head, will detach HEAD:
	git checkout refs/heads/master

(The quotes are there because this "branch" doesn't match the definition
of a branch as I used it earlier...)


So basically, we don't have explicit branches, just a mechanism to
control where the branches grow.

Björn

Re: What are branches?

[Jakub Narebski]

Björn Steinbrink <B.Steinbrink@gmx.de> writes:

> If you go out, and look at a tree lit-up by the evil daystar, branches
> start at the trunk and end at their tip. The trunk isn't part of the
> branch.  [...]

Well, you have to remember that the 'branch' metaphor should not be
taken too literaly; take for example merges which do not have
equivalent in a tree build.

But if we are talking about literal branches: take a closer loog at
the tip of tree (plant) branch.  You can find growong tip there
(apical meristem) where new cells grow.  In Git you have 'branches'
(branch heads) where you create new commits...

But I agree that there isn't for example true notion of 'trunk' in
git, and this is what allows Git to be truly distributed...

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: What are branches?

[Björn Steinbrink]

On 2009.04.20 11:59:38 -0700, Jakub Narebski wrote:
> Björn Steinbrink <B.Steinbrink@gmx.de> writes:
> 
> > If you go out, and look at a tree lit-up by the evil daystar, branches
> > start at the trunk and end at their tip. The trunk isn't part of the
> > branch.  [...]
> 
> Well, you have to remember that the 'branch' metaphor should not be
> taken too literaly; take for example merges which do not have
> equivalent in a tree build.

True, but that just happened to fit the task-oriented branch view so
well, and I wanted the reference to the evil daystar (obviously ;-)).

> But if we are talking about literal branches: take a closer loog at
> the tip of tree (plant) branch.  You can find growong tip there
> (apical meristem) where new cells grow.  In Git you have 'branches'
> (branch heads) where you create new commits...

Yeah, see the end of my mail, where I said that git has a mechanism to
control where branches grow. Seems to fit :-)

> But I agree that there isn't for example true notion of 'trunk' in
> git, and this is what allows Git to be truly distributed...

Hm, not just no trunk, but also no branches that have a starting point
and an end point. In general, you can't say "My branch starts _here_"
unless you use the root commit(s) as the starting point, or you apply
"extra" knowledge (you know from which other branch this branch forked).

Björn

Re: What are branches?

[Jakub Narebski]

On Mon, 20 April 2009, Björn Steinbrink wrote:
> On 2009.04.20 11:59:38 -0700, Jakub Narebski wrote:
> > Björn Steinbrink <B.Steinbrink@gmx.de> writes:
> > 
> > > If you go out, and look at a tree lit-up by the evil daystar, branches
> > > start at the trunk and end at their tip. The trunk isn't part of the
> > > branch.  [...]
> > 
> > Well, you have to remember that the 'branch' metaphor should not be
> > taken too literaly; take for example merges which do not have
> > equivalent in a tree build.
> 
> True, but that just happened to fit the task-oriented branch view so
> well, and I wanted the reference to the evil daystar (obviously ;-)).

Also in (botanical) trees you can usually distinguish between trunk
and side branches, and I think in most cases also which branch forked
from which one.  Making one of branches (trunk) special might make
sense for centralized version control systems like CVS (1.2 vs 1.2.2.4
version numbers) or Subversion (<project>/trunk for trunk (main branch)
vs <project>/branches/<branchname>; although this is only convention
and is not enforced by the tool), but in my opinion contradicts
distributed nature of distributed SCM such like Git (and Mercurial).

> > But if we are talking about literal branches: take a closer loog at
> > the tip of tree (plant) branch.  You can find growong tip there
> > (apical meristem) where new cells grow.  In Git you have 'branches'
> > (branch heads) where you create new commits...
> 
> Yeah, see the end of my mail, where I said that git has a mechanism to
> control where branches grow. Seems to fit :-)

The difference is that you can (usually) see which branch was first.
It is not the case for Git (and it wouldn't make sense, as for DSCM
there is no sense of 'first' wrt. time).

> > But I agree that there isn't for example true notion of 'trunk' in
> > git, and this is what allows Git to be truly distributed...
> 
> Hm, not just no trunk, but also no branches that have a starting point
> and an end point. In general, you can't say "My branch starts _here_"
> unless you use the root commit(s) as the starting point, or you apply
> "extra" knowledge (you know from which other branch this branch forked).

Well, you can use reflog... if it is not expired.  Or the tracking info
in a config.

-- 
Jakub Narebski
Poland

Re: What are branches?

[Björn Steinbrink]

On 2009.04.24 15:08:05 +0200, Jakub Narebski wrote:
> On Mon, 20 April 2009, Björn Steinbrink wrote:
> > On 2009.04.20 11:59:38 -0700, Jakub Narebski wrote:
> > > Björn Steinbrink <B.Steinbrink@gmx.de> writes:
> > > 
> > > > If you go out, and look at a tree lit-up by the evil daystar, branches
> > > > start at the trunk and end at their tip. The trunk isn't part of the
> > > > branch.  [...]
> > > 
> > > Well, you have to remember that the 'branch' metaphor should not be
> > > taken too literaly; take for example merges which do not have
> > > equivalent in a tree build.
> > 
> > True, but that just happened to fit the task-oriented branch view so
> > well, and I wanted the reference to the evil daystar (obviously ;-)).
> 
> Also in (botanical) trees you can usually distinguish between trunk
> and side branches, and I think in most cases also which branch forked
> from which one.  Making one of branches (trunk) special might make
> sense for centralized version control systems like CVS (1.2 vs 1.2.2.4
> version numbers) or Subversion (<project>/trunk for trunk (main branch)
> vs <project>/branches/<branchname>; although this is only convention
> and is not enforced by the tool), but in my opinion contradicts
> distributed nature of distributed SCM such like Git (and Mercurial).
> 
> > > But if we are talking about literal branches: take a closer loog at
> > > the tip of tree (plant) branch.  You can find growong tip there
> > > (apical meristem) where new cells grow.  In Git you have 'branches'
> > > (branch heads) where you create new commits...
> > 
> > Yeah, see the end of my mail, where I said that git has a mechanism to
> > control where branches grow. Seems to fit :-)
> 
> The difference is that you can (usually) see which branch was first.
> It is not the case for Git (and it wouldn't make sense, as for DSCM
> there is no sense of 'first' wrt. time).

Hm, I'd say we're agreeing, right? What you said basically proves my
point. You don't have "direct" access to the "branches" (the already
grown parts, where you can tell where they start, end and originate
from), but just to the branch heads/tip (where branches grow). I'm just
saying that we might have to accept that fact and make it clear in the
documentation. Not that we should make git support "branches" as first
class entities. Even for "simple" things like repeated merges the
analogy to branches in plants make little sense (as you said).

> > > But I agree that there isn't for example true notion of 'trunk' in
> > > git, and this is what allows Git to be truly distributed...
> > 
> > Hm, not just no trunk, but also no branches that have a starting point
> > and an end point. In general, you can't say "My branch starts _here_"
> > unless you use the root commit(s) as the starting point, or you apply
> > "extra" knowledge (you know from which other branch this branch forked).
> 
> Well, you can use reflog... if it is not expired.  Or the tracking info
> in a config.

None of that is available in a cloned repo where you might want to look
at the history some "branches", wondering which commits form them, in a
task oriented fashion.

Björn

Re: What are branches?

[Dmitry Potapov]

On Mon, Apr 20, 2009 at 04:25:38PM +0200, Johannes Schindelin wrote:
> 
> On Mon, 20 Apr 2009, Dmitry Potapov wrote:
> 
> > When you create a new commit, it is always belong to _one_ branch and 
> > never to two or more branches.
> 
> Certainly you forgot about detached HEADs?

I suppose it is a branch without any name given to it, but it is an
advanced feature. I don't think many beginners know about it, so it
is something that can confuse beginners.

> And about the ability to 
> create new branches which point to the _exact_ same commit as other 
> branches?

In essence, we mark the starting point of the branch. Obviously, it
points to a commit that is on other branch or branches. Not every
VCS creates a commit when a new branch is created, though overhead
of creating of a new branch in other VCSes is usually much larger.

> And about the option to delete the original branch, not 
> removing the commit, or the other branches, at all?

Again, there is nothing unique about it. If I remember correctly, it is
so in CVS too. You could remove branch name, but it was still available
by ID.


Dmitry

Re: What are branches?

[Johannes Schindelin]

Hi,

On Mon, 20 Apr 2009, Dmitry Potapov wrote:

> On Mon, Apr 20, 2009 at 04:25:38PM +0200, Johannes Schindelin wrote:
> > 
> > On Mon, 20 Apr 2009, Dmitry Potapov wrote:
> > 
> > > When you create a new commit, it is always belong to _one_ branch 
> > > and never to two or more branches.
> > 
> > Certainly you forgot about detached HEADs?
> 
> I suppose it is a branch without any name given to it, but it is an 
> advanced feature. I don't think many beginners know about it, so it is 
> something that can confuse beginners.

I'm sorry, the direction of this discussion does not please me.

The purpose of my message was to make Git old-timers _aware_ of the 
problems newbies have with our notion of branches.  And a wish to come up 
with less confusing documentation.

The purpose was not to discuss at length what branches are in Git (and 
the intended discussion was certainly not about CVS!).

Ciao,
Dscho

Re: What are branches?

[Michał Kiedrowicz]

Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

> I'm sorry, the direction of this discussion does not please me.
> 
> The purpose of my message was to make Git old-timers _aware_ of the 
> problems newbies have with our notion of branches.  And a wish to
> come up with less confusing documentation.
> 
> The purpose was not to discuss at length what branches are in Git
> (and the intended discussion was certainly not about CVS!).
> 
> Ciao,
> Dscho

I think you did something more. You made them aware that
they do not even agree what a branch in Git is.

Michal Kiedrowicz

Re: What are branches?

[Dmitry Potapov]

On Mon, Apr 20, 2009 at 09:19:10PM +0200, Johannes Schindelin wrote:
> 
> The purpose of my message was to make Git old-timers _aware_ of the 
> problems newbies have with our notion of branches.  And a wish to come up 
> with less confusing documentation.

Thank you for your attempt bringing attention to this problem, but I
think anyone who remember their first steps with Git or have observed
other people starting to use Git recently have noticed that already.

I will try quickly summarize my view of it:

- branches in Git are not fundamentally different than in other VCSes,
  and clearly correspond commonly used definition of this term.
  Obviously, every VCS has some difference in the way how it manages
  branches (which makes use of branches in some VCS much easier than in
  others).

- obviously, all newcomers have some ideas about branches based on their
  previous experience (whether it was another VCS or some books), but
  often they do not give much thought to branches before, because they
  rarely used them except two or three branches (like maint and master),
  and many have never merged branches.

- the graph shown by gitk may be very confusing for beginners, because
  they cannot see the branch line, in particular, of the master branch.

- I don't find documentation to be confusing, but it doesn't mean that it
  cannot be improved. Yet, based on my observation, most confusion are
  among those users who has shown less propensity to read documentation.


Dmitry

Re: What are branches?

[Björn Steinbrink]

On 2009.04.20 22:47:46 +0400, Dmitry Potapov wrote:
> On Mon, Apr 20, 2009 at 04:25:38PM +0200, Johannes Schindelin wrote:
> > 
> > On Mon, 20 Apr 2009, Dmitry Potapov wrote:
> > 
> > > When you create a new commit, it is always belong to _one_ branch and 
> > > never to two or more branches.
> > 
> > Certainly you forgot about detached HEADs?
> 
> I suppose it is a branch without any name given to it,

Strictly, you don't give names to branches with git. But if you do, that
has some "interesting" consequences. Let's say you have "master" checked
out and do:

git branch foo
git checkout -b bar

You now have a single line of development and three names that reference
it. So your branch would have three names, right?

git commit --allow-empty -m 123

Now, your previous branch only has two names left, and you have a new
branch with a single name.

git reset foo

And now, you again have three names for the original branch and the new
branch is unnamed.

So when you go and say that branch heads provide names for branches, your
actions become pretty weird. "git branch <name>" gives new names to
existing branches, and "git commit" is what actually creates the branch
(this is always the case), plus it might remove a name from an existing
branch. "git reset" removes a name from one branch and gives it to
another branch. "git rebase" does the same, and it's in general not
valid to think of rebase as rewriting the branch's history. For example:

git checkout -b for-v2 for-v1
git rebase --onto v2 v1 for-v2

That would create a new branch, add for-v2 as a name for it and remove
the for-v2 name from the old branch (so the number of names for it is
reduced by one, but it's still called for-v1)


So, IMHO, if you think the whole "branches have names" scheme through,
using the "a branch is a line of development" definition and keeping in
mind how git actually works, using branch heads, things do get pretty
confusing.

> but it is an advanced feature. I don't think many beginners know about
> it, so it is something that can confuse beginners.

But it should not. In my experience, telling someone how HEAD works
often leads to some kind of epiphany. And a detached HEAD is probably
easier to grasp than the "normal" situation where HEAD is a symbolic
reference to some branch head. Btw, writing those emails, I can now
understand _why_ the explanation of HEAD and how it controls which
reference gets updated upon e.g. "git commit" might be so helpful to
some users. It might just be the fact that they suddenly realize that
git does not have a true directly user-accesible notion of branches, but
just branch heads. I can imagine how users that think in branches that
have a start and an end might get confused.

Björn

Re: What are branches?

[Brian Gernhardt]

On Apr 20, 2009, at 9:24 AM, Dmitry Potapov wrote:

> On Mon, Apr 20, 2009 at 02:07:50PM +0200, Michael J Gruber wrote:
>> Hg is introducing "bookmarks" now, corresponding to git branches. I
>> think this name describes the nature of git branches very well.
>
> Honestly, the first thing that comes to my mind when I hear bookmarks
> in relation to VCS is unannotated tags... The idea of self advancing
> bookmarks is really weird...

That's because you're thinking of browser bookmarks instead of a real  
bookmark.  A bookmark in a book would be rather pointless if I  
couldn't advance it as I read pages.  :-D

~~ Brian

Re: What are branches?

[Felipe Contreras]

On Sun, Apr 19, 2009 at 6:17 PM, Johannes Schindelin
<Johannes.Schindelin@gmx.de> wrote:
> Hi,
>
> if you're like me, you used Git for _way_ too long to really understand
> how anybody can say that Git is hard to learn.  The concepts underlying
> Git have sunk so deep that I do not question them anymore.
>
> But it is important to keep in mind that our concept of branches is not
> intuitive:
>
> http://longair.net/blog/2009/04/16/git-fetch-and-merge/
>
> In particular, we have some pretty confusing nomenclature when it comes to
> branches, and we might want to think how to improve the situation.
>
> Food for thought on a lazy Sunday afternoon.

Completely agree. The problem is that git doesn't really have branches.

In my mind a true branch has a divergence start-point from another
branch, so if you rebase a branch, it must be from the start-point.

What git has been referring to "branches" are actually mere
references. That's why 'git rebase' needs either a start-point
specified manually, or it will need to travel the acyclic graph
finding commits that are not already in the graph of the new
start-point.

AFAIK TopGit makes true branches possible in git.

-- 
Felipe Contreras