{"thread":{"id":"51097","subject":"Feedback on git-restore","startedAt":"2019-05-15T09:48:50Z","lastAt":"2019-05-18T14:20:02Z","messageCount":8,"participants":["Poughon Victor","Duy Nguyen","Ævar Arnfjörð Bjarmason","Junio C Hamano","Philip Oakley"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"375616","messageId":"3E55146A6A81B44A9CB69CAB65908CEA6B91353C@TW-MBX-P01.cnesnet.ad.cnes.fr","threadId":"51097","inReplyTo":null,"subject":"Feedback on git-restore","fromName":"Poughon Victor","fromEmail":"victor.poughon@cnes.fr","sentAt":"2019-05-15T09:38:59Z","receivedAt":"2019-05-15T09:48:50Z","isPatch":false,"sender":{"key":"victor.poughon@cnes.fr","avatar":null},"body":"Hi\n\nI came across a description of a new git command currently in development called 'git restore'. Since it's still not out, and the original poster [1] seemed to ask for feedback, I though I'd send some here. Hope that's ok!\n\nReading the documentation [2] I find it very confusing. In particular when comparing the following two commands:\n\n$ git restore --staged file\n$ git restore --worktree file\n\nWith the current proposal, the first will restore the index from HEAD, while the second will restore the worktree from the index. In other words, the source for the restore is different in both commands, even though neither specify a source! This means that git-restore really does two different things depending on some other not obvious context. Unfortunately that's typical of the (often criticized) obscure interface of git. To be fair that behavior is documented in [2]. But still, having a variable default value for --source depending on other arguments is very confusing.\n\nSo in summary, I'd make two recommendations for this command's UX:\n1. Make --source default value always HEAD if unspecified\n2. Rename --staged to --index\n\nSome examples of those:\n\n$ git restore --index file # reset the index from HEAD\n$ git restore --worktree file # reset the worktree from HEAD\n$ git restore --worktree --source=index file # reset the worktree from the index\n$ git restore --index --worktree file # reset both the index and worktree from HEAD\n$ git restore file # reset the worktree from HEAD \n\n[1] https://news.ycombinator.com/item?id=19907960\n[2] https://github.com/git/git/blob/pu/Documentation/git-restore.txt\n\nBest,\nVictor\n\n\n\n"},{"id":"375617","messageId":"20190515103031.GA29149@ash","threadId":"51097","inReplyTo":"3E55146A6A81B44A9CB69CAB65908CEA6B91353C@TW-MBX-P01.cnesnet.ad.cnes.fr","subject":"Re: Feedback on git-restore","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2019-05-15T10:30:31Z","receivedAt":"2019-05-15T10:30:39Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Wed, May 15, 2019 at 09:38:59AM +0000, Poughon Victor wrote:\n> Hi\n> \n> I came across a description of a new git command currently in\n> development called 'git restore'. Since it's still not out, and the\n> original poster [1] seemed to ask for feedback, I though I'd send\n> some here. Hope that's ok!\n>\n\nAbsolutely. And this is even better because other people could also\ncomment on.\n\n> Reading the documentation [2] I find it very confusing. In\n> particular when comparing the following two commands:\n> \n> $ git restore --staged file\n> $ git restore --worktree file\n> \n> With the current proposal, the first will restore the index from\n> HEAD, while the second will restore the worktree from the index. In\n> other words, the source for the restore is different in both\n> commands, even though neither specify a source!\n>\n> This means that git-restore really does two different things\n> depending on some other not obvious context. Unfortunately that's\n> typical of the (often criticized) obscure interface of git. To be\n> fair that behavior is documented in [2]. But still, having a\n> variable default value for --source depending on other arguments is\n> very confusing.\n\nI think it depends on whether use actively use the index, or you\nmostly ignore it and always do \"git commit -a\" and friends.\n\nWhen you do use the index, the \"worktree <-> index <-> HEAD\" is the\nthree stages that you are aware, in that order, and restoring from the\n\"next\" stage is expected.\n\nIt does feel natural for me that we \"restore worktree from the index\"\nand \"restore index from HEAD\". But maybe I'm just too used to the old\nway of thinking? Let's see what other people say.\n\nThis is also consistent with other commands, for example \"git diff\n--staged/--cached\" compares the index and HEAD and \"git diff\" compares\nworktree and the index. You would need extra effort e.g. \"git diff\nHEAD\" to compare the worktree and HEAD.\n\nIf your workflow ignores the index, which should always match HEAD,\nthen different default source is practically gone, since\nindex == HEAD.\n\n> So in summary, I'd make two recommendations for this command's UX:\n> 1. Make --source default value always HEAD if unspecified\n> 2. Rename --staged to --index\n\nThis --index vs --staged was discussed and --staged is a compromise.\nThe problem is --index means something different in existing\ncommands. It specifies that you want to target both the index _and_\nworktree. --cached on the other hand only targets the index [1].\n\nIt's confusing, yes. But --index/--cached is part of Git and we cannot\njust ignore our baggage and redefine --index to \"just index\". That\nwill create more confusion and inconsistency between commands.\n\"--index\" is simply not available.\n\nSo the compromise is we leave --index/--cached alone and gradually\nmove to the --staged/--worktree combo (for other commands as well).\nEventually I hope people will move to the second pair and mostly\nforget about --index/--cached. And in a very long long time in the\nfuture, maybe we can deprecate/remove/redefine --index/--cached.\n\n[1] https://github.com/git/git/blob/pu/Documentation/gitcli.txt#L179-L199\n\n> Some examples of those:\n> \n> $ git restore --index file # reset the index from HEAD\n> $ git restore --worktree file # reset the worktree from HEAD\n\nI should also note that --worktree is the default, you can just write\n\n$ git restore file\n\nand achieve the same thing. Writing --worktree is only needed when you\nwant to make it clear to the reader you're restoring the worktree.\n\n> $ git restore --worktree --source=index file # reset the worktree from the index\n> $ git restore --index --worktree file # reset both the index and worktree from HEAD\n> $ git restore file # reset the worktree from HEAD \n> \n> [1] https://news.ycombinator.com/item?id=19907960\n> [2] https://github.com/git/git/blob/pu/Documentation/git-restore.txt\n> \n> Best,\n> Victor\n> \n> \n> \n"},{"id":"375624","messageId":"20190515111647.GA31209@ash","threadId":"51097","inReplyTo":"87d0kkvv96.fsf@evledraar.gmail.com","subject":"Re: Feedback on git-restore","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2019-05-15T11:16:48Z","receivedAt":"2019-05-15T11:57:39Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Wed, May 15, 2019 at 12:59:17PM +0200, Ævar Arnfjörð Bjarmason wrote:\n> One thing that would be really useful (and maybe it even exists, I just\n> haven't seen it in the mails) is some abbreviated cheatsheet style doc\n> of before/after in the UI. Similar to cheatsheets like e.g.:\n> \n>     https://git.wiki.kernel.org/images-git/7/78/Git-svn-cheatsheet.pdf\n>     http://unix4admins.blogspot.com/2013/03/unix-commands-comparison-sheet.html\n> \n> As far as I can tell the best examples are your changes to\n> s/checkout/[reset|switch]/ in various existing docs, that's great, but\n> isn't so easy to understand at a glance.\n\nOK the cheatsheet would be like this (I'm dropping \"git\" prefix to\nkeep it short)\n\ncheckout <branch>          -> switch <branch> (same \"dwim\" behavior)\ncheckout <revision>        -> switch --detach <revision>\ncheckout -b <branch> <rev> -> switch -c <branch> <rev>\ncheckout <path>            -> restore [--worktree] <path>\ncheckout <rev> -- <path>   -> restore --source=<rev> --worktree --staged <path>\nreset <path>               -> restore --staged <path>\nreset <rev> -- <path>      -> restore --source=<rev> --staged <path>\nreset --hard               -> restore --source=HEAD --staged --worktree :/\n(not available now)        -> restore --source=<rev> [--worktree] <path>\n\nThere are other behavior changes to improve things, e.g. --no-overlay\nis the default in \"git restore\". But those can't be shown in a cheatsheet.\n--\nDuy\n"},{"id":"375625","messageId":"87d0kkvv96.fsf@evledraar.gmail.com","threadId":"51097","inReplyTo":"20190515103031.GA29149@ash","subject":"Re: Feedback on git-restore","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2019-05-15T10:59:17Z","receivedAt":"2019-05-15T12:20:46Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Wed, May 15 2019, Duy Nguyen wrote:\n\n> On Wed, May 15, 2019 at 09:38:59AM +0000, Poughon Victor wrote:\n>> Hi\n>>\n>> I came across a description of a new git command currently in\n>> development called 'git restore'. Since it's still not out, and the\n>> original poster [1] seemed to ask for feedback, I though I'd send\n>> some here. Hope that's ok!\n>>\n>\n> Absolutely. And this is even better because other people could also\n> comment on.\n>\n>> Reading the documentation [2] I find it very confusing. In\n>> particular when comparing the following two commands:\n>>\n>> $ git restore --staged file\n>> $ git restore --worktree file\n>>\n>> With the current proposal, the first will restore the index from\n>> HEAD, while the second will restore the worktree from the index. In\n>> other words, the source for the restore is different in both\n>> commands, even though neither specify a source!\n>>\n>> This means that git-restore really does two different things\n>> depending on some other not obvious context. Unfortunately that's\n>> typical of the (often criticized) obscure interface of git. To be\n>> fair that behavior is documented in [2]. But still, having a\n>> variable default value for --source depending on other arguments is\n>> very confusing.\n>\n> I think it depends on whether use actively use the index, or you\n> mostly ignore it and always do \"git commit -a\" and friends.\n>\n> When you do use the index, the \"worktree <-> index <-> HEAD\" is the\n> three stages that you are aware, in that order, and restoring from the\n> \"next\" stage is expected.\n>\n> It does feel natural for me that we \"restore worktree from the index\"\n> and \"restore index from HEAD\". But maybe I'm just too used to the old\n> way of thinking? Let's see what other people say.\n>\n> This is also consistent with other commands, for example \"git diff\n> --staged/--cached\" compares the index and HEAD and \"git diff\" compares\n> worktree and the index. You would need extra effort e.g. \"git diff\n> HEAD\" to compare the worktree and HEAD.\n>\n> If your workflow ignores the index, which should always match HEAD,\n> then different default source is practically gone, since\n> index == HEAD.\n\nI haven't had time to follow the whole restore/switch effort in any\ndetail.\n\nOne thing that would be really useful (and maybe it even exists, I just\nhaven't seen it in the mails) is some abbreviated cheatsheet style doc\nof before/after in the UI. Similar to cheatsheets like e.g.:\n\n    https://git.wiki.kernel.org/images-git/7/78/Git-svn-cheatsheet.pdf\n    http://unix4admins.blogspot.com/2013/03/unix-commands-comparison-sheet.html\n\nAs far as I can tell the best examples are your changes to\ns/checkout/[reset|switch]/ in various existing docs, that's great, but\nisn't so easy to understand at a glance.\n\n>> So in summary, I'd make two recommendations for this command's UX:\n>> 1. Make --source default value always HEAD if unspecified\n>> 2. Rename --staged to --index\n>\n> This --index vs --staged was discussed and --staged is a compromise.\n> The problem is --index means something different in existing\n> commands. It specifies that you want to target both the index _and_\n> worktree. --cached on the other hand only targets the index [1].\n>\n> It's confusing, yes. But --index/--cached is part of Git and we cannot\n> just ignore our baggage and redefine --index to \"just index\". That\n> will create more confusion and inconsistency between commands.\n> \"--index\" is simply not available.\n>\n> So the compromise is we leave --index/--cached alone and gradually\n> move to the --staged/--worktree combo (for other commands as well).\n> Eventually I hope people will move to the second pair and mostly\n> forget about --index/--cached. And in a very long long time in the\n> future, maybe we can deprecate/remove/redefine --index/--cached.\n\nWe had some discussion around such UI changes in\nhttps://public-inbox.org/git/87zhtqvm66.fsf@evledraar.gmail.com/\n\nI'm not expecting us to agree any more on that ui.version config point\ntoday than then.\n\nBut I do think it would be really useful in such a cheatsheet to have a\nthird column of \"here's what the 2nd column look like if we were writing\ngit today / weren't worried about backwards compatibility\".\n\nIt would allow us to at least clearly document what we wanted to do, but\ndecided not to for backwards compatibility, and perhaps such a\nlightweight design doc could even inform future steps about deprecation\nand/or \"ui.version\" config etc.\n\n> [1] https://github.com/git/git/blob/pu/Documentation/gitcli.txt#L179-L199\n>\n>> Some examples of those:\n>>\n>> $ git restore --index file # reset the index from HEAD\n>> $ git restore --worktree file # reset the worktree from HEAD\n>\n> I should also note that --worktree is the default, you can just write\n>\n> $ git restore file\n>\n> and achieve the same thing. Writing --worktree is only needed when you\n> want to make it clear to the reader you're restoring the worktree.\n>\n>> $ git restore --worktree --source=index file # reset the worktree from the index\n>> $ git restore --index --worktree file # reset both the index and worktree from HEAD\n>> $ git restore file # reset the worktree from HEAD\n>>\n>> [1] https://news.ycombinator.com/item?id=19907960\n>> [2] https://github.com/git/git/blob/pu/Documentation/git-restore.txt\n>>\n>> Best,\n>> Victor\n>>\n>>\n>>\n"},{"id":"375686","messageId":"xmqq7ear5egz.fsf@gitster-ct.c.googlers.com","threadId":"51097","inReplyTo":"20190515103031.GA29149@ash","subject":"Re: Feedback on git-restore","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-05-16T02:18:36Z","receivedAt":"2019-05-16T02:19:50Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Duy Nguyen <pclouds@gmail.com> writes:\n\n> I think it depends on whether use actively use the index, or you\n> mostly ignore it and always do \"git commit -a\" and friends.\n>\n> When you do use the index, the \"worktree <-> index <-> HEAD\" is the\n> three stages that you are aware, in that order, and restoring from the\n> \"next\" stage is expected.\n>\n> It does feel natural for me that we \"restore worktree from the index\"\n> and \"restore index from HEAD\". But maybe I'm just too used to the old\n> way of thinking? Let's see what other people say.\n\nI am somewhat sympathetic to unexperienced users who do not \"get\"\nGit here, but because I still think you cannot make effective use of\nGit without understanding the workflow using the index as an \"extra\"\nlevel sitting between the working tree and the commits, I think it\nis a learning experience worth investing in for a new user to get\nused to the way of thinking you showed in the above paragraphs.\n\n> This is also consistent with other commands, for example \"git diff\n> --staged/--cached\" compares the index and HEAD and \"git diff\" compares\n> worktree and the index. You would need extra effort e.g. \"git diff\n> HEAD\" to compare the worktree and HEAD.\n\nExactly.\n\n> This --index vs --staged was discussed and --staged is a compromise.\n> The problem is --index means something different in existing\n> commands. It specifies that you want to target both the index _and_\n> worktree. --cached on the other hand only targets the index [1].\n>\n> It's confusing, yes. But --index/--cached is part of Git and we cannot\n> just ignore our baggage and redefine --index to \"just index\".\n\nAnother thing worth pointing out here may be that a user would stop\nfeeling it a baggage once the index-centric way of thinking sinks\nin.  Because the index is so central to the local use of Git\nworkflow (i.e. \"I am just cloning and pulling from the outside world\nto fllow along\" does not count), \"just the working tree and not the\nindex\" mode is an anomaly, until/unless you start talking about\ngoing backwards (e.g. \"I've smudged my working tree by mistake, and\nneed to recover by copying something out to it\", which is the mental\nmodel of \"restore\").\n\n\tSide note: while at the mechanical level what it does is an\n\tequivalent to what \"checkout -- <paths>\" does, the mental\n\tmodels are different.  \"checkout\" is still a way to move\n\tforward \"I need the contents of these paths in my next\n\tcommit to look like those in that tree-ish, so copy them out\n\tto the working tree (to e.g. compile test) and also to the\n\tindex (for e.g. the ease of committing after testing is\n\tdone)\".\n\n> So the compromise is we leave --index/--cached alone and gradually\n> move to the --staged/--worktree combo (for other commands as well).\n\nI think what is truly new and valuable is the \"working tree only,\nbypassing the index\" mode, but I am not sure if we want to always\nforce us to say both when we want to affect both the index and the\nworking tree, as the index is still central to the local workflow.\nI am not sure if there is a wide agreement with such a \"gradually\nmove to\" plan.\n\nAlso, when you want to only affect the indexed contents, wouldn't\nexisting \"--cached\" suffice?\n\nIOW, I do not mind --staged as a synonym for --cached, and --worktree\nas a useful addition, but I do not think these new pair should replace\nthe existing ones.\n"},{"id":"375723","messageId":"d8fd0d06-ec83-941f-c29f-2fea0efb6fd3@iee.org","threadId":"51097","inReplyTo":"xmqq7ear5egz.fsf@gitster-ct.c.googlers.com","subject":"Re: Feedback on git-restore","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2019-05-16T12:12:14Z","receivedAt":"2019-05-16T12:12:17Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 16/05/2019 03:18, Junio C Hamano wrote:\n> Duy Nguyen <pclouds@gmail.com> writes:\n>\n>> I think it depends on whether use actively use the index, or you\n>> mostly ignore it and always do \"git commit -a\" and friends.\n>>\n>> When you do use the index, the \"worktree <-> index <-> HEAD\" is the\n>> three stages that you are aware, in that order, and restoring from the\n>> \"next\" stage is expected.\n>>\n>> It does feel natural for me that we \"restore worktree from the index\"\n>> and \"restore index from HEAD\". But maybe I'm just too used to the old\n>> way of thinking? Let's see what other people say.\n> I am somewhat sympathetic to unexperienced users who do not \"get\"\n> Git here, but because I still think you cannot make effective use of\n> Git without understanding the workflow using the index as an \"extra\"\n> level sitting between the working tree and the commits, I think it\n> is a learning experience worth investing in for a new user to get\n> used to the way of thinking you showed in the above paragraphs.\nI would agree.\n\n\"the Index\" is grossly under-documented and explained. I still don't \nhave a proper understanding of all the multiple Nuances regarding the \nIndex concept. Only a moment ago I was reading a thread that talked \nabout having multiple indexes and the wrong one being referenced or locked.\n\nI tend to map the Index to an old-fashioned 'out-box' on the corner of \none's desk (from the days when everything was paper and cc really meant \na carbon copy made with carbon paper). One would work on a document and \nwhen 'finished' place it in the out-box, which also acted as a \nwork-in-progress (wip) box. Only later would a secretary/mail-person \ncome around to see what needed filing/sending.\n\nThe fact that there can be many indexes, with multiple stages (all \nun-named) is a further source of confusion. For the average user, the \nonly visible artefacts are those in the file system, and perhaps the \ncrisp memory of the last commit. So I can see where Victor is coming \nfrom. I don't think we should be solely relying on the experience of \nuser mistakes for their learning.\n\nMaybe we need a `git index` command to make it far more visible to \naverage users (or `git staging-area --show`, with a --cached option ;-).\n>> This is also consistent with other commands, for example \"git diff\n>> --staged/--cached\" compares the index and HEAD and \"git diff\" compares\n>> worktree and the index. You would need extra effort e.g. \"git diff\n>> HEAD\" to compare the worktree and HEAD.\n> Exactly.\n>\n>> This --index vs --staged was discussed and --staged is a compromise.\n>> The problem is --index means something different in existing\n>> commands. It specifies that you want to target both the index _and_\n>> worktree. --cached on the other hand only targets the index [1].\n>>\n>> It's confusing, yes. But --index/--cached is part of Git and we cannot\n>> just ignore our baggage and redefine --index to \"just index\".\n> Another thing worth pointing out here may be that a user would stop\n> feeling it a baggage once the index-centric way of thinking sinks\n> in.  Because the index is so central to the local use of Git\n> workflow (i.e. \"I am just cloning and pulling from the outside world\n> to fllow along\" does not count), \"just the working tree and not the\n> index\" mode is an anomaly, until/unless you start talking about\n> going backwards (e.g. \"I've smudged my working tree by mistake, and\n> need to recover by copying something out to it\", which is the mental\n> model of \"restore\").\n>\n> \tSide note: while at the mechanical level what it does is an\n> \tequivalent to what \"checkout -- <paths>\" does, the mental\n> \tmodels are different.  \"checkout\" is still a way to move\n> \tforward \"I need the contents of these paths in my next\n> \tcommit to look like those in that tree-ish, so copy them out\n> \tto the working tree (to e.g. compile test) and also to the\n> \tindex (for e.g. the ease of committing after testing is\n> \tdone)\".\n>\n>> So the compromise is we leave --index/--cached alone and gradually\n>> move to the --staged/--worktree combo (for other commands as well).\n> I think what is truly new and valuable is the \"working tree only,\n> bypassing the index\" mode, but I am not sure if we want to always\n> force us to say both when we want to affect both the index and the\n> working tree, as the index is still central to the local workflow.\n> I am not sure if there is a wide agreement with such a \"gradually\n> move to\" plan.\n>\n> Also, when you want to only affect the indexed contents, wouldn't\n> existing \"--cached\" suffice?\n>\n> IOW, I do not mind --staged as a synonym for --cached, and --worktree\n> as a useful addition, but I do not think these new pair should replace\n> the existing ones.\nIf the Index is central it need to be to get out from behind the \ncurtain. Just sayin'.\n\n--\nPhilip\n"},{"id":"375726","messageId":"CACsJy8D16A3VKdTFfVyENZoH4J7Dv-3iwovEgsUj07KUT8NBKA@mail.gmail.com","threadId":"51097","inReplyTo":"d8fd0d06-ec83-941f-c29f-2fea0efb6fd3@iee.org","subject":"Re: Feedback on git-restore","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2019-05-16T12:44:10Z","receivedAt":"2019-05-16T12:44:40Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Thu, May 16, 2019 at 7:12 PM Philip Oakley <philipoakley@iee.org> wrote:\n> Maybe we need a `git index` command to make it far more visible to\n> average users (or `git staging-area --show`, with a --cached option ;-).\n\nNot commenting on the other parts (and also Junio's mail) since I\nstill need more time to process.\n\nBut how about we see the index as a \"commit-in-progress\" (or \"staging\narea\" which is almost the same, maybe \"commit area\" is better)?\n\nYou can't make a commit visible unless you check it out (and then can\nuse various tools available to work on filesystem), or you use git\ndiff/show to examine it. The index is treated pretty much the same\nway, except that it does not have a proper SHA-1 yet because it's\nstill a work in progress.\n\nShort of creating a fuse filesystem to show you the index content (as\nread-only files) I don't see any better way that you can actually see\nthe index without checking it out.\n\nPS. Yes I ignored the role of the index during a merge conflict. Not\nrelying on the index for conflict handling might be possible, but I'm\nnot going to touch that topic, way out of my area.\n-- \nDuy\n"},{"id":"375856","messageId":"3f2a846e-ac69-c2c9-fd1b-0781f71d32ed@iee.org","threadId":"51097","inReplyTo":"CACsJy8D16A3VKdTFfVyENZoH4J7Dv-3iwovEgsUj07KUT8NBKA@mail.gmail.com","subject":"Re: Feedback on git-restore","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2019-05-18T14:19:58Z","receivedAt":"2019-05-18T14:20:02Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Duy,\n\nOn 16/05/2019 13:44, Duy Nguyen wrote:\n> On Thu, May 16, 2019 at 7:12 PM Philip Oakley <philipoakley@iee.org> wrote:\n>> Maybe we need a `git index` command to make it far more visible to\n>> average users (or `git staging-area --show`, with a --cached option ;-).\n> Not commenting on the other parts (and also Junio's mail) since I\n> still need more time to process.\n>\n> But how about we see the index as a \"commit-in-progress\" (or \"staging\n> area\" which is almost the same, maybe \"commit area\" is better)?\nI'd agree.\n\nMy initial comment was more about the cognitive disconnect between \nVictor's original reply where he has the commit and the file system as \nthe (only) firm reference points, and then your reply, which makes the \ncase that the _Index_ is central.\n\nIt was that disconnect that I wanted to highlight, which is at a level \nabove the discussion on just the restore command.\n\nThere was a lot of discussion a year or three back about the terminology \nof cache/Index/staging for this middle area. It probably wasn't resolved \nfully as it only discussed the name, rather than why the concept wasn't \nwell understood, and what was needed to fix _that_.\n>\n> You can't make a commit visible unless you check it out (and then can\n> use various tools available to work on filesystem), or you use git\n> diff/show to examine it. The index is treated pretty much the same\n> way, except that it does not have a proper SHA-1 yet because it's\n> still a work in progress.\nI'd say most users feel happy about the fixedness of their last commit, \nand probably feel happy with the ability to view it via various tools \n(especially if pushed to their GitHub/Lab/Bucket repo). The apparently \ntransient nature of the index is part of its Achilles heel. We talk too \neasily about 'blowing it away' [1].  Such phrases reinforce the user \nbelief that they should treat it as a bit of a swamp area.\n\nWe don't have an index_log of the changes to the staging tree, as files \nare added or removed. That view implies that the index is simply the \ncurrent work-in-progress (wip) tree, and doesn't contain anything else..\n>\n> Short of creating a fuse filesystem to show you the index content (as\n> read-only files) I don't see any better way that you can actually see\n> the index without checking it out.\nSurely? the 'git status' command [1] is, in a way, trying to be that \nview, but we just haven't told the users\n>\n> PS. Yes I ignored the role of the index during a merge conflict. Not\n> relying on the index for conflict handling might be possible, but I'm\n> not going to touch that topic, way out of my area.\nThe role during merges would be part of that missing conceptual \nstructure. Our documentation is doing a little too much of the 'ignore \nwhat's behind the curtain' [2]. I've certainly fallen for that often. \nThe need for various web explanations e.g. [3,4] also suggest we could \nbe more assertive in our top level user documentation about 'index is \none of the most important data structures in git'.\n\nIn summary, I think the problem that Victor alludes to is at a higher \nlevel with respect to how we document what the staging area / index is \nand does.\n\nPhilip\n\n[1] e.g. https://shafiul.github.io//gitbook/1_the_git_index.html\n[2] Wizard of Oz, Powerful concept, vs loose tools.\n[3] \nhttps://stackoverflow.com/questions/4084921/what-does-the-git-index-contain-exactly,\n[4] https://mincong-h.github.io/2018/04/28/git-index/\n"}]}