reset command: provide convenient and meaningful options help

This commit changes the jgit "reset" command line options help from
this:

jgit reset name [VAL ...] [-- path ... ...] [--hard] [--help (-h)]
[--mixed] [--soft]
 name        : Reset current HEAD to the specified state
 [...]

to this:

jgit reset [commit-ish] [path ... ...] [-- path ... ...] [--hard]
[--help (-h)] [--mixed] [--soft]
 commit-ish  : Reset to given reference name
 [...]

Bug: 484951
Change-Id: I614e71101b4f9f46ef8f02379d1a9d135f3292d2
Signed-off-by: Andrey Loskutov <loskutov@gmx.de>

org.eclipse.jgit.pgm.test/tst/org/eclipse/jgit/pgm/ResetTest.java

@@ -48,6 +48,7 @@
 import org.eclipse.jgit.lib.CLIRepositoryTestCase;
 import org.eclipse.jgit.revwalk.RevCommit;
 import org.junit.Before;
+import org.junit.Ignore;
 import org.junit.Test;
 
 public class ResetTest extends CLIRepositoryTestCase {
@@ -61,6 +62,13 @@ public void setUp() throws Exception {
 		git = new Git(db);
 	}
 
+	@Test
+	public void testZombieArgument_Bug484951() throws Exception {
+		String[] result = execute("git reset -h");
+		assertFalse("Unexpected argument: " + result[0],
+				result[0].contains("[VAL ...]"));
+	}
+
 	@Test
 	public void testResetSelf() throws Exception {
 		RevCommit commit = git.commit().setMessage("initial commit").call();
@@ -91,15 +99,28 @@ public void testResetEmptyPath() throws Exception {
 
 	@Test
 	public void testResetPathDoubleDash() throws Exception {
-		resetPath(true);
+		resetPath(true, true);
 	}
 
 	@Test
 	public void testResetPathNoDoubleDash() throws Exception {
-		resetPath(false);
+		resetPath(false, true);
 	}
 
-	private void resetPath(boolean useDoubleDash) throws Exception {
+	@Test
+	public void testResetPathDoubleDashNoRef() throws Exception {
+		resetPath(true, false);
+	}
+
+	@Ignore("Currently we cannote recognize if a name is a commit-ish or a path, "
+			+ "so 'git reset a' will not work if 'a' is not a branch name but a file path")
+	@Test
+	public void testResetPathNoDoubleDashNoRef() throws Exception {
+		resetPath(false, false);
+	}
+
+	private void resetPath(boolean useDoubleDash, boolean supplyCommit)
+			throws Exception {
 		// create files a and b
 		writeTrashFile("a", "Hello world a");
 		writeTrashFile("b", "Hello world b");
@@ -115,8 +136,9 @@ private void resetPath(boolean useDoubleDash) throws Exception {
 		git.add().addFilepattern(".").call();
 
 		// reset only file a
-		String cmd = String.format("git reset %s%s a", commit.getId().name(),
-				(useDoubleDash) ? " --" : "");
+		String cmd = String.format("git reset %s%s a",
+				supplyCommit ? commit.getId().name() : "",
+				useDoubleDash ? " --" : "");
 		assertStringArrayEquals("", execute(cmd));
 		assertEquals(commit.getId(),
 				git.getRepository().exactRef("HEAD").getObjectId());

org.eclipse.jgit.pgm/resources/org/eclipse/jgit/pgm/internal/CLIText.properties

@@ -337,6 +337,7 @@ usage_recordChangesToRepository=Record changes to the repository
 usage_recurseIntoSubtrees=recurse into subtrees
 usage_renameLimit=limit size of rename matrix
 usage_reset=Reset current HEAD to the specified state
+usage_resetReference=Reset to given reference name
 usage_resetHard=Resets the index and working tree
 usage_resetSoft=Resets without touching the index file nor the working tree
 usage_resetMixed=Resets the index but not the working tree

org.eclipse.jgit.pgm/src/org/eclipse/jgit/pgm/Reset.java

@@ -51,7 +51,7 @@
 import org.eclipse.jgit.api.ResetCommand.ResetType;
 import org.kohsuke.args4j.Argument;
 import org.kohsuke.args4j.Option;
-import org.kohsuke.args4j.spi.StopOptionHandler;
+import org.kohsuke.args4j.spi.RestOfArgumentsHandler;
 
 @Command(common = true, usage = "usage_reset")
 class Reset extends TextBuiltin {
@@ -65,12 +65,12 @@ class Reset extends TextBuiltin {
 	@Option(name = "--hard", usage = "usage_resetHard")
 	private boolean hard = false;
 
-	@Argument(required = true, index = 0, metaVar = "metaVar_name", usage = "usage_reset")
+	@Argument(required = false, index = 0, metaVar = "metaVar_commitish", usage = "usage_resetReference")
 	private String commit;
 
-	@Argument(index = 1)
-	@Option(name = "--", metaVar = "metaVar_paths", multiValued = true, handler = StopOptionHandler.class)
-	private List<String> paths = new ArrayList<String>();
+	@Argument(required = false, index = 1, metaVar = "metaVar_paths")
+	@Option(name = "--", metaVar = "metaVar_paths", multiValued = true, handler = RestOfArgumentsHandler.class)
+	private List<String> paths = new ArrayList<>();
 
 	@Override
 	protected void run() throws Exception {