Git intermediate

[ahmadia]

These are ready for high-level review.

Note, there is feedback in #127 that has not been incorporated yet.

Please bring new feedback over here. I'll spend some time addressing comments after I've gotten a complete draft of this material together.

[wking]

On Sun, Jan 19, 2014 at 03:22:06PM -0800, Aron Ahmadia wrote:

A git/intermediate/00-intro.md (129)

• “couple” → “coupled” in “Since their couple biocosmology simulation
  software” ?
• “writeLaTeX ,” → “writeLaTeX,”
• “fear” → “worry” in “Barbara and Candace also fear this process…”

I imagine some of these were copy-pasted from the old novice version,
but that now discusses Wolfman and Dracula ;). You also refer to the
novice material as “git/beginner/00-intro.md” in 710ddd8, when it is
now “novice”. I'd suggest symlinking the intro to the novice version,
but Microsoft puts so many hurdles in the way ;). Maybe msysGit works
around those?

• As you point out, color.ui=auto is the default since Git v1.8.4
  (2013-08-23) 1. Since most of our students will be working from
  fresh installs (I think?), we may not have to worry about this one.
  We should push this back if students are running OSes that still
  package older versions by default.

A git/intermediate/01-conversational-git.md (506)

• Oh man, this phrase-wrapped Markdown is killing me :p. Can't we
  just use our editor's auto-wrapping? I dunno if GitHub's
  soft-wrapped prose diffing 2 works with hard-wrapped text, but
  wrapping this to 70 characters (fill-paragraph (M-q) in Emacs) makes
  the source much more readable, and command-line differs can always
  use --word-diff=color.
• It looks like bio-pipeline is now up to 53 objects :). Progress :).
  Or maybe GitHub just needs to do some garbage collection on your
  bare repo ;).
• I'd drop an ellipsis in the 'ls -a' results to show that you removed
  the non-dotted directories from the output.
• You've got a double-space in “Git documentation as a commit,”
• Backticks around --max count 1 should be sufficient.
• The colored diff highlights trailing whitespace after %pylab in
  python_pipeline.ipy ;).
• I don't think the diff format needs the “for machines” apologizing.
  There's certainly some stuff that is geared towards machines (I
  don't usually read the @@ lines with great care), but the bulk of
  most patches is going to be the very readable +/- lines. I'd prefer
  an approach that said, “some parts of this format are more
  interesting than others. We're just going to focus in the important
  parts. Lines starting with a single ‘+’ were added, and lines
  starting with a single ‘-’ were removed.”. Lines without the
  initial ‘+’ or ‘-’ are present in both versions, and are provided as
  helpful context so you can understand the changes.”
• Non-hex folks might be confused with “digits” describing “cbd6”.
  I'd use “characters”.
• Backticks around -b in “by using -b with the checkout”. There's
  also some fencing errors in this section.
• In “the history of our current revision..”, is this a period, or the
  beginning of an ellipsis?
• Funky prompt in “$❯ git checkout 61fd”.
• git checkout - gives me “error: pathspec '-' did not match any
  file(s) known to git” with Git v1.8.5.2. Maybe you mean git checkout HEAD or git checkout --?

[ahmadia]

Thanks @wking, really helpful feedback. I'll get those in tomorrow. Feel
free to create a fix commit if you like, otherwise I'll just attribute :)

On Sun, Jan 19, 2014 at 11:40 PM, W. Trevor King
[email protected]:

On Sun, Jan 19, 2014 at 03:22:06PM -0800, Aron Ahmadia wrote:

A git/intermediate/00-intro.md (129)

• “couple” → “coupled” in “Since their couple biocosmology simulation
  software” ?
• “writeLaTeX ,” → “writeLaTeX,”
• “fear” → “worry” in “Barbara and Candace also fear this process…”

I imagine some of these were copy-pasted from the old novice version,
but that now discusses Wolfman and Dracula ;). You also refer to the
novice material as “git/beginner/00-intro.md” in 710ddd8, when it is
now “novice”. I'd suggest symlinking the intro to the novice version,
but Microsoft puts so many hurdles in the way ;). Maybe msysGit works
around those?

• As you point out, color.ui=auto is the default since Git v1.8.4
  (2013-08-23) 1. Since most of our students will be working from
  fresh installs (I think?), we may not have to worry about this one.
  We should push this back if students are running OSes that still
  package older versions by default.

A git/intermediate/01-conversational-git.md (506)

