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

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans" <julia@jvns.ca> writes:

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

There is an easier-to-understand example.  If you pretend that you
"add" series of "diff/patch" to the index as you repeat "edit &&
add" three times, in the mental model of the users, there would be
three set of patches stored in the index somehow.  It would be a
fair wish for the users to have to be able to revert only the change
you added with your second "git add" while keeping the first one and
the third (latest) one.  You cannot explain why you fundamentally
cannot give them such a new "feature", until you admit that what is
recorded is the latest snapshot and earlier snapshots are discarded.

Another thing that the "collection of diff/patch" view probably
harms understanding of users is merge, which is not a set of diffs,
one for each parent and the merge result.  Of course, as a merge is
symmetric across the parents, it is not diff between the first
parent and the merge result, either.