[pony-build] Managing git branches

[C. Titus Brown]

Hi all,

I think you've all been burned by the ...ease... with which you can branch
in git.  So here are some tips for working with remote branches.

Terminology:

  'repository' or 'repo' is a standalone collection of branches; 'git clone'
  clones repos.

  'branch' is a specific named set of code (consisting of a set of patches,
  basically) within a repo.  An unlimited number of branches can co-exist
  within a single repo.

--

Factoids:

Within a repo, you switch between branches with 'git checkout <branch>'.

To merge between branches, you switch to one branch and do 'git merge <other>'
to merge in the other branch.

A good way to do merges IMO is to do

   git checkout <branch 1>
   git checkout -b test_merge   	# creates and checks out a copy of 1
   git merge <branch 2>

If there are merge conflicts because git can't tell how to reconcile two
parallel sets of changes, it will tell you that there are conflicts and
ask you to reconcile them manually.  Within the conflicted files there will
be lines that start with '<<<<'.  We can talk more about what to do with
them when you run into them, but the basic idea is you should edit out
the non-functioning code and then do

   git add <reconciled file>

which will explicitly tell git that you've reconciled the two branches.

Then do a commit, and voila, test_merge will contain the merge!  (If the
merge succeeds without any manual changes, you don't need to do a commit.)

--

Now, the problems that Khushboo are running into are caused by git's
refusal to automatically push to branches that are not direct ancestors
of the branch being pushed -- in other words, branches that explicitly
require merges.

Just to remind you,

  git fetch <repo> <remote branch>:<local branch>

takes the remote branch from repo and copies it to the local branch.
Generally it will refuse to do this if the local branch already exists
and is not an ancestor of the remote branch.

And

   git push <repo> <local branch>:<remote branch>

is the same in reverse: you're trying to do a reverse fetch and replace
the remote branch with the local branch, which git will again refuse
to do if it requires a merge.

Also, note,

  git pull <repo> <remote branch>

will attempt to merge the remote branch into whatever branch you're actually
on.  It can result in merge conflicts.

There are a bunch of ways to deal with these problems but you'll find that
once you get more used to git it will generally "just work".  For now you're
stuck in the never-never land of annoyingness where it seems like nothing
works without effort, but that will change...

--

In general, until you guys are on your feet, you should not worry too much
about the push/pull/fetch details.  Just get code that works the way YOU
want it to and let me worry about the nasty details.  However, you *should*
(as in, I will get pissy if you don't) generally keep up with my master
branch.  This involves doing

   git pull http://github.com/ctb/pony-build.git master

and resolving any conflicts that result.  This will simplify my later
merges of YOUR code by keeping our branches as "close cousins" rather
than distant cousins.

Does that make sense?

cheers,
--titus
-- 
C. Titus Brown, ctb at msu.edu