Subject: Re: [PATCH 2/5] doc: git-add: start man page with an example

From: "Julia Evans" <[email-masked]>
Date: Tue, 12 Aug 2025 17:40:19 -0400

> 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".