• Oh man, this phrase-wrapped Markdown is killing me :p. Can't we
  just use our editor's auto-wrapping? I dunno if GitHub's
  soft-wrapped prose diffing 2 works with hard-wrapped text, but
  wrapping this to 70 characters (fill-paragraph (M-q) in Emacs) makes
  the source much more readable, and command-line differs can always
  use --word-diff=color.
• It looks like bio-pipeline is now up to 53 objects :). Progress :).
  Or maybe GitHub just needs to do some garbage collection on your
  bare repo ;).
• I'd drop an ellipsis in the 'ls -a' results to show that you removed
  the non-dotted directories from the output.
• You've got a double-space in “Git documentation as a commit,”
• Backticks around --max count 1 should be sufficient.
• The colored diff highlights trailing whitespace after %pylab in
  python_pipeline.ipy ;).
• I don't think the diff format needs the “for machines” apologizing.
  There's certainly some stuff that is geared towards machines (I
  don't usually read the @@ lines with great care), but the bulk of
  most patches is going to be the very readable +/- lines. I'd prefer
  an approach that said, “some parts of this format are more
  interesting than others. We're just going to focus in the important
  parts. Lines starting with a single ‘+’ were added, and lines
  starting with a single ‘-’ were removed.”. Lines without the
  initial ‘+’ or ‘-’ are present in both versions, and are provided as
  helpful context so you can understand the changes.”
• Non-hex folks might be confused with “digits” describing “cbd6”.
  I'd use “characters”.
• Backticks around -b in “by using -b with the checkout”. There's
  also some fencing errors in this section.
• In “the history of our current revision..”, is this a period, or the
  beginning of an ellipsis?
• Funky prompt in “$❯ git checkout 61fd”.
• git checkout - gives me “error: pathspec '-' did not match any
  file(s) known to git” with Git v1.8.5.2. Maybe you mean git checkout HEAD or git checkout --?

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/243#issuecomment-32733871
.

[wking]

On Sun, Jan 19, 2014 at 08:46:16PM -0800, Aron Ahmadia wrote:

Thanks @wking, really helpful feedback. I'll get those in tomorrow.
Feel free to create a fix commit if you like, otherwise I'll just
attribute :)

Meh. Feel free to squash fixups ;).

[ahmadia]

Inline responses:

• “couple” → “coupled” in “Since their couple biocosmology simulation
  software” ?
• “writeLaTeX ,” → “writeLaTeX,”
• “fear” → “worry” in “Barbara and Candace also fear this process…”

Thanks, incorporated.

I imagine some of these were copy-pasted from the old novice version,
but that now discusses Wolfman and Dracula ;).

It's a fork. I think the horror movie characters are a bit distracting, and is focused on local cultural references.

You also refer to the
novice material as “git/beginner/00-intro.md” in 710ddd8, when it is
now “novice”. I'd suggest symlinking the intro to the novice version,
but Microsoft puts so many hurdles in the way ;). Maybe msysGit works
around those?

I think it does, I'll worry about it later.

• As you point out, color.ui=auto is the default since Git v1.8.4
  (2013-08-23) [1]. Since most of our students will be working from
  fresh installs (I think?), we may not have to worry about this one.
  We should push this back if students are running OSes that still
  package older versions by default.

I'm going to punt on thinking about this one as well.

• Oh man, this phrase-wrapped Markdown is killing me :p. Can't we
  just use our editor's auto-wrapping? I dunno if GitHub's
  soft-wrapped prose diffing [2] works with hard-wrapped text, but
  wrapping this to 70 characters (fill-paragraph (M-q) in Emacs) makes
  the source much more readable, and command-line differs can always
  use --word-diff=color.

You'll live :)

• It looks like bio-pipeline is now up to 53 objects :). Progress :).
  Or maybe GitHub just needs to do some garbage collection on your
  bare repo ;).

I've got some extra branches/tags in there that need to be deleted.
I really want a better repository, but I don't have one.

• I'd drop an ellipsis in the 'ls -a' results to show that you removed
  the non-dotted directories from the output.

Just copy-and-pasted the output, which only added 2 lines.

• You've got a double-space in “Git documentation as a commit,”
• Backticks around --max count 1 should be sufficient.

Fixed and incorporated.

• The colored diff highlights trailing whitespace after %pylab in
  python_pipeline.ipy ;).

I'm okay with this :)

