Re: [PATCH 3/8] tag: Change misleading --list <pattern> documentation

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 18, 2017, 18:43 UTC
Message-ID: <xmqqmvci2zoc.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20170318103256.27141-4-avarab@gmail.com>

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

Show 5 quoted lines

> However, documenting this as "-l <pattern>" was never correct, as
> these both worked before Jeff's change:
>
>     git tag -l 'v*'
>     git tag 'v*' -l

Actually, we do not particularly care about the latter, and quite honestly, I'd prefer we do not advertise and encourage the latter. Most Git commands take dashed options first and then non-dashed arguments, and so should "git tag". A more important example to show why "-l <pattern>" that pretends <pattern> is an argument to the option is wrong is this:

	git tag -l --merged X 'v*'

and this one

>     git tag --list 'v*rc*' '*2.8*'

Show 19 quoted lines

> diff --git a/t/t7004-tag.sh b/t/t7004-tag.sh
> index 74fc82a3c0..d36cd51fe2 100755
> --- a/t/t7004-tag.sh
> +++ b/t/t7004-tag.sh
> @@ -118,6 +118,18 @@ test_expect_success 'listing all tags if one exists should succeed' '
>  	git tag
>  '
>  
> +cat >expect <<EOF
> +mytag
> +EOF
> +test_expect_success 'Multiple -l or --list options are equivalent to one -l option' '
> +	git tag -l -l >actual &&
> +	test_cmp expect actual &&
> +	git tag --list --list >actual &&
> +	test_cmp expect actual &&
> +	git tag --list -l --list >actual &&
> +	test_cmp expect actual
> +'

OK. I do not care too deeply about this one, but somebody may want to tighten up the command line parsing to detect conflicting or duplicated cmdmode as an error in the future, and at that time this will require updating. I am not sure if we want to promise that giving multiple -l will keep working.

> +test_expect_success 'tag -l can accept multiple patterns interleaved with -l or --list options' '
> +	git tag -l "v1*" "v0*" >actual &&

This is good thing to promise that we will keep it working.

Show 5 quoted lines

> +	test_cmp expect actual &&
> +	git tag -l "v1*" --list "v0*" >actual &&
> +	test_cmp expect actual &&
> +	git tag -l "v1*" "v0*" -l --list >actual &&
> +	test_cmp expect actual

I'd prefer we do *not* promise that it will keep working if you give pattern and then later any dashed-option like -l to the command by having tests like these.

Thanks.