[BUG, RFC] git stash drop --help

[BUG, RFC] git stash drop --help

[Vincent Legoll]

Hello,

I stumbled upon something that annoyed me a bit, as I was working with

git stash to commit some big pile of modifications in small commits...

I wanted to get help wrt "git stash drop" and did it the following way :

[steps to reproduce]

mkdir tmp
cd tmp
git init
touch test.txt
git add test.txt
git commit -a -m "initial version"
echo zorglub > test.txt
git stash
git stash drop --help
refs/stash@{0} supprimé (ff100a8c2f1b7b00b9100b32d2a5dc19a8b0092a)

And that was definitely not what I intended. Fortunately for me I had a
backup of that stashed diff somewhere else, but I was still surprised,

because I was used to:

git $(SOMETHING) --help

to do what I want.

This is probably because "drop" is a subcommand of "stash",
as evidenced by:

git stash --help drop

working as intended (even if as as side effect of --help ignoring
further parameters)

-- 
Vincent Legoll

[PATCH] stash: complain about unknown flags

[Jeff King]

The option parser for git-stash stuffs unknown flags into
the $FLAGS variable, where they can be accessed by the
individual commands. However, most commands do not even look
at these extra flags, leading to unexpected results like
this:

  $ git stash drop --help
  Dropped refs/stash@{0} (e6cf6d80faf92bb7828f7b60c47fc61c03bd30a1)

We should notice the extra flags and bail. Rather than
annotate each command to reject a non-empty $FLAGS variable,
we can notice that "stash show" is the only command that
actually _wants_ arbitrary flags. So we switch the default
mode to reject unknown flags, and let stash_show() opt into
the feature.

Reported-by: Vincent Legoll <vincent.legoll@gmail.com>
Signed-off-by: Jeff King <peff@peff.net>
---
This takes away the immediate pain. We may also want to
teach "--help" to the option. I guess we cannot do better
than just having it run "git help stash" in all cases (i.e.,
we have no way to get the help for a specific subcommand).

 git-stash.sh     | 6 +++++-
 t/t3903-stash.sh | 4 ++++
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/git-stash.sh b/git-stash.sh
index 7911f30..c6f492c 100755
--- a/git-stash.sh
+++ b/git-stash.sh
@@ -301,6 +301,7 @@ list_stash () {
 }
 
 show_stash () {
+	ALLOW_UNKNOWN_FLAGS=t
 	assert_stash_like "$@"
 
 	git diff ${FLAGS:---stat} $b_commit $w_commit
@@ -332,13 +333,14 @@ show_stash () {
 #
 #   GIT_QUIET is set to t if -q is specified
 #   INDEX_OPTION is set to --index if --index is specified.
-#   FLAGS is set to the remaining flags
+#   FLAGS is set to the remaining flags (if allowed)
 #
 # dies if:
 #   * too many revisions specified
 #   * no revision is specified and there is no stash stack
 #   * a revision is specified which cannot be resolve to a SHA1
 #   * a non-existent stash reference is specified
+#   * unknown flags were set and ALLOW_UNKNOWN_FLAGS is not "t"
 #
 
 parse_flags_and_rev()
@@ -372,6 +374,8 @@ parse_flags_and_rev()
 				INDEX_OPTION=--index
 			;;
 			-*)
+				test "$ALLOW_UNKNOWN_FLAGS" = t ||
+					die "$(eval_gettext "unknown option: \$opt")"
 				FLAGS="${FLAGS}${FLAGS:+ }$opt"
 			;;
 		esac
diff --git a/t/t3903-stash.sh b/t/t3903-stash.sh
index 0746eee..7396ca9 100755
--- a/t/t3903-stash.sh
+++ b/t/t3903-stash.sh
@@ -100,6 +100,10 @@ test_expect_success 'unstashing in a subdirectory' '
 	)
 '
 
+test_expect_success 'stash drop complains of extra options' '
+	test_must_fail git stash drop --foo
+'
+
 test_expect_success 'drop top stash' '
 	git reset --hard &&
 	git stash list > stashlist1 &&
-- 
2.4.1.396.g7ba6d7b

[PATCH 2/1] stash: recognize "--help" for subcommands

[Jeff King]

On Wed, May 20, 2015 at 02:01:32PM -0400, Jeff King wrote:

> This takes away the immediate pain. We may also want to
> teach "--help" to the option. I guess we cannot do better
> than just having it run "git help stash" in all cases (i.e.,
> we have no way to get the help for a specific subcommand).

That actually turns out to be pretty painless...

-- >* --
Subject: stash: recognize "--help" for subcommands

If you run "git stash --help", you get the help for stash
(this magic is done by the git wrapper itself). But if you
run "git stash drop --help", you get an error. We
cannot show help specific to "stash drop", of course, but we
can at least give the user the normal stash manpage.

Signed-off-by: Jeff King <peff@peff.net>
---
 git-stash.sh | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/git-stash.sh b/git-stash.sh
index c6f492c..1f5ea87 100755
--- a/git-stash.sh
+++ b/git-stash.sh
@@ -219,6 +219,9 @@ save_stash () {
 		-a|--all)
 			untracked=all
 			;;
+		--help)
+			show_help
+			;;
 		--)
 			shift
 			break
@@ -307,6 +310,11 @@ show_stash () {
 	git diff ${FLAGS:---stat} $b_commit $w_commit
 }
 
+show_help () {
+	exec git help stash
+	exit 1
+}
+
 #
 # Parses the remaining options looking for flags and
 # at most one revision defaulting to ${ref_stash}@{0}
@@ -373,6 +381,9 @@ parse_flags_and_rev()
 			--index)
 				INDEX_OPTION=--index
 			;;
+			--help)
+				show_help
+			;;
 			-*)
 				test "$ALLOW_UNKNOWN_FLAGS" = t ||
 					die "$(eval_gettext "unknown option: \$opt")"
-- 
2.4.1.396.g7ba6d7b

Re: [PATCH 2/1] stash: recognize "--help" for subcommands

[Vincent Legoll]

On Wed, May 20, 2015 at 8:17 PM, Jeff King <peff@peff.net> wrote:
> On Wed, May 20, 2015 at 02:01:32PM -0400, Jeff King wrote:
>
>> This takes away the immediate pain. We may also want to
>> teach "--help" to the option. I guess we cannot do better
>> than just having it run "git help stash" in all cases (i.e.,
>> we have no way to get the help for a specific subcommand).
>
> That actually turns out to be pretty painless...

Looks OK, but this "[PATCH 2/1]" is fishy...

-- 
Vincent Legoll

Re: [PATCH] stash: complain about unknown flags

[Vincent Legoll]

Hello,

On Wed, May 20, 2015 at 8:01 PM, Jeff King <peff@peff.net> wrote:
> The option parser for git-stash stuffs unknown flags into
> the $FLAGS variable, where they can be accessed by the
> individual commands. However, most commands do not even look
> at these extra flags, leading to unexpected results like
> this:
>
>   $ git stash drop --help
>   Dropped refs/stash@{0} (e6cf6d80faf92bb7828f7b60c47fc61c03bd30a1)
>
> We should notice the extra flags and bail. Rather than
> annotate each command to reject a non-empty $FLAGS variable,
> we can notice that "stash show" is the only command that
> actually _wants_ arbitrary flags. So we switch the default
> mode to reject unknown flags, and let stash_show() opt into
> the feature.

Better late than never, that does look good...

-- 
Vincent Legoll