* [PATCH] read-tree.txt: clarify --reset and worktree changes
@ 2019-03-26 12:09 Nguyễn Thái Ngọc Duy
2019-04-01 10:47 ` Junio C Hamano
2019-04-01 12:05 ` [PATCH v2] " Nguyễn Thái Ngọc Duy
0 siblings, 2 replies; 4+ messages in thread
From: Nguyễn Thái Ngọc Duy @ 2019-03-26 12:09 UTC (permalink / raw)
To: git; +Cc: Junio C Hamano, 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.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
---
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
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH] read-tree.txt: clarify --reset and worktree changes
2019-03-26 12:09 [PATCH] read-tree.txt: clarify --reset and worktree changes Nguyễn Thái Ngọc Duy
@ 2019-04-01 10:47 ` Junio C Hamano
2019-04-01 12:02 ` Duy Nguyen
2019-04-01 12:05 ` [PATCH v2] " Nguyễn Thái Ngọc Duy
1 sibling, 1 reply; 4+ messages in thread
From: Junio C Hamano @ 2019-04-01 10:47 UTC (permalink / raw)
To: Nguyễn Thái Ngọc Duy; +Cc: git
Nguyễn Thái Ngọc Duy <pclouds@gmail.com> 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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] read-tree.txt: clarify --reset and worktree changes
2019-04-01 10:47 ` Junio C Hamano
@ 2019-04-01 12:02 ` Duy Nguyen
0 siblings, 0 replies; 4+ messages in thread
From: Duy Nguyen @ 2019-04-01 12:02 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Git Mailing List
On Mon, Apr 1, 2019 at 5:47 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Nguyễn Thái Ngọc Duy <pclouds@gmail.com> 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
^ permalink raw reply [flat|nested] 4+ messages in thread
* [PATCH v2] read-tree.txt: clarify --reset and worktree changes
2019-03-26 12:09 [PATCH] read-tree.txt: clarify --reset and worktree changes Nguyễn Thái Ngọc Duy
2019-04-01 10:47 ` Junio C Hamano
@ 2019-04-01 12:05 ` Nguyễn Thái Ngọc Duy
1 sibling, 0 replies; 4+ messages in thread
From: Nguyễn Thái Ngọc Duy @ 2019-04-01 12:05 UTC (permalink / raw)
To: pclouds; +Cc: git, gitster
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 <pclouds@gmail.com>
---
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
^ permalink raw reply related [flat|nested] 4+ messages in thread
end of thread, other threads:[~2019-04-01 12:05 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-03-26 12:09 [PATCH] read-tree.txt: clarify --reset and worktree changes Nguyễn Thái Ngọc Duy
2019-04-01 10:47 ` Junio C Hamano
2019-04-01 12:02 ` Duy Nguyen
2019-04-01 12:05 ` [PATCH v2] " Nguyễn Thái Ngọc Duy
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).