Git wiki page

[Geert Janssens]

On Friday 17 May 2013 10:46:41 John Ralls wrote:
> On May 17, 2013, at 10:09 AM, Geert Janssens <janssens-geert at telenet.be> wrote:
> > There is one section in particular that will need improvement: branching
> > and merging in a pure git environment. This should be a summary of our
> > future git workflow strategy. We had a first discussion about this some
> > time ago, but I think it's worth looking at what other projects are
> > doing. I don't have enough git experience to come up with best practices.
> > On the page I have added two links to specific git workflows that could
> > serve as a starting point for discussion on this topic.
> > 
> > Feel free to update the page with every improvement you can think of.
> 
> Most of my non-Gnucash git experience comes from the Gnome repos, where
> rebasing is the standard behavior. It's not a practice I like, but I
> imagine that they had an SVN transition period just like we have and got
> into that habit.
> 
> I do think that we should encourage all non-trivial changes to happen in
> feature branches which are then merged (with --no-ff to force a merge
> commit for generating news) and deleted
+1

> -- for the most part those feature
> branches are never published, so only the canonical repo doesn't get
> clogged with branches. In fact, even published branches can get pruned once
> they've been merged, since git retains the history correctly and a 'branch'
> is just a ref to its HEAD. That keeps the branches list manageable.
> 
I know from experience that this last part takes some time to fully grasp when coming from 
svn. So I'll just add a simplified, explicit example on git branches for others still deeply in the 
svn mindset (best viewed with a fixed-width font):

Suppose you have this tree of commits in your local repository

A - B    (trunk)
  \
    C    (feature-x)

A is the parent commit, B is a descendant of this commit on the trunk branch. C is a 
descendant of A on the feature-x branch. It's already worth pointing out here what branch 
means in git. The trunk 'branch' is some kind of label that is currently attached to commit B. 
The feature-x 'branch' is equally some kind of label attached to commit C

When you merge feature-x into trunk in git, you will get this tree:

A - B - D (trunk)
  \   /
    C     (feature-x)

The 'trunk branch' is now a label attached to commit D. All the ancestors of commit D are 
considered part of the trunk branch. But note already how the branch itself is just a label 
moving from commit to commit as changes are committed.

Now this all happened in your local git repository. The upstream git repository doesn't know 
about any of this yet. At some point you want to push your work upstream. Let's assume for 
simplicity that commit A and B were already in the upstream repo as well. This means the 
upstream repo looks like this:

A - B    (trunk)

'trunk' is a public branch. Let's push our local trunk changes upstream. After a successful 
push, upstream will look like this:

A - B - D (trunk)
  \   /
    C

You might say that's exactly like the local repo, but there's one slight, yet important 
difference: the *branch* feature-x wasn't pushed upstream (note that I didn't put that name 
next to the C commit).

The *commits* that were on that branch and are ancestors of commit D are (commit C in our 
example). These are required to regenerate commit D, so they are pushed upstream as well. 
But as John notes, the *branch* itself is just a name tied to a commit. This name can move to 
another commit or even be removed without affecting the commits themselves in any way. 
So unless you explicitly push that branch (name) to the upstream repository it won't appear 
in there. That's what John means with "we can keep the branch list manageable".

Hopefully this will help some to understand git branches better and why they are totally 
different from svn branches (where each branch is a commit in itself, not a floating label to 
attach to some commit).

Geert