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

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

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