Suggestion for improving the git staging area graphic

[unicrey]

I am referring to the graphic http://swcarpentry.github.io/git-novice/fig/git-staging-area.svg found in the episode http://swcarpentry.github.io/git-novice/04-changes/index.html about halfway through the episode.

I think there is a dissonance between the metaphor used in the text and the graphic that goes with it. The text talks in terms of a photo capturing metaphor. git add is adding things to the frame of a snapshot and git commit actually takes the snapshot. I feel this is very intuitive. This is even carried forward with the idea of git commit -a being something like a group photo where any random person could appear.

On the other hand, the graphic shows documents on a cylinder as the staging area and the cylinder is then stacked atop other cylinders to represent the repository. While this is a fine graphic, I feel it does not go well with idea of a 'frame' from the text.

Instead, we could have something like a rectangular photo frame for the staging area and a stack of photographs to represent the repository. One or two documents would be shown within the frame and the top photograph and a couple of documents could be shown outside the frame.

Additionally, extending the photo capturing metaphor, .gitignore could be explained in later episodes as putting a filter on the lens so some files are invisible to the git frame.

[markmatney]

I feel the dissonance as well. While I think it's valuable to have abstract conceptual models in the lesson (in case an instructor judges them appropriate for their workshop), I agree that the "Git as a photographer" analogy is compelling and should be developed more. Perhaps this can be a source of inspiration? 😄 (thanks to @jt14den for showing me that lesson)

And I like your idea of extending it to .gitignore. Although, instead of comparing it to a lens filter, what about: a request to not be recorded? ("Photographer, I'd prefer not to be filmed / please don't take my picture"). I like this better because it gives human subjects more agency and avoids questions about the construction/purpose of a hypothetical people-filter. "Out-of-frame by request", vs. "in-frame but edited/blocked out".

[unicrey]

'git as a photographer' sounds good. That image you refer to is exactly the kind of thing I had in mind.

I hadn't thought of it that way regarding the filter. It's a very important point about the appropriate cultural context of our analogies.

[djbordelon]

In a recent git workshop I used a "photo booth" metaphor--the camera only captures what is inside the booth (i.e., staged for commit). Things may be going on outside the booth that are not captured (untracked files, .gitignore). The "snapshots" (commits) are collected in an "album" which forms your git repo.

[markmatney]

That's an interesting idea. Although, if the photo booth implements both "tracking" and "ignoring" (presumably with the boundary that it introduces to separate "inside" from "outside"), the distinction between the two operations seems to me a bit blurred w.r.t. the metaphor, and a potential point of confusion for learners. How did you maintain that distinction? Were there any follow-up questions?

[kekoziar]

The analogy and the image are two different ways of representing what's going on. The image doesn't need to reflect the analogy. When we teach it some learners will understand after we read the analogy, and some will understand when we show the image. The two examples are there because it allows different mental images to help different learners with the concept.

But, @unicrey the call-out in the middle of episode 4 is the only place the photo analogy is used, while the format of the image is used throughout the lesson. How would changing the image to what you propose impact the rest of the images in the lesson?

[markmatney]

I think part of the "dissonance" feeling might be coming from the image being positioned directly after the "Staging Area" call-out box -- something about that (at least to me) is communicating that the two are meant to accompany each other.

To me, the text preceding the call-out box is a better lead-up to the image, so how about we move the image in question above that call-out box (and perhaps also put a colon at the end of "but not yet committed")?

[erinmgraham]

Hi All,

Thank you for your contribution to the git-novice repository. We noticed that this issue has been inactive since 2021 and it seems that the conversation has come to a halt. To keep our repository clean and focused, we are closing this issue for now.

If you believe this issue still needs attention, please feel free to reopen it or create a new one with updated details.

Thank you for your understanding and support!