Re: Feedback on git-restore

[Philip Oakley <philipoakley@iee.org>]

Hi Duy,

On 16/05/2019 13:44, Duy Nguyen wrote:
> On Thu, May 16, 2019 at 7:12 PM Philip Oakley <philipoakley@iee.org> 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)?
I'd agree.

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_.
>
> 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.
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' [1].  Such phrases reinforce the user 
belief that they should treat it as a bit of a swamp area.

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..
>
> 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.
Surely? the 'git status' command [1] is, in a way, trying to be that 
view, but we just haven't told the users
>
> 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.
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' [2]. 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'.

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

Philip

[1] e.g. https://shafiul.github.io//gitbook/1_the_git_index.html
[2] Wizard of Oz, Powerful concept, vs loose tools.
[3] 
https://stackoverflow.com/questions/4084921/what-does-the-git-index-contain-exactly,
[4] https://mincong-h.github.io/2018/04/28/git-index/