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

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 14, 2025, 00:41 UTC
Message-ID: <xmqq4iuabup7.fsf@gitster.g>
In-Reply-To: <152d47a3-7744-476a-8ab8-43b7b52b67ea@app.fastmail.com>

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

Show 6 quoted lines

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