Skip to contentSkip to conversation

read-tree.txt: clarify --reset and worktree changes

PATCH Superseded Nguyễn Thái Ngọc Duy 2 participants 4 messages Mar 26, 2019 – Apr 1, 2019 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 read-tree.txt: clarify --reset and worktree changes

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.

---
 Documentation/git-read-tree.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/git-read-tree.txt +3 -2
index 5c70bc2878..12a25bc954 100644
@@ -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
Signature · 1 line
2.21.0.479.g47ac719cd3
#1 lore raw

Documentation/git-read-tree.txt OPTIONS · line 43

Quoted 13 lines · Nguyễn Thái Ngọc Duy
Documentation/git-read-tree.txt +3 -2
index 5c70bc2878..12a25bc954 100644
@@ -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.

Quoted 3 lines
Documentation/git-read-tree.txt +0 -0
 -u::
 	After a successful merge, update the files in the work
author
#2 lore raw
Quoted 10 lines · Junio C Hamano
Quoted 7 lines · Nguyễn Thái Ngọc Duy
Documentation/git-read-tree.txt +0 -0
index 5c70bc2878..12a25bc954 100644
@@ -38,8 +38,9 @@ OPTIONS
      started.
 
Quoted 10 lines

Documentation/git-read-tree.txt OPTIONS · line 43

Quoted 6 lines
Documentation/git-read-tree.txt +3 -2
 --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.

Quoted 5 lines

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.

Quoted 6 lines

Thanks.

Quoted 3 lines
Documentation/git-read-tree.txt +0 -0
 -u::
      After a successful merge, update the files in the work
Signature · 1 line
Duy
#3 lore raw

PATCH v2 1/1 read-tree.txt: clarify --reset and worktree changes

In reply to Nguyễn Thái Ngọc Duy

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.

---
v2 updates a bit to emphasize on worktree changes.

 Documentation/git-read-tree.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/git-read-tree.txt +3 -2
index 5c70bc2878..7061d6634e 100644
@@ -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
Signature · 1 line
2.21.0.479.g47ac719cd3