• I don't think the diff format needs the “for machines” apologizing.
  There's certainly some stuff that is geared towards machines (I
  don't usually read the @@ lines with great care), but the bulk of
  most patches is going to be the very readable +/- lines. I'd prefer
  an approach that said, “some parts of [this format][3] are more
  interesting than others. We're just going to focus in the important
  parts. Lines starting with a single ‘+’ were added, and lines
  starting with a single ‘-’ were removed.”. Lines without the
  initial ‘+’ or ‘-’ are present in both versions, and are provided as
  helpful context so you can understand the changes.”

I added some of your text, which is helpful. Take a look at the page you linked to and imagine a non-computer scientist trying to comprehend it. I'm a computer scientist and I barely understand it :)

• Non-hex folks might be confused with “digits” describing “cbd6”.
  I'd use “characters”.

Nice catch, fixed.

• Backticks around -b in “by using -b with the checkout”. There's
  also some fencing errors in this section.

I fixed the one you pointed out, but did not go looking for others :)

• In “the history of our current revision..”, is this a period, or the
  beginning of an ellipsis?

Clearly a moment of indecision, fixed.

• Funky prompt in “$❯ git checkout 61fd”.

You mean "awesome .zprezto prompt", right? :)

• git checkout - gives me “error: pathspec '-' did not match any
  file(s) known to git” with Git v1.8.5.2. Maybe you mean git checkout HEAD or git checkout --?

What's your reflog showing? git checkout - only works if you've been following the tutorial, it's shorthand for git checkout @{-1}, and undoes your most recent git checkout command, even restoring the previously attached branch.

[wking]

On Mon, Jan 20, 2014 at 08:01:29AM -0800, Aron Ahmadia wrote:

• I don't think the diff format needs the “for machines”
  apologizing. …

I added some of your text, which is helpful.

You've got trailing whitespace after “so you can understand the
changes.”. You can check for this sort of thing before staging your
changes with git diff --check.

Backticks around the + and - are probably better than my curly
quotes (‘’), so you get the same styling as the examples in the
preformatted diff examples.

Take a look at the page you linked to and imagine a non-computer
scientist trying to comprehend it. I'm a computer scientist and I
barely understand it :)

I read through it again and it seems fairly clear. More examples
would be nice though. If we want our own diff-format explainer, I'd
at least pull it out into the glossary or a sidebar for enthusiastic
students, and skip it during most lessons.

• Backticks around -b in “by using -b with the checkout”. There's
  also some fencing errors in this section.

I fixed the one you pointed out, but did not go looking for others :)

