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:

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

I suspect that you need to look at the whole thing backwards.  I
realize that it is another way to say that you are looking at the
whole thing backwards, so take your pick ;-).

Nobody stops you from extending the system to store more than one
snapshots in the index and allow your users to roll back to one of
these snapshots kept in the index.  The reason why we haven't done
so is because there has not been motivating any use case for such a
feature (and coming up with a reasonable UI for it would also be
more work).  After all, if you want to keep a set of good points to
go back to [*], that is what commits are for in the world view of
Git, where creating commits and moving around in history are cheap.
If it were something worth going back to, you'd do so at the commit
level.  "git stash" and its index operations (like the "--keep"
option that allows you to test with only what is in the index) are
implemented as (temporary) commits internally exactly for this
reason.

Having said that, there is a focused support to record the previous
state before a snapshot records a resolution for a conflicted path
[**].  This was added because of a concrete motivating use case to
allow you to recover from a botched conflict resolution (aka "gee, I
thought this resolution was OK but I did 'git add' way too early,
before I actually tested the result!"), where "you can commit to
mark the place to later go back" principle does not cleanly apply,
since commits in Git do not record conflicted state.

Please don't keep asking "why" on this point (i.e. "why not record
conflicts in commit?") and other things---at some point, the answers
will become a series of "that is how it is, and it has been good
enough for us", and then it becomes a waste of time to further ask
"why".  Until "here is the change I made to do things differently;
please see how well it works" materializes, that is.


[Footnote]

 * This is another example why the snapshot worldview gives clear
   workflow.  After you pile on several drunken-walk experimental
   commits on top of a good commit and realize that this particular
   line of effort is leading nowhere, you "jump back" to that known
   good point (i.e. "git reset --hard HEAD~7").  You do not have to
   apply these changes in reverse direction (i.e. "git apply -R") in
   reverse order (i.e. "git rev-list --reverse HEAD~7..".

** Read about "Resolve undo" in the documentation.