What are branches?

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

On Sun, Apr 19, 2009 at 10:17, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

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

On Sun, Apr 19, 2009 at 5:17 PM, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

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?

Hi,

On Mon, 20 Apr 2009, Tuncer Ayaz wrote:

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

Thanks, Dscho

On Mon, Apr 20, 2009 at 12:29 AM, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

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

On Sun, Apr 19, 2009 at 05:17:52PM +0200, Johannes Schindelin wrote:

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

Dmitry Potapov venit, vidit, dixit 20.04.2009 13:32:

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.

On Mon, Apr 20, 2009 at 02:07:50PM +0200, Michael J Gruber wrote:

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.

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

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

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

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.

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

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.

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.

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.

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

Michael

On Mon, Apr 20, 2009 at 03:52:59PM +0200, Michael J Gruber wrote:

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.

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.

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.

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.

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.

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.

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

Dmitry Potapov <dpotapov@gmail.com> writes:

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.

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.

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

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.

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

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.

On Mon, Apr 20, 2009 at 01:58:37PM -0700, Junio C Hamano wrote:

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

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

Hi,

On Mon, 20 Apr 2009, Dmitry Potapov wrote:

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

On 2009.04.20 16:25:38 +0200, Johannes Schindelin wrote:

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

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

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

On 2009.04.20 11:59:38 -0700, Jakub Narebski wrote:

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

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

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

On Mon, 20 April 2009, Björn Steinbrink wrote:

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

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

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

On 2009.04.24 15:08:05 +0200, Jakub Narebski wrote:

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

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

On Mon, Apr 20, 2009 at 04:25:38PM +0200, Johannes Schindelin wrote:

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.

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.

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

Hi,

On Mon, 20 Apr 2009, Dmitry Potapov 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

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

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

Michal Kiedrowicz

On Mon, Apr 20, 2009 at 09:19:10PM +0200, Johannes Schindelin wrote:

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

On 2009.04.20 22:47:46 +0400, Dmitry Potapov wrote:

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

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

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

On Sun, Apr 19, 2009 at 6:17 PM, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

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.

Francis Galiegue venit, vidit, dixit 20.04.2009 16:14:

No, there is not.

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

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

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

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 ;)