Subject: Re: [PATCH 2/6] merge, pull: introduce '--(no-)stat' option

From: Junio C Hamano <[email-masked]>
Date: Sat, 05 Apr 2008 19:36:57 -0700

SZEDER Gábor <[email-masked]> writes:

> '--(no-)summary' options are still accepted, but are not advertised.

Given that...

> diff --git a/git-merge.sh b/git-merge.sh
> index 7dbbb1d..1b693ad 100755
> --- a/git-merge.sh
> +++ b/git-merge.sh
> @@ -8,8 +8,8 @@ OPTIONS_SPEC="\
>  git-merge [options] <remote>...
>  git-merge [options] <msg> HEAD <remote>
>  --
> -summary              show a diffstat at the end of the merge
> -n,no-summary         don't show a diffstat at the end of the merge
> +stat                 show a diffstat at the end of the merge
> +n,no-stat            don't show a diffstat at the end of the merge
>  squash               create a single commit instead of doing a merge
>  commit               perform a commit if the merge sucesses (default)
>  ff                   allow fast forward (default)

...this hunk removes the original options from OPTIONS_SPEC, I suspect you
would get "unknown option 'stat'" from underlying "git rev-parse --parseopt".

You probably haven't noticed the breakage because you replaced all
existing --summary with --stat in the tests, though.  Oops.

We would want to take a three-stage approach where we (1) start accepting
both forms without changing the official names shown to the users, (2)
deprecate the old names and make the new ones official, and then (3)
finally remove the old ones.  Your 2 thru 5 roll (1) and (2) into one
step.

I would not have major problem with this "hasty deprecation" in "usage"
strings, but I find it somewhat problematic to stop mentioning the old
names in the documentation and bash completion from day one.  People learn
old names elsewhere (e.g. in somebody's blog entry) and then try to find
the description in their manual and they are already removed from your
copy.  Oops.

So I pretty much prefer to have an explicit deprecation period where both
forms are not just accepted but described as equals, but with the older
ones marked clearly as deprecated and planned for removal, so that people
would know what is going on.

Other than that, the rest of the series looked Ok from my cursory review.