Some clarifications needed for file states

[lteblmr]

In section "Recording Changes to the Repository" there is a sentence:

Remember that each file in your working directory can be in one of two states: tracked or untracked.

but there is no previous definitions of "tracked" and "untracked" states for files, so there is no previous reference to remember from. The only previous mention of the "file states" was in section "1.3 Getting Started - What is Git?" where it says "Git has three main states that your files can reside in: committed, modified, and staged:"

The next sentence says:

Tracked files are files that were in the last snapshot; they can be unmodified, modified, or staged. In short, tracked files are files that Git knows about. Untracked files are everything else — any files in your working directory that were not in your last snapshot and are not in your staging area. When you first clone a repository, all of your files will be tracked and unmodified because Git just checked them out and you haven’t edited anything.

So tracked files are "files that were in the last snapshot which can be unmodified, modified, or staged" and "untracked files are everything else". Then in the next diagram you show that Untracked files can be moved to Staged location by the "add the file" operation. So is this file now tracked or untracked? My reasoning goes like this: It is new file so it's not in the last snapshot, so according to the first definition it is still untracked. But according to the second definition "untracked files are neither in the last snapshot nor in the staging area" this file can't be untracked because it is staged. So file is at the same time untracked and not untracked which is confusing.

Note: I understand that you are simplifying things in these first chapters but I feel this part is confusing (at least it confuses me everytime I come to it) so I am reporting it here.

[ben]

Fair enough. This is a really tricky section of the book to get right, since there is a broad set of backgrounds that lead here, and we want to get everybody over the hump to understanding how Git thinks of the files. What we invariably end up with is something that isn't quite perfect for anybody.

Can you think of a better way to word this? We should probably avoid the term "state," since that has an actual technical meaning, and doesn't really work in this context anyways.

[tabathap]

👌

[HonkingGoose]

I agree that the statement that a file can be only in one of two states is not technically correct. But we do help the reader understand that a file can have both staged changes, and new unstaged changes. So that (parts of) the file can be in both states as one.

Relevant snippets from recording-changes.asc, emphasis on the key point is mine:

git add is a multipurpose command — you use it to begin tracking new files, to stage files, and to do other things like marking merge-conflicted files as resolved. It may be helpful to think of it more as “add precisely this content to the next commit” rather than “add this file to the project”.

And then a little bit further on we explain that the file is both staged and unstaged:

What the heck? Now CONTRIBUTING.md is listed as both staged and unstaged. How is that possible? It turns out that Git stages a file exactly as it is when you run the git add command. If you commit now, the version of CONTRIBUTING.md as it was when you last ran the git add command is how it will go into the commit, not the version of the file as it looks in your working directory when you run git commit. If you modify a file after you run git add, you have to run git add again to stage the latest version of the file:

Yeah this is really hard to get right. I'm thinking that it's a bit more time-based: you have previously staged a change, that change is now staged. And later you made another change, but that change is not staged yet.

Then I was thinking, maybe we can only refer to line level changes, but that also breaks down, as one line can also have staged and unstaged changes at the same time.

I really don't know a better explanation than what we have now. Maybe it's okay to simplify at first, and then once the reader understands the cycle of changes, then give them the more complicated picture?

[ben]

That's always been my approach, and flawed as it is it still seems better than the alternatives. @lteblmr, what would you like to see as the outcome of this issue?