Misleading Interplay between Episode 4 and 5
will-cowen opened this issue · comments
How could the content be improved?
At the end of Episode 4 is a callout titled "Directories" which includes instruction on how directories can be handled, including a creating a spaceships directory, two files, and a commit to the repo.
This commit happens outside the "main flow" of the document, and by occurring inside a callout there is the implication that it is optional.
However, in lesson 5 there is the command $ git diff HEAD~3 mars.txt which, if the episode 4: directories spaceship commit has been skipped, will return fatal: ambiguous argument 'HEAD~3': unknown revision or path not in the working tree.
I would recommend altering either episode 4 to ensure the spaceship commit occurs in the main document flow OR changing episode 5 diff commands to use HEAD~2 to avoid potentially ambiguous references.
Which part of the content does your suggestion apply to?
Episode 4: Directories callout
I ran into exactly this issue just now. Having the "directories" stuff as optional causes exactly that issue. So it should be made non-option by removing it from the callout, or it should be done in a way that allows skipping it without causing issue. For example omitting the "git commit -m "Add some initial thoughts on spaceships" might be one way to mitigate the issue.
Similarly, the "Committing Multiple Files" exercise below could also add similar confusion as it also introduces a new commit to the main repository we are working with. While this wouldn't lead to the "unknown revision" as mentioned previously, it would lead to inconsistent output as that shown in the lesson.
My proposal would be to change HEAD~3 to HEAD~2. If the optional directories callout is followed, the output will be inconsistent, but at least won't lead to the "fatal" result. I will submit a pull request for that change.