Episode 4: the staging area should be explained earlier

[dubst3pp4]

In Episode 4, "Tracking Changes", the first usage of git add was introduced with the sentence

We can tell Git to track a file using git add

And after the file gets added by the learner, the git add command is explained with

Git now knows that it’s supposed to keep track of mars.txt [...]

The problem here is, that the student might think, that you only need to add a file once, as from this moment on Git knows this file.

After the first commit, the effect of the sequence git add and git commit is explained as follows:

When we run git commit, Git takes everything we have told it to save by using git add and stores a copy permanently inside the special .git directory. This permanent copy is called a commit [...]

It is confusing that now git add is explained as a command "to save" a file, whereas only some sentences earlier it was the command to let Git keep track of the file.

The concept of the Staging area (or index, as referred to in the Git manual), should be briefly explained already at this point. This is what man git add says:

This command updates the index using the current content found in the working tree, to prepare the content staged for the next commit. [...]

The "index" holds a snapshot of the content of the working tree, and it is this snapshot that is taken as the contents of the next commit. Thus after making any changes to the working tree, and before running the commit command, you must use the add command to add any new or modified files to the index.

This command can be performed multiple times before a commit. It only adds the content of the specified file(s) at the time the add command is run; if you want subsequent changes included in the next commit, then you must run git add again to add the new content to the index.

To summarize, git add lets Git remember the changes you have applied to a file on your disk, to save them permanently at a later time into your repository.

As I used Git the first time a decade ago, I had exactly this problem in understanding the differences between the changes in the (physical) file, the changes that are added to the index and the changes that are recorded as a commit.

I know that the staging area is introduced later by intention, but I think that this part could be a stumbling block for new learners, especially those that don't have a computer science background.

Maybe we could rework this little section to find more precise words that aren't too confusing? Any hints?

[kekoziar]

Thank you for the feedback. A guiding principle of lesson development in The Carpentries is to reduce cognitive load on learners. The pedagogy model is to demonstrate code then explain what happened. The instructor training states, "presenting novices with a pile of facts early on is counter-productive, because they do not yet have a model or framework to fit those facts into. In fact, presenting too many facts too soon can actually reinforce an incorrect mental model." The challenge, especially for experts, is to use accurate language that a novice completely understands so they can build a mental model.

The staging area is a larger mental model than a commit, and doesn't make sense outside of the commit mental model. IMO, explaining the concepts of the staging area before a learner has experienced a commit is the opposite of the Carpentries' pedagogy model.

That said, we are always looking for improvements to the lesson, especially contributions that provide clarity. Please feel free to share a rewrite of the staging area section that provides clarity for new learners, while minimizing time added to the lesson.