Refactor 05-history #269

Open
wants to merge 4 commits into
from

Projects

None yet

5 participants

@bpteague

This PR is in fulfillment of the new instructor checkout requirement.

I went to improve the learning objectives in 05-history and ended up refactoring the entire lesson. The content is the same but the emphasis and order of presentation is different. The lesson currently starts with git diff and teaches readers how to refer to commits using HEAD~x notation, but I found I didn't have any good context to attach those new facts to, and was left asking "so what?"

My refactoring moves the concept of "going back in time" to the very beginning, motivated with the same example used later on ("Oops I over-wrote a file"). It introduces commit IDs and git checkout pretty much simultaneously; then short IDs, git diff for looking at history, and HEAD~x.

I welcome comments and feedback! Unfortunately the diff is so big that reading it is a PITA; I re-rendered the HTML and pushed it to my own repo. You can see the new version at

http://bpteague.github.io/git-novice/05-history.html

bpteague added some commits May 12, 2016
@bpteague bpteague Refactor chapter 5 (History).
Makes undoing mistakes a more central theme, using it to motivate
why you would want to move through the git history.
4606a53
@bpteague bpteague Sync the index with chapter 5's name 659ea5b
@bpteague bpteague Add bpteague to the AUTHORS file c74777f
@bpteague bpteague Clarify what "staged" means 2a44426
@iglpdc iglpdc added this to the Version 5.4 milestone Jun 6, 2016
@gvwilson
Member

@daisieh @iglpdc what do you think?

@iglpdc
Contributor
iglpdc commented Jun 14, 2016

I prefer to split this topic into two: one for exploring the history and the other for undoing mistakes (see #212 and the comment on that).

On the new "Exploring the history" we should mention:

  • git diff
  • git diff --cached
  • the three ways of referring to versions: first, full commit IDs; second, short commits IDs, and third, HEAD and HEAD~ (learners saw the full commit in git log, so it's natural start with it).

On the new "Undoing mistakes" we should mention:

  • git checkout -- <filename> to undo changes in the working dir,
  • git reset to undo changes in the stage,
  • git checkout <commit> <filename> to recover an old version of the file

I usually explain this part by "incrementing the scope" of the mistake, sort of like @bpteague mentions: you first make a mistake, save it but nothing else; then you make the mistake, save and stage, but not commit, and last you go all the way to actually committing your mistake. This plays very well with any story you make up.

@bpteague do you want to redo your PR to make the first part from what you have in here. I can do the "Undoing mistakes" chunk later.

@rgaiacs rgaiacs commented on the diff Aug 27, 2016
05-history.md
@@ -1,102 +1,48 @@
---
layout: page
title: Version Control with Git
-subtitle: Exploring History
+subtitle: Exploring History and Undoing Mistakes
@rgaiacs
rgaiacs Aug 27, 2016 Contributor

I'm -1 to add "Undoing Mistakes". What mistakes do you want to undo?

@rgaiacs
Contributor
rgaiacs commented Aug 27, 2016

@bpteague do you want to redo your PR to make the first part from what you have in here?

@bpteague

Hi @iglpdc and @rgaiacs - sure, I'll be happy to re-work the PR to address only "exploring history" -- and I like the "incrementing scope" layout for @iglpdc's proposed "undoing mistakes." I'm still left at a bit of a loss for how to motivate "exploring history" -- as a new git user, why should I care? Thoughts?

@rgaiacs
Contributor
rgaiacs commented Aug 31, 2016

I'll be happy to re-work the PR to address only "exploring history"

Thanks.

I'm still left at a bit of a loss for how to motivate "exploring history" -- as a new git user, why should I care? Thoughts?

Because history is what enables undo features. Ask for the students to think about writing a report with never using the undo feature: no undo when copying and past, no undo when remove a section, no undo when remove one file, ...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment