> But isn't it the source of the most end-user confusion that they > cannot wean themselves off of the diff/patch worldview? To me it feels very contextual! My impression is that what's important for Git users is to be able to think about commits as diffs in some contexts, and as snapshots in other contexts. For example with `git rebase` I'm usually thinking of my commits as diffs, but it's very helpful to me to think of a merge commit as a snapshot, because the merge commit does not have to be a "combination" of the two sides of the merge, it can have arbitrary extra content. > Wouldn't "add file X" confuse folks who still remember how other > SCMs before Git operated (i.e. "file X is now known, so if I make > further changes to X next 'commit' command will record it") into > thinking that Git would do the same? The point about Subversion is interesting: I would expect that most people learning about Git's data model in 2025 have never used Subversion. So while I think it's extremely important to make accurate statements while talking about Git (and I think it's very possible that this description is not accurate enough!), I do not think it's so important to specifically target misconceptions that users coming from Subversion/CVS may have. >> +By default, `git commit` only commits changes that you've added to the >> +index. For example, if you've edited `file.c` and want to commit your >> +changes, you can run: >> + >> + git add file.c >> + git commit > > What happens when you did "edit && add && edit && add"? It commits > the two changes you added to the index? I do not think it is > productive to hide the fact that you are preparing a snapshot of the > "next commit" in the index (or "staging the contents for the next > commit in the staging area") with various forms "git add", including > "git add -p". It could! It's easy for me to imagine a world where the index stores an ordered list of diffs, which are applied as patches in series when I commit. I guess you'd need some sort of patch + patch + patch + diff workflow to generate the final diff, but to me that doesn't feel so different from what Git is actually doing in practice. In any case, I'll think more about whether I think this is really an accurate description. I'm always especially interested in the practical consequences of having misconceptions about Git: for example (and maybe I'm convincing myself to change my position here!) with `git mv` I think it can become relevant pretty quickly that commits are snapshots, because if you move a file and edit it then Git can't always accurately guess that you intended to "move" the file rather than delete the file and create a new one. I'd like to be able to have a similarly practical example of why it's important to think of commits as snapshots in the context of `git add` but I haven't quite found the right one yet. I've noticed that people will often sort of "reject" information that does not fit their mental models, and I think "commits are snapshots, this is important in this context because of <specific practical consequence>" is much more convincing than just "commits are snapshots".
