# [PATCH] reset: update help text 9 messages from 2011-03-29 to 2011-04-02. Participants: Nguyễn Thái Ngọc Duy, Nguyen Thai Ngoc Duy, Jonathan Nieder, Junio C Hamano. Thread: https://gitlist.dev/t/26909 ## Nguyễn Thái Ngọc Duy, 2011-03-29 13:20 Subject: [PATCH] reset: update help text Message-ID: <1301404805-12095-1-git-send-email-pclouds@gmail.com> URL: https://gitlist.dev/e/1301404805-12095-1-git-send-email-pclouds%40gmail.com ``` State --mixed is the default so users don't have to open up man page. Also make it clear how --hard and --merge are different. Move -q to bottom because it's not that important to pay attention to as the first item. Signed-off-by: Nguyễn Thái Ngọc Duy --- builtin/reset.c | 6 +++--- 1 files changed, 3 insertions(+), 3 deletions(-) diff --git a/builtin/reset.c b/builtin/reset.c index eb5f98c..7419c9e 100644 --- a/builtin/reset.c +++ b/builtin/reset.c @@ -243,17 +243,17 @@ int cmd_reset(int argc, const char **argv, const char *prefix) struct commit *commit; char *reflog_action, msg[1024]; const struct option options[] = { - OPT__QUIET(&quiet, "be quiet, only report errors"), OPT_SET_INT(0, "mixed", &reset_type, - "reset HEAD and index", MIXED), + "reset HEAD and index (default)", MIXED), OPT_SET_INT(0, "soft", &reset_type, "reset only HEAD", SOFT), OPT_SET_INT(0, "hard", &reset_type, "reset HEAD, index and working tree", HARD), OPT_SET_INT(0, "merge", &reset_type, - "reset HEAD, index and working tree", MERGE), + "like --hard but keep local changes in working tree", MERGE), OPT_SET_INT(0, "keep", &reset_type, "reset HEAD but keep local changes", KEEP), OPT_BOOLEAN('p', "patch", &patch_mode, "select hunks interactively"), + OPT__QUIET(&quiet, "be quiet, only report errors"), OPT_END() }; -- 1.7.4.74.g639db ``` ## Nguyen Thai Ngoc Duy, 2011-03-29 13:29 Subject: Re: [PATCH] reset: update help text Message-ID: URL: https://gitlist.dev/e/AANLkTin5CguMu360%2BhV_QJYHnyEQYeVp05HSBp05UGvr%40mail.gmail.com In-Reply-To: <1301404805-12095-1-git-send-email-pclouds@gmail.com> ``` 2011/3/29 Nguyễn Thái Ngọc Duy : > Also make it clear how --hard and --merge are different. By the way I don't like the option names --hard, --mixed and --soft. They do not remind me what they actually do. Every time I need to do non-default operation, I have to open man page. I've been thinking of --ref, --index and --worktree as a more friendly version, which can be combined and converted to --soft, --mixed and --hard internally. Invalid combinations will be rejected. That thinking went well until I found out there were --merge and --keep, and was stuck. -- Duy ``` ## Jonathan Nieder, 2011-03-29 21:04 Subject: Re: [PATCH] reset: update help text Message-ID: <20110329210457.GA14031@elie> URL: https://gitlist.dev/e/20110329210457.GA14031%40elie In-Reply-To: <1301404805-12095-1-git-send-email-pclouds@gmail.com> ``` (+cc: Christian, Michael, and Thomas) Nguyễn Thái Ngọc Duy wrote: > State --mixed is the default so users don't have to open up man page. > > Also make it clear how --hard and --merge are different. Thanks; I think the goal of this patch is a good one. > --- a/builtin/reset.c > +++ b/builtin/reset.c > @@ -243,17 +243,17 @@ int cmd_reset(int argc, const char **argv, const char *prefix) > struct commit *commit; > char *reflog_action, msg[1024]; > const struct option options[] = { > - OPT__QUIET(&quiet, "be quiet, only report errors"), > OPT_SET_INT(0, "mixed", &reset_type, > - "reset HEAD and index", MIXED), > + "reset HEAD and index (default)", MIXED), Nice. > OPT_SET_INT(0, "soft", &reset_type, "reset only HEAD", SOFT), > OPT_SET_INT(0, "hard", &reset_type, > "reset HEAD, index and working tree", HARD), > OPT_SET_INT(0, "merge", &reset_type, > - "reset HEAD, index and working tree", MERGE), > + "like --hard but keep local changes in working tree", MERGE), > OPT_SET_INT(0, "keep", &reset_type, > "reset HEAD but keep local changes", KEEP), The description does not make it obvious to me how these two (--merge and --keep) differ. I think the intent of the options are: --keep: start working on a different commit, carrying over local changes (like "git checkout") --merge: return to , cancelling a merge-like operation that creates some unmerged and some clean index entries Maybe something along these lines could be ok starting point? OPT_SET_INT(0, "keep", &reset_type, "move to , carrying over local changes in working tree", KEEP), OPT_SET_INT(0, "merge", &reset_type, "return to , cancelling failed merge or cherry-pick", MERGE), ``` ## Nguyen Thai Ngoc Duy, 2011-03-31 12:31 Subject: Re: [PATCH] reset: update help text Message-ID: URL: https://gitlist.dev/e/AANLkTiknvWE9Fe3u88Jbis4Cgxd5ubqaR6MzYOJZ-AtM%40mail.gmail.com In-Reply-To: <20110329210457.GA14031@elie> ``` 2011/3/30 Jonathan Nieder : > The description does not make it obvious to me how these two (--merge > and --keep) differ.  I think the intent of the options are: > >  --keep: >        start working on a different commit, carrying over local changes >        (like "git checkout") >  --merge: >        return to , cancelling a merge-like operation that >        creates some unmerged and some clean index entries > > Maybe something along these lines could be ok starting point? > >        OPT_SET_INT(0, "keep", &reset_type, >                "move to , carrying over local changes in working tree", >                KEEP), >        OPT_SET_INT(0, "merge", &reset_type, >                "return to , cancelling failed merge or cherry-pick", >                MERGE), > To be honest, I have no idea what the above describes. I read 9bc454d (reset: add option "--keep" to "git reset" - 2010-01-19) and figured that --keep is like --merge except that "git diff" before and after the reset is exactly the same, is it? I have never used --keep before. -- Duy ``` ## Jonathan Nieder, 2011-03-31 18:42 Subject: Re: [PATCH] reset: update help text Message-ID: <20110331184246.GA19264@elie> URL: https://gitlist.dev/e/20110331184246.GA19264%40elie In-Reply-To: ``` Nguyen Thai Ngoc Duy wrote: > To be honest, I have no idea what the above describes. I read 9bc454d > (reset: add option "--keep" to "git reset" - 2010-01-19) and figured > that --keep is like --merge except that "git diff" before and after > the reset is exactly the same, is it? I have never used --keep before. I use "git reset --keep" to - discard a bad commit: git reset --keep HEAD^ - start working against a different commit: git checkout -b topic && ... hack hack hack without committing ... && : "oops, I thought I was on master but I was somewhere else" && git reset --keep master The spirit of the thing[1] is: * if the diff "HEAD -> " touch paths in which we have local changes, error out; * otherwise, checkout the relevant paths from but leave the paths in which we have local changes alone. which indeed means "git diff --cached" and "git diff" before and after would be exactly the same. But there are some edge cases, in which the diff "HEAD -> " makes the same change we did and the reset --keep is still allowed. This is totally different from --merge. The only legitimate use of --merge is to cancel a merge you just performed, imho --- the effect otherwise is too scary ("git add ; git reset --merge elsewhere" --- bye, bye, changes made at ). Hope that helps, Jonathan [1] Detailed semantics: for each path listed by "git diff --name-only HEAD ": * if the worktree, index, and HEAD match, make the index and worktree match . * otherwise, if it is "not easy" to keep local changes, error out. We are not going to do a three-way merge. That is, - if the index matches neither HEAD nor , error out; - if the index matches HEAD but not the worktree, error out. * otherwise, it is "easy", so keep local changes. - if the index already matches , leave the index and worktree alone. - if the index and worktree match HEAD, make them match the instead. These are the same rules used by fast-forward merges and plain "git checkout". ``` ## Junio C Hamano, 2011-03-31 18:45 Subject: Re: [PATCH] reset: update help text Message-ID: <7v4o6jku28.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7v4o6jku28.fsf%40alter.siamese.dyndns.org In-Reply-To: <20110329210457.GA14031@elie> ``` Jonathan Nieder writes: > The description does not make it obvious to me how these two (--merge > and --keep) differ. I think the intent of the options are: > > --keep: > start working on a different commit, carrying over local changes > (like "git checkout") > --merge: > return to , cancelling a merge-like operation that > creates some unmerged and some clean index entries > > Maybe something along these lines could be ok starting point? > > OPT_SET_INT(0, "keep", &reset_type, > "move to , carrying over local changes in working tree", > KEEP), > OPT_SET_INT(0, "merge", &reset_type, > "return to , cancelling failed merge or cherry-pick", > MERGE), I cannot think of anything better, but I can still show my concern that "move to" and "return to" might not convey exactly what we are trying to express. But I agree that your phrasing definitely is a good starting point. ``` ## Junio C Hamano, 2011-03-31 21:44 Subject: Re: [PATCH] reset: update help text Message-ID: <7v39m3j780.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7v39m3j780.fsf%40alter.siamese.dyndns.org In-Reply-To: <20110331184246.GA19264@elie> ``` Jonathan Nieder writes: > [1] Detailed semantics: for each path listed by "git diff --name-only > HEAD ": > > * if the worktree, index, and HEAD match, make the index and worktree > match . > > * otherwise, if it is "not easy" to keep local changes, error out. > We are not going to do a three-way merge. That is, > > - if the index matches neither HEAD nor , error out; > - if the index matches HEAD but not the worktree, error out. > > * otherwise, it is "easy", so keep local changes. > > - if the index already matches , leave the index and > worktree alone. > - if the index and worktree match HEAD, make them match the > instead. The latter item in the last "otherwise" is the same as the first "if all match, move to the one from the named commit", isn't it? ``` ## Jonathan Nieder, 2011-03-31 21:57 Subject: Re: [PATCH] reset: update help text Message-ID: <20110331215741.GA20474@elie> URL: https://gitlist.dev/e/20110331215741.GA20474%40elie In-Reply-To: <7v39m3j780.fsf@alter.siamese.dyndns.org> ``` Junio C Hamano wrote: > Jonathan Nieder writes: >> [1] Detailed semantics: for each path listed by "git diff --name-only >> HEAD ": >> >> * if the worktree, index, and HEAD match, make the index and worktree >> match . >> >> * otherwise, if it is "not easy" to keep local changes, error out. >> We are not going to do a three-way merge. That is, >> >> - if the index matches neither HEAD nor , error out; >> - if the index matches HEAD but not the worktree, error out. >> >> * otherwise, it is "easy", so keep local changes. >> >> - if the index already matches , leave the index and >> worktree alone. >> - if the index and worktree match HEAD, make them match the >> instead. > > The latter item in the last "otherwise" is the same as the first "if all > match, move to the one from the named commit", isn't it? Yes, sorry for the nonsense. ``` ## Nguyen Thai Ngoc Duy, 2011-04-02 08:43 Subject: Re: [PATCH] reset: update help text Message-ID: URL: https://gitlist.dev/e/BANLkTi%3Dm-MYaQZ8_u8-CAXPaVpJi9QDkTg%40mail.gmail.com In-Reply-To: <20110331184246.GA19264@elie> ``` On Fri, Apr 1, 2011 at 1:42 AM, Jonathan Nieder wrote: > Nguyen Thai Ngoc Duy wrote: > >> To be honest, I have no idea what the above describes. I read 9bc454d >> (reset: add option "--keep" to "git reset" - 2010-01-19) and figured >> that --keep is like --merge except that "git diff" before and after >> the reset is exactly the same, is it? I have never used --keep before. > > I use "git reset --keep" to > >  - discard a bad commit: git reset --keep HEAD^ >  - start working against a different commit: > >        git checkout -b topic && >        ... hack hack hack without committing ... && >        : "oops, I thought I was on master but I was somewhere else" && >        git reset --keep master > > .. Thanks. Your changes make sense to me now. -- Duy ```