Ah, I'd thought the fencing errors were:

  $ git checkout cbd6
  Note: checking out 'cbd6'.
  ``` ← need fence here

  You are in 'detached HEAD' state…

But that explanatory paragraph is quoting Git itself, so you're good.

> * Funky prompt in “$❯ git checkout 61fd”.
> 
> You mean "awesome .zprezto prompt", right? :)

Absolutely ;).

> * `git checkout -` gives me “error: pathspec '-' did not match any
>   file(s) known to git” with Git v1.8.5.2.  Maybe you mean `git
>   checkout HEAD` or `git checkout --`?
> 
> What's your reflog showing?

Ah, I hadn't actually checked out the earlier revision, so my reflog
was just:

  61fd2bc HEAD@{0}: clone: from https://github.com/ahmadia/bio-pipeline.git

> `git checkout -` only works if you've been following the tutorial,
> it's shorthand for `git checkout @{-1}`, and undoes your most recent
> `git checkout` command, even restoring the previously attached
> branch.

I see.  I'd recommend avoiding the checkout-specific `-` and using the
more explicit `@{-1}` which is explained in `git help revisions`.
Still, “checkout the last branch” may be useful enough that we do want
to introduce students to it…  Personally, I just use:

  $ git checkout $branch

and fill in the target branch name by hand ;).  I find the `<rev>^`
syntax much more useful.  For example, before squashing with `commit
--amend`, I run:

  $ git diff HEAD^

to see both the already-committed changes and the soon-to-be-squashed
changes in a single diff.

[rhiever]

@ahmadia, here are the notes on this material from the ERDC SWC bootcamp:

1. Add commit to example repo that has a text change (both additions and deletions). You currently only have commits with only additions and only deletions.
2. Consider cleaning up commits to example repo if you think it's too messy. (You commented that the commits were really messy.)
3. Consider showing the GitHub GUI at the end. git/GitHub is really overwhelming at first, and the GUI could be the gateway drug into using it. The only reason I kept using git/GitHub -- as an intermediate programmer taught by @gvwilson, no less -- is because I discovered the GitHub GUI.
4. Consider discussing putting data on git/github. Should it be done? What are better alternatives? (figshare etc.)

[rgaiacs]

Consider showing the GitHub GUI at the end. git/GitHub is really overwhelming at first, and the GUI could be the gateway drug into using it. The only reason I kept using git/GitHub -- as an intermediate programmer taught by @gvwilson, no less -- is because I discovered the GitHub GUI.

GitHub GUI works only on Windows, correct?

"Git comes with built-in GUI tools for committing (git-gui) and browsing (gitk), but there are several third-party tools for users looking for platform-specific experience." From http://git-scm.com/downloads/guis

I thought that we avoid showing any GUI for git for the same reason that we try to use nano as text editor, keep the user in the terminal.

[rhiever]

They have a GUI for windows and Mac. I'm not sure about Linux.

Here's my rationale: git is overwhelming to learners at first, and the
payoff of using it isn't immediate. Some may think, "Why invest all this
time and effort into learning something that /may/ save my butt in the
future?" There's already a lot of useful things they learn in the boot camp
that has immediate payback, and git could fall through as the weakest link.

The GUIs are really straightforward to use, and can at least get them
committing to online repos immediately. After they've been using the GUI
for a few months, they'll start experiencing the value of git, then find it
worthwhile to revisit the full suite of git commands. Hence the gateway
drug metaphor.

Of course, this is riding on the assumption that very few people pick up
version control from the boot camp in the long run because of how
complicated it is w/o the immediate payback. I have no data to back this
assumption, but I'd put money on it.

On Sunday, January 26, 2014, r-gaia-cs [email protected] wrote:

Consider showing the GitHub GUI at the end. git/GitHub is really
overwhelming at first, and the GUI could be the gateway drug into using it.
The only reason I kept using git/GitHub -- as an intermediate programmer
taught by @gvwilson https://github.com/gvwilson, no less -- is because
I discovered the GitHub GUI.

GitHub GUI http://windows.github.com/ works only on Windows, correct?

"Git comes with built-in GUI tools for committing (git-gui) and browsing
(gitk), but there are several third-party tools for users looking for
platform-specific experience." From http://git-scm.com/downloads/guis

I thought that we avoid showing any GUI for git for the same reason that
we try to use nano as text editor, keep the user in the terminal.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/243#issuecomment-33315151
.

Randal S. Olson

Computer Science PhD Student
Michigan State University
E-mail: [email protected] | Twitter:
@randal_olsonhttps://twitter.com/randal_olson
http://www.randalolson.com

[jkitzes]

+1 on showing a GUI of some kind at the end, after the shell commands, although I'm partial to Sourcetree.

I think it's important to separate the value of git from the experience of using git - personally, I don't think that showing a GUI will do much to resolve the "do I need this or not" debate, which is the most important one for our students. To get students using git, I think that the more important issue is to clearly tell the students, early and often, what problems git will solve for them.

In my own git lesson for beginners, I organize the entire tutorial around six "headaches" that git solves and how to use git to solve them. Covers the usual "canonical" commands, more or less, but puts motivation front and center.

[wking]

On Sun, Jan 26, 2014 at 06:19:43AM -0800, Randy Olson wrote:

They have a GUI for windows and Mac. I'm not sure about Linux.

GitHub does not offer a Linux GUI 1.

Sun, Jan 26, 2014 at 09:21:16AM -0800, Justin Kitzes:

+1 on showing a GUI of some kind at the end, after the shell
commands, although I'm partial to Sourcetree.

SourceTree also seems to lack Linux support 2.

There are a number of other GUIs 3, including git-gui and gitk which
are distributed with Git itself. If we're going to teach from a GUI,
I think git-gui is the way to go. It's even installed automatically
by Git Bash / msysGit. I've never actually used it (or any other Git
GUI) though, except for a few gitk and gitg screenshots.

I'm definitely in favor of increased situational awareness in Git.
Frequent use of a history display with HEAD pointers and such helps me
a lot ;). You can do this with gitk / gitg / tig / …, or just by
calling something like:

$ log --graph --topo-order --oneline --decorate

from the command line. I've got that aliased to glog, and I use it
all the time.

[wking]

On Sun, Jan 26, 2014 at 10:27:57AM -0800, W. Trevor King wrote:

$ log --graph --topo-order --oneline --decorate

I see that @jkitzes sets up a similar alias in his lesson 1:

$ git config --global alias.lg "log --oneline --graph --decorate --all"

I think that's a good idea for an intermediate less (and maybe even
the novice lesson?). I'd leave out the --all though, because
sometimes that's too many commits to absorb ;).

$ git config --global alias.glog 'log --graph --topo-order --oneline --decorate'

You can easily added it at invocation time:

$ git glog --all

And you can also look at other subsets:

$ git fetch origin
$ git glog HEAD..origin/master

[jkitzes]

@wking, yes, I find these abbreviated log commands very useful for teaching. I like using --all in this case because it makes the alias more useful for visualizing branches, which I teach later in that lesson. I do think it's appropriate for novices, as we teach novices branching, which I think is unnecessarily hard to learn without some sort of visual aid.

I agree with the idea of using command line calls like this in the lessons (both novice and intermediate) and mentioning GUI's at the end as something the students might want to look into on their own time.

[wking]

On Sun, Jan 26, 2014 at 11:08:41AM -0800, Justin Kitzes wrote:

I like using --all in this case because it makes the alias more
useful for visualizing branches, which I teach later in that lesson.

I agree that --all is good for the lessons. I just think that the
alias is more flexible without the --all, and you can have your
students invoke:

$ git glog --all

explicitly when you do want to see everything (which may be all the
time for these lessons).

I agree with the idea of using command line calls like this in the
lessons (both novice and intermediate) and mentioning GUI's at the
end as something the students might want to look into on their own
time.

Sounds good to me. Pointing folks towards non-core GUIs (instead of
using them in class) lets us avoid system-compatibility and
closed-source issues. I think a pointer to the core GUIs is probably
useful to.

[ahmadia]

Sorry to join the discussion late, but thanks for the pointers. I think
there's room for pointing to the popular Git GUIs and an alias.

On Sun, Jan 26, 2014 at 1:20 PM, W. Trevor King [email protected]:

On Sun, Jan 26, 2014 at 11:08:41AM -0800, Justin Kitzes wrote:

I like using --all in this case because it makes the alias more
useful for visualizing branches, which I teach later in that lesson.

I agree that --all is good for the lessons. I just think that the
alias is more flexible without the --all, and you can have your
students invoke:

$ git glog --all

explicitly when you do want to see everything (which may be all the
time for these lessons).

I agree with the idea of using command line calls like this in the
lessons (both novice and intermediate) and mentioning GUI's at the
end as something the students might want to look into on their own
time.

Sounds good to me. Pointing folks towards non-core GUIs (instead of
using them in class) lets us avoid system-compatibility and
closed-source issues. I think a pointer to the core GUIs is probably
useful to.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/243#issuecomment-33327052
.

[rhiever]

There are a number of other GUIs [3], including git-gui and gitk which
are distributed with Git itself. If we're going to teach from a GUI,
I think git-gui is the way to go. It's even installed automatically
by Git Bash / msysGit. I've never actually used it (or any other Git
GUI) though, except for a few gitk and gitg screenshots.

Just to clarify my position on this: I think it's a terrible idea to teach from the GUI, especially the GitHub GUI. I've tried this before with a few students and it didn't work out well at all.

Anyway, I think we're all on the same page here. Yay!

[gvwilson]

Can we merge this intermediate material, then open a separate PR on "what to say when about Git GUIs"?

[rhiever]

I'm 👍 on that as long as @ahmadia feels he's addressed the other
concerns raised. (He's the one who raised most of them, I just documented
them.)

On Monday, January 27, 2014, Greg Wilson [email protected] wrote:

Can we merge this intermediate material, then open a separate PR on "what
to say when about Git GUIs"?

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/243#issuecomment-33370958
.

Randal S. Olson

Computer Science PhD Student
Michigan State University
E-mail: [email protected] | Twitter:
@randal_olsonhttps://twitter.com/randal_olson
http://www.randalolson.com

[ethanwhite]

I'm +1 as well (sorry to not be on top of this one @ahmadia). This is great material and we should go ahead and get it in even if there are a few things related to GUIs that we want to clean up afterwards.

@ahmadia - let me know if you have any last things you want to take care of before the merge, otherwise I'll go ahead and push the big green button.

[ahmadia]

The material is still fairly rough but I'm okay with you merging it in.

A

On Monday, January 27, 2014, Ethan White [email protected] wrote:

I'm +1 as well (sorry to not be on top of this one @ahmadiahttps://github.com/ahmadia).
This is great material and we should go ahead and get it in even if there
are a few things related to GUIs that we want to clean up afterwards.

@ahmadia https://github.com/ahmadia - let me know if you have any last
things you want to take care of before the merge, otherwise I'll go ahead
and push the big green button.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/243#issuecomment-33371745
.