[PATCH] reset: update help text

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 <redacted>
---
 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

2011/3/29 Nguyễn Thái Ngọc Duy [off-list ref]:

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

(+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.

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 <commit>, 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 <commit>, carrying over local changes in working tree",
		KEEP),
	OPT_SET_INT(0, "merge", &reset_type,
		"return to <commit>, cancelling failed merge or cherry-pick",
		MERGE),

2011/3/30 Jonathan Nieder [off-list ref]:

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 <commit>, 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 <commit>, carrying over local changes in working tree",
               KEEP),
       OPT_SET_INT(0, "merge", &reset_type,
               "return to <commit>, 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

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 -> <commit>" touch paths in which we have local
   changes, error out;
 * otherwise, checkout the relevant paths from <commit> 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 -> <commit>" 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 <path>; git reset --merge elsewhere"

--- bye, bye, changes made at <path>).

Hope that helps,
Jonathan

[1] Detailed semantics: for each path listed by "git diff --name-only
HEAD <commit>":

 * if the worktree, index, and HEAD match, make the index and worktree
   match <commit>.

 * 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 <commit>, 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 <commit>, leave the index and
     worktree alone.
   - if the index and worktree match HEAD, make them match the
     <commit> instead.

These are the same rules used by fast-forward merges and plain
"git checkout".

On Fri, Apr 1, 2011 at 1:42 AM, Jonathan Nieder [off-list ref] wrote:

Nguyen Thai Ngoc Duy wrote:

quoted

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