Suggestion for the clarification of `git diff` command in the Tracking Changes lesson

[ebrahimifard]

In the Tracking Changes episode of the Version Control with Git lesson, git diff command has been used in two different forms of without any switch and with --staged switch. The one without switch is introduced as "the differences between the current state of the file and the most recently saved version" and the other one is explained as "the difference between the last committed change and what’s in the staging area.".

Although they may seem fine, they are not accurate (especially the explanation of git diff). What this command in general does is to give us a report of the difference between various states of our files. Those states could be working directory, staging area, and commit. Thus, to make the above mentioned commands more precise, I suggest to change their definitions to the followings:

• git diff: difference between the working directory and the last commit

• git diff --staged: difference between the staging area and the last commit

[kekoziar]

Hello, @ebrahimifard. Thank you for your comment. A guiding principle of lesson development in The Carpentries is to reduce cognitive load on learners. In everyday language, git diff does "[show ...] the differences between the current state of the file and the most recently saved version." There is nothing false about that statement, although I can see why some experts would have issues with its lack of precision.

This lack of precision vs accessibility is a fine line that experts must be aware of and balance while they are teaching (or developing a lesson). Experts have stronger connections to precise terminology and their relationships, but this means that conclusions that seem obvious to experts are not obvious to learners.

How would you propose to reword a definition of git diff and git diff --staged in non-technical everyday language so that its function is obvious to novice learners?

[dbarbi]

I agree with @ebrahimifard and would not try too hard to go for a less technical wording. I see that learners should be able to understand without too much of a cognitive load, but on the other hand, sooner or later they will have to understand the technical language anyway, to understand other publications, such as manuals or user forums.

[astroDimitrios]

I would agree that the wording could be clarified - @kekoziar perhaps dual coding the info with a graphic like the one at the end of the lesson would help?

You could add in git diff HEAD as well although this might be too much.

[erinmgraham]

I like the wording as suggested by @ebrahimifard and think it's more clear and consistent with terminology used earlier. By this time learners know what working directories and commits are and I note that "the most recently saved version" typically refers to the version that has been committed but earlier in the lesson we use 'save' for both add and commit which is arguably more confusing. In the absence of further comment from @kekoziar, my preference is to go ahead with the change to the text and include the graphic.

[fkohrt]

Maybe related, I stumbled upon the following sentence today:

Note that HEAD is the default option for git diff, so omitting it will not change the command’s output at all (give it a try).

I found this to be very confusing, because the output is only the same if no additional files have been staged since the last commit.

[fkohrt]

Regarding the proposed definition of git diff by @ebrahimifard, I cannot see how "difference between the working directory and the last commit" is better than "the differences between the current state of the file and the most recently saved version". Correct me if I'm wrong, but what git diff (without any arguments) does is compare workspace and staging area. The tutorial puts this nicely a few lines below: "[the] difference between what it’s been asked to save permanently and what’s currently in the directory". So why not use that definition throughout?