{"thread":{"id":"50822","subject":"[PATCH] read-tree.txt: clarify --reset and worktree changes","startedAt":"2019-03-26T12:10:12Z","lastAt":"2019-04-01T12:05:33Z","messageCount":4,"participants":["Nguyễn Thái Ngọc Duy","Junio C Hamano","Duy Nguyen"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"372513","messageId":"20190326120939.31657-1-pclouds@gmail.com","threadId":"50822","inReplyTo":null,"subject":"[PATCH] read-tree.txt: clarify --reset and worktree changes","fromName":"Nguyễn Thái Ngọc Duy","fromEmail":"pclouds@gmail.com","sentAt":"2019-03-26T12:09:39Z","receivedAt":"2019-03-26T12:10:12Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"The description of --reset stays true to the first implementation in\n438195cced (git-read-tree: add \"--reset\" flag, 2005-06-09). That is,\n--reset discards unmerged entries. Or at least true to the commit\nmessage because I can't be sure about read-tree's behavior regarding\nlocal changes.\n\nBut in fcc387db9b (read-tree -m -u: do not overwrite or remove untracked\nworking tree files., 2006-05-17), it is clear that \"-m -u\" tries to keep\nlocal changes, while --reset is singled out and will keep overwriting\nworktree files. It's not stated in the commit message, but it's obvious\nfrom the patch.\n\nI went this far back not because I had a lot of free time, but because I\ndid not trust my reading of unpack-trees.c code. So far I think the\nrelated changes in history agree with my understanding of the current\ncode, that \"--reset\" loses local changes.\n\nThis behavior is not mentioned in git-read-tree.txt, even though\nold-timers probably can just guess it based on the \"reset\" name. Update\ngit-read-tree.txt about this.\n\nSide note. There's another change regarding --reset that is not\nobviously about local changes, b018ff6085 (unpack-trees: fix \"read-tree\n-u --reset A B\" with conflicted index, 2012-12-29). But I'm pretty sure\nthis is about the first function of --reset, to discard unmerged entries\ncorrectly.\n\nPS. The patch changes one more line than necessary because the first\nline uses spaces instead of tab.\n\nSigned-off-by: Nguyễn Thái Ngọc Duy \n---\n Documentation/git-read-tree.txt | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex 5c70bc2878..12a25bc954 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -38,8 +38,9 @@ OPTIONS\n \tstarted.\n \n --reset::\n- Same as -m, except that unmerged entries are discarded\n- instead of failing.\n+\tSame as -m, except that unmerged entries are discarded\n+\tinstead of failing. If `-u` is used, updates leading to loss\n+\tof local changes will not abort the operation.\n \n -u::\n \tAfter a successful merge, update the files in the work\n-- \n2.21.0.479.g47ac719cd3\n\n"},{"id":"372875","messageId":"xmqqmulauhmv.fsf@gitster-ct.c.googlers.com","threadId":"50822","inReplyTo":"20190326120939.31657-1-pclouds@gmail.com","subject":"Re: [PATCH] read-tree.txt: clarify --reset and worktree changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-04-01T10:47:20Z","receivedAt":"2019-04-01T10:47:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nguyễn Thái Ngọc Duy writes:\n\n> diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\n> index 5c70bc2878..12a25bc954 100644\n> --- a/Documentation/git-read-tree.txt\n> +++ b/Documentation/git-read-tree.txt\n> @@ -38,8 +38,9 @@ OPTIONS\n> \tstarted.\n> \n> --reset::\n> - Same as -m, except that unmerged entries are discarded\n> - instead of failing.\n> +\tSame as -m, except that unmerged entries are discarded\n> +\tinstead of failing. If `-u` is used, updates leading to loss\n> +\tof local changes will not abort the operation.\n\n\"git add $file\" makes a local change to the index at path $file\",\nand reverting that local change is what \"read-tree --reset\"\nprimarily does.\n\nThe difference cased by presence or lack of \"-u\" is only about the\nworking tree files, so s/local/working tree/ perhaps?\n\nI'd also phrase s/If `-u` is used/When used with `-u`/ if I were\nwriting this.\n\nThanks.\n\n> \n> -u::\n> \tAfter a successful merge, update the files in the work\n"},{"id":"372882","messageId":"CACsJy8B1Bp6=H_pKTfaZtucxod-SK3X+gb6zMJfmxBy8ep0PPA@mail.gmail.com","threadId":"50822","inReplyTo":"xmqqmulauhmv.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] read-tree.txt: clarify --reset and worktree changes","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2019-04-01T12:02:12Z","receivedAt":"2019-04-01T12:02:41Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Mon, Apr 1, 2019 at 5:47 PM Junio C Hamano wrote:\n>\n> Nguyễn Thái Ngọc Duy writes:\n>\n> > diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\n> > index 5c70bc2878..12a25bc954 100644\n> > --- a/Documentation/git-read-tree.txt\n> > +++ b/Documentation/git-read-tree.txt\n> > @@ -38,8 +38,9 @@ OPTIONS\n> > started.\n> >\n> > --reset::\n> > - Same as -m, except that unmerged entries are discarded\n> > - instead of failing.\n> > + Same as -m, except that unmerged entries are discarded\n> > + instead of failing. If `-u` is used, updates leading to loss\n> > + of local changes will not abort the operation.\n>\n> \"git add $file\" makes a local change to the index at path $file\",\n> and reverting that local change is what \"read-tree --reset\"\n> primarily does.\n\nThat sounds more like \"reset $file\" than \"read-tree --reset\" actually,\nwhich works on a full tree instead of a path.\n\n> The difference cased by presence or lack of \"-u\" is only about the\n> working tree files, so s/local/working tree/ perhaps?\n>\n> I'd also phrase s/If `-u` is used/When used with `-u`/ if I were\n> writing this.\n\nUpdated. v2 coming.\n\n>\n> Thanks.\n>\n> >\n> > -u::\n> > After a successful merge, update the files in the work\n\n\n\n-- \nDuy\n"},{"id":"372883","messageId":"20190401120505.12164-1-pclouds@gmail.com","threadId":"50822","inReplyTo":"20190326120939.31657-1-pclouds@gmail.com","subject":"[PATCH v2] read-tree.txt: clarify --reset and worktree changes","fromName":"Nguyễn Thái Ngọc Duy","fromEmail":"pclouds@gmail.com","sentAt":"2019-04-01T12:05:05Z","receivedAt":"2019-04-01T12:05:33Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"The description of --reset stays true to the first implementation in\n438195cced (git-read-tree: add \"--reset\" flag, 2005-06-09). That is,\n--reset discards unmerged entries. Or at least true to the commit\nmessage because I can't be sure about read-tree's behavior regarding\nlocal changes.\n\nBut in fcc387db9b (read-tree -m -u: do not overwrite or remove untracked\nworking tree files., 2006-05-17), it is clear that \"-m -u\" tries to keep\nlocal changes, while --reset is singled out and will keep overwriting\nworktree files. It's not stated in the commit message, but it's obvious\nfrom the patch.\n\nI went this far back not because I had a lot of free time, but because I\ndid not trust my reading of unpack-trees.c code. So far I think the\nrelated changes in history agree with my understanding of the current\ncode, that \"--reset\" loses local changes.\n\nThis behavior is not mentioned in git-read-tree.txt, even though\nold-timers probably can just guess it based on the \"reset\" name. Update\ngit-read-tree.txt about this.\n\nSide note. There's another change regarding --reset that is not\nobviously about local changes, b018ff6085 (unpack-trees: fix \"read-tree\n-u --reset A B\" with conflicted index, 2012-12-29). But I'm pretty sure\nthis is about the first function of --reset, to discard unmerged entries\ncorrectly.\n\nPS. The patch changes one more line than necessary because the first\nline uses spaces instead of tab.\n\nSigned-off-by: Nguyễn Thái Ngọc Duy \n---\n v2 updates a bit to emphasize on worktree changes.\n\n Documentation/git-read-tree.txt | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex 5c70bc2878..7061d6634e 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -38,8 +38,9 @@ OPTIONS\n \tstarted.\n \n --reset::\n- Same as -m, except that unmerged entries are discarded\n- instead of failing.\n+\tSame as -m, except that unmerged entries are discarded instead\n+\tof failing. When used with `-u`, updates leading to loss of\n+\tworking tree changes will not abort the operation.\n \n -u::\n \tAfter a successful merge, update the files in the work\n-- \n2.21.0.479.g47ac719cd3\n\n"}]}