Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

ebrahimifard opened this issue Nov 20, 2020 · 2 comments


Copy link

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

Copy link

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?

Copy link

dbarbi commented Sep 1, 2021

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.

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

No branches or pull requests

3 participants