# [PATCH] read-tree.txt: clarify --reset and worktree changes 4 messages from 2019-03-26 to 2019-04-01. Participants: Nguyễn Thái Ngọc Duy, Junio C Hamano, Duy Nguyen. Thread: https://gitlist.dev/t/50822 ## Nguyễn Thái Ngọc Duy, 2019-03-26 12:09 Subject: [PATCH] read-tree.txt: clarify --reset and worktree changes Message-ID: <20190326120939.31657-1-pclouds@gmail.com> URL: https://gitlist.dev/e/20190326120939.31657-1-pclouds%40gmail.com ``` The description of --reset stays true to the first implementation in 438195cced (git-read-tree: add "--reset" flag, 2005-06-09). That is, --reset discards unmerged entries. Or at least true to the commit message because I can't be sure about read-tree's behavior regarding local changes. But in fcc387db9b (read-tree -m -u: do not overwrite or remove untracked working tree files., 2006-05-17), it is clear that "-m -u" tries to keep local changes, while --reset is singled out and will keep overwriting worktree files. It's not stated in the commit message, but it's obvious from the patch. I went this far back not because I had a lot of free time, but because I did not trust my reading of unpack-trees.c code. So far I think the related changes in history agree with my understanding of the current code, that "--reset" loses local changes. This behavior is not mentioned in git-read-tree.txt, even though old-timers probably can just guess it based on the "reset" name. Update git-read-tree.txt about this. Side note. There's another change regarding --reset that is not obviously about local changes, b018ff6085 (unpack-trees: fix "read-tree -u --reset A B" with conflicted index, 2012-12-29). But I'm pretty sure this is about the first function of --reset, to discard unmerged entries correctly. PS. The patch changes one more line than necessary because the first line uses spaces instead of tab. Signed-off-by: Nguyễn Thái Ngọc Duy --- Documentation/git-read-tree.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 5c70bc2878..12a25bc954 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -38,8 +38,9 @@ OPTIONS started. --reset:: - Same as -m, except that unmerged entries are discarded - instead of failing. + Same as -m, except that unmerged entries are discarded + instead of failing. If `-u` is used, updates leading to loss + of local changes will not abort the operation. -u:: After a successful merge, update the files in the work -- 2.21.0.479.g47ac719cd3 ``` ## Junio C Hamano, 2019-04-01 10:47 Subject: Re: [PATCH] read-tree.txt: clarify --reset and worktree changes Message-ID: URL: https://gitlist.dev/e/xmqqmulauhmv.fsf%40gitster-ct.c.googlers.com In-Reply-To: <20190326120939.31657-1-pclouds@gmail.com> ``` Nguyễn Thái Ngọc Duy writes: > diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt > index 5c70bc2878..12a25bc954 100644 > --- a/Documentation/git-read-tree.txt > +++ b/Documentation/git-read-tree.txt > @@ -38,8 +38,9 @@ OPTIONS > started. > > --reset:: > - Same as -m, except that unmerged entries are discarded > - instead of failing. > + Same as -m, except that unmerged entries are discarded > + instead of failing. If `-u` is used, updates leading to loss > + of local changes will not abort the operation. "git add $file" makes a local change to the index at path $file", and reverting that local change is what "read-tree --reset" primarily does. The difference cased by presence or lack of "-u" is only about the working tree files, so s/local/working tree/ perhaps? I'd also phrase s/If `-u` is used/When used with `-u`/ if I were writing this. Thanks. > > -u:: > After a successful merge, update the files in the work ``` ## Duy Nguyen, 2019-04-01 12:02 Subject: Re: [PATCH] read-tree.txt: clarify --reset and worktree changes Message-ID: URL: https://gitlist.dev/e/CACsJy8B1Bp6%3DH_pKTfaZtucxod-SK3X%2Bgb6zMJfmxBy8ep0PPA%40mail.gmail.com In-Reply-To: ``` On Mon, Apr 1, 2019 at 5:47 PM Junio C Hamano wrote: > > Nguyễn Thái Ngọc Duy writes: > > > diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt > > index 5c70bc2878..12a25bc954 100644 > > --- a/Documentation/git-read-tree.txt > > +++ b/Documentation/git-read-tree.txt > > @@ -38,8 +38,9 @@ OPTIONS > > started. > > > > --reset:: > > - Same as -m, except that unmerged entries are discarded > > - instead of failing. > > + Same as -m, except that unmerged entries are discarded > > + instead of failing. If `-u` is used, updates leading to loss > > + of local changes will not abort the operation. > > "git add $file" makes a local change to the index at path $file", > and reverting that local change is what "read-tree --reset" > primarily does. That sounds more like "reset $file" than "read-tree --reset" actually, which works on a full tree instead of a path. > The difference cased by presence or lack of "-u" is only about the > working tree files, so s/local/working tree/ perhaps? > > I'd also phrase s/If `-u` is used/When used with `-u`/ if I were > writing this. Updated. v2 coming. > > Thanks. > > > > > -u:: > > After a successful merge, update the files in the work -- Duy ``` ## Nguyễn Thái Ngọc Duy, 2019-04-01 12:05 Subject: [PATCH v2] read-tree.txt: clarify --reset and worktree changes Message-ID: <20190401120505.12164-1-pclouds@gmail.com> URL: https://gitlist.dev/e/20190401120505.12164-1-pclouds%40gmail.com In-Reply-To: <20190326120939.31657-1-pclouds@gmail.com> ``` The description of --reset stays true to the first implementation in 438195cced (git-read-tree: add "--reset" flag, 2005-06-09). That is, --reset discards unmerged entries. Or at least true to the commit message because I can't be sure about read-tree's behavior regarding local changes. But in fcc387db9b (read-tree -m -u: do not overwrite or remove untracked working tree files., 2006-05-17), it is clear that "-m -u" tries to keep local changes, while --reset is singled out and will keep overwriting worktree files. It's not stated in the commit message, but it's obvious from the patch. I went this far back not because I had a lot of free time, but because I did not trust my reading of unpack-trees.c code. So far I think the related changes in history agree with my understanding of the current code, that "--reset" loses local changes. This behavior is not mentioned in git-read-tree.txt, even though old-timers probably can just guess it based on the "reset" name. Update git-read-tree.txt about this. Side note. There's another change regarding --reset that is not obviously about local changes, b018ff6085 (unpack-trees: fix "read-tree -u --reset A B" with conflicted index, 2012-12-29). But I'm pretty sure this is about the first function of --reset, to discard unmerged entries correctly. PS. The patch changes one more line than necessary because the first line uses spaces instead of tab. Signed-off-by: Nguyễn Thái Ngọc Duy --- v2 updates a bit to emphasize on worktree changes. Documentation/git-read-tree.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 5c70bc2878..7061d6634e 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -38,8 +38,9 @@ OPTIONS started. --reset:: - Same as -m, except that unmerged entries are discarded - instead of failing. + Same as -m, except that unmerged entries are discarded instead + of failing. When used with `-u`, updates leading to loss of + working tree changes will not abort the operation. -u:: After a successful merge, update the files in the work -- 2.21.0.479.g47ac719cd3 ```