Re: Feedback on git-restore
- Date: Sat, 18 May 2019 15:19:58 +0100
- From: Philip Oakley <philipoakley@xxxxxxx>
- Subject: Re: Feedback on git-restore
On 16/05/2019 13:44, Duy Nguyen wrote:
On Thu, May 16, 2019 at 7:12 PM Philip Oakley <philipoakley@xxxxxxx> wrote:
Maybe we need a `git index` command to make it far more visible to
average users (or `git staging-area --show`, with a --cached option ;-).
Not commenting on the other parts (and also Junio's mail) since I
still need more time to process.
But how about we see the index as a "commit-in-progress" (or "staging
area" which is almost the same, maybe "commit area" is better)?
My initial comment was more about the cognitive disconnect between
Victor's original reply where he has the commit and the file system as
the (only) firm reference points, and then your reply, which makes the
case that the _Index_ is central.
It was that disconnect that I wanted to highlight, which is at a level
above the discussion on just the restore command.
There was a lot of discussion a year or three back about the terminology
of cache/Index/staging for this middle area. It probably wasn't resolved
fully as it only discussed the name, rather than why the concept wasn't
well understood, and what was needed to fix _that_.
I'd say most users feel happy about the fixedness of their last commit,
and probably feel happy with the ability to view it via various tools
(especially if pushed to their GitHub/Lab/Bucket repo). The apparently
transient nature of the index is part of its Achilles heel. We talk too
easily about 'blowing it away' . Such phrases reinforce the user
belief that they should treat it as a bit of a swamp area.
You can't make a commit visible unless you check it out (and then can
use various tools available to work on filesystem), or you use git
diff/show to examine it. The index is treated pretty much the same
way, except that it does not have a proper SHA-1 yet because it's
still a work in progress.
We don't have an index_log of the changes to the staging tree, as files
are added or removed. That view implies that the index is simply the
current work-in-progress (wip) tree, and doesn't contain anything else..
Surely? the 'git status' command  is, in a way, trying to be that
view, but we just haven't told the users
Short of creating a fuse filesystem to show you the index content (as
read-only files) I don't see any better way that you can actually see
the index without checking it out.
The role during merges would be part of that missing conceptual
structure. Our documentation is doing a little too much of the 'ignore
what's behind the curtain' . I've certainly fallen for that often.
The need for various web explanations e.g. [3,4] also suggest we could
be more assertive in our top level user documentation about 'index is
one of the most important data structures in git'.
PS. Yes I ignored the role of the index during a merge conflict. Not
relying on the index for conflict handling might be possible, but I'm
not going to touch that topic, way out of my area.
In summary, I think the problem that Victor alludes to is at a higher
level with respect to how we document what the staging area / index is
 e.g. https://shafiul.github.io//gitbook/1_the_git_index.html
 Wizard of Oz, Powerful concept, vs loose tools.