Web lists-archives.com

Re: Feedback on git-restore

Hi Duy,

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


[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/