Novice-level lesson on branching in Git

[dtrapezoid]

Adding a lesson on branching for novice git users. Kept it as simple as could be, introducing the basic branching commands only. I am on the fence about how to resolve the lesson so I would love to have feedback on the following-

Update 5/1: Upon discussing the options went with teaching a PR on GitHub proper for the resolution to the lesson.

Resolving the lesson:
In line 155, I introduce merging. This will be problematic in the command line with the fast-forward vs. regular merge issue. To address this there are a few options.

• Pull request- If we introduce a pull request on GitHub, we can show them git log --oneline --graph so they can have a nice visual at the end showing their history in the command line. I personally think this is the best option.
• Explaining fast-forward vs. regular merge- A run for the hills option, imho, it might be a little much to throw on them at this point.
• Have them commit again to the master before merging- A run for the mountains approach, they add a dummy commit in their workflow to retain branching history.

Any feedback on the rest of the lesson is welcome, tried to keep it consistent with Greg's lessons using the Monster Mash story line.

[jiffyclub]

An option not enumerated by @dtrap is to leave things as is: have the students branch and merge from the command line, and give no special discussion as to the different types of merges and history and whatnot. That could leave them uninformed about the mess of things they may encounter in the future, but we probably don't have time to cover all that.

[wking]

On Mon, Apr 28, 2014 at 10:40:33PM -0700, Dani Traphagen wrote:

In line 155, I introduce merging. This will be problematic in the
command line with the fast-forward vs. regular merge issue. To
address this there are a few options.

• Pull request- If we introduce a pull request on GitHub, we can
  show them git log --oneline --graph so they can have a nice
  visual at the end showing their history in the command line. I
  personally think this is the best option.
• Explaining fast-forward vs. regular merge- A run for the hills
  option, imho, it might be a little much to throw on them at this
  point.
• Have them commit again to the master before merging- A run for
  the mountains approach, they add a dummy commit in their workflow
  to retain branching history.

Branches allow you factor a large change into a series of small
commits. That way, folks reviewing the change (either before merging,
or while looking back into the history later) can get both the big
picture (from branch level stuff like the cover letter, PR message, or
merge-commit message) and smaller, line-level detail (from pre-merge
commit messages). I think anything that avoids fast-forward merges
(pull requests and 'merge --no-ff') is a good way to make that point
clearly. Personally, the only uses I see for fast-forward merges are:

• Updating a local branch to follow upstream changes:

  $ git checkout master
  $ git pull --ff-only origin master

• Integrating one-commit branches. The single commit message already
  completely explains the change, so there's nothing left to talk
  about in an extra merge-commit. However, this situation is
  complicated enough (e.g. if the target branch has advanced in the
  meantime, possibly introducing rebase conflicts), that I probably
  wouldn't spend time one it with novices.

Since the novice lesson is already using GitHub, I think the
pull-request approach makes the most sense here.

On a more detailed level:

• 'Touch' and 'Nano' are probably not going to work on a
  case-sensitive OS.

• “for feedback before he without disrupting” → “for feedback without
  disrupting”.

• I wouldn't explicitly list git status in the lesson. It should
  have been covered earlier, and I think listing it here distracts
  from the new branching stuff. I'd still mention it (verbally in
  workshops, or in an aside here) if folks were having trouble keeping
  track of what Git was thinking.

• With Git 2.0 (to be released soon), git push will start pushing
  just the current branch by default. Until 2.0 has been out for a
  few years, it's probably better to stick with explicit pushes:

  $ git push origin shelter_plan

  In fact, I'm pretty sure the existing git push will give something
  like:

  Everything up-to-date

  because the 'shelter_plan' doesn't exist upstream yet.

• I don't think your post-push 'git branch' is doing what you claim
  it's doing (because it only shows local branches, and Dracula and
  Mummy can't see any of those). I'd prefer:

  $ git log --oneline --graph --decorate

  • c0ffee1 (HEAD, origin/shelter_plan, shelter_plan) shelter.txt: Add bedrooms
  • deadbee (origin/master, origin/HEAD, master) Some common commit

• After exiting your room sizes, you're house is a bit under half the
  size ;). I think you should explicitly list the git commit for
  this revised version too, so folks don't checkout master with a
  dirty file (which Git wouldn't let them do in this case anyway).

• “swtich” → “switch”.

• Merging and pushing to master before soliciting feedback is the
  wrong order ;). It's better to push the shelter_plan feature
  branch, get feedback (“why do you get the big room‽”), adjust to
  that feedback (commit the evenly-sized rooms), re-push and get more
  feedback (“looks good to me”), and then merge and push to master.

[jiffyclub]

This branch is shelter_plan above. Shows up as shelter here and a couple spots below.

[dtrapezoid]

Yes, thank you for pointing that out, this was a last minute branch name change so that the .txt file name and branch name being the same wouldn't confuse the students. I will fix this.

[jiffyclub]

"Explain what branches are"

[dtrapezoid]

👍

[gvwilson]

Again, lose the sub-sub heading - I think you can go straight into the paragraph below.

[dtrapezoid]

👍

[PBarmby]

A mistake I keep making here is "git push origin master" instead of "git push origin branchname". Would a short discussion of the "git push" arguments be helpful/appropriate here?

[PBarmby]

I'm fairly new to branching myself and wish I'd had this lesson a few months ago! I think you cover the bascis well. Agreed that fast-foward vs regular merging seems too complex for this level.
In addition to Greg's request for a diagram up by line 100, I wonder if a more general diagram showing what branches can do would be useful. There are some good ones here which might be a model: http://nvie.com/posts/a-successful-git-branching-model/

[gvwilson]

Can this one please be updated and then merged in before #759 ?

[jiffyclub]

@dtrapezoid, I'm sure you're pretty busy now. Think you'll get a chance to work on this anytime soon?

[dtrapezoid]

@jiffyclub Hey Matt! Yes, that is true, I am going hard right now on the new job.

I'll update the changes I have so far this Saturday, but I think I'll have to delegate the images changes on the screenshots due to copyright issues to someone else. Those images could simply be cropped out of the screenshots and overlayed as a quicker approach to redoing the process.

I haven't yet pushed up all the changes I commented on, so a lot of work has been done already to correct the changes @gvwilson suggested. I will do that this Sat. and see what else I can get through too. I'm thinking carving out a few hours Saturday around 3pm if you have time to chat then.

[gvwilson]

Relocated at swcarpentry/git-novice#225