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

From: Julia Evans <julia@jvns.ca>
Date: Aug 14, 2025, 02:59 UTC
Message-ID: <e1c9f388-f72c-4bb4-b05d-b5b183501456@app.fastmail.com>
In-Reply-To: <xmqq4iuabup7.fsf@gitster.g>

Show 9 quoted lines

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

Thanks, I think this is the perfect example and it gets at something about git add that i’ve never totally understood: why are the earlier snapshots discarded?

Naively, one might think that:

1. the git index is just a tree object
2. when you commit, Git takes that tree object, attaches a
   message, and makes a commit with it
3. git maintains some sort of history (like the reflog) for the past "index"
   tree objects

If Git worked that way, I imagine it would be possible to implement the feature you describe, and I feel like there's some sort of obvious reason (something to do with performance?) for why the index isn't implemented this way that I've never learned.

This example makes me think that if we want people to understand the limitations of the index, it's important to communicate that the past index snapshots are *discarded* and not just that the index is a snapshot.