merge --no-ff is NOT mentioned in help

merge --no-ff is NOT mentioned in help

[Vanderhoof, Tzadik]

When I do: "git merge -h"  to get help, the option "--no-ff" is left out of the list of options.

This e-mail, including attachments, may include confidential and/or
proprietary information, and may be used only by the person or entity
to which it is addressed. If the reader of this e-mail is not the intended
recipient or his or her authorized agent, the reader is hereby notified
that any dissemination, distribution or copying of this e-mail is
prohibited. If you have received this e-mail in error, please notify the
sender by replying to this message and delete this e-mail immediately.

Re: merge --no-ff is NOT mentioned in help

[Mike Rappazzo]

On Wed, Nov 16, 2016 at 10:16 AM, Vanderhoof, Tzadik
<tzadik.vanderhoof@optum360.com> wrote:
> When I do: "git merge -h"  to get help, the option "--no-ff" is left out of the list of options.

I am running git version 2.10.0, and running git merge --help contains
these lines:

       --ff
           When the merge resolves as a fast-forward, only update the
branch pointer, without creating a merge commit. This is the default
behavior.

       --no-ff
           Create a merge commit even when the merge resolves as a
fast-forward. This is the default behaviour when merging an annotated
(and possibly signed) tag.

       --ff-only
           Refuse to merge and exit with a non-zero status unless the
current HEAD is already up-to-date or the merge can be resolved as a
fast-forward.

>
> This e-mail, including attachments, may include confidential and/or
> proprietary information, and may be used only by the person or entity
> to which it is addressed. If the reader of this e-mail is not the intended
> recipient or his or her authorized agent, the reader is hereby notified
> that any dissemination, distribution or copying of this e-mail is
> prohibited. If you have received this e-mail in error, please notify the
> sender by replying to this message and delete this e-mail immediately.
>

RE: merge --no-ff is NOT mentioned in help

[Vanderhoof, Tzadik]

I am running:    git version 2.10.1.windows.1

I typed: git merge -h

and got:

usage: git merge [<options>] [<commit>...]
   or: git merge [<options>] <msg> HEAD <commit>
   or: git merge --abort

    -n                    do not show a diffstat at the end of the merge
    --stat                show a diffstat at the end of the merge
    --summary             (synonym to --stat)
    --log[=<n>]           add (at most <n>) entries from shortlog to merge commit message
    --squash              create a single commit instead of doing a merge
    --commit              perform a commit if the merge succeeds (default)
    -e, --edit            edit message before committing
    --ff                  allow fast-forward (default)
    --ff-only             abort if fast-forward is not possible
    --rerere-autoupdate   update the index with reused conflict resolution if possible
    --verify-signatures   verify that the named commit has a valid GPG signature
    -s, --strategy <strategy>
                          merge strategy to use
    -X, --strategy-option <option=value>
                          option for selected merge strategy
    -m, --message <message>
                          merge commit message (for a non-fast-forward merge)
    -v, --verbose         be more verbose
    -q, --quiet           be more quiet
    --abort               abort the current in-progress merge
    --allow-unrelated-histories
                          allow merging unrelated histories
    --progress            force progress reporting
    -S, --gpg-sign[=<key-id>]
                          GPG sign commit
    --overwrite-ignore    update ignored files (default)

Notice there is NO mention of the "--no-ff" option

-----Original Message-----
From: Mike Rappazzo [mailto:rappazzo@gmail.com] 
Sent: Wednesday, November 16, 2016 7:37 AM
To: Vanderhoof, Tzadik
Cc: git@vger.kernel.org
Subject: Re: merge --no-ff is NOT mentioned in help

On Wed, Nov 16, 2016 at 10:16 AM, Vanderhoof, Tzadik <tzadik.vanderhoof@optum360.com> wrote:
> When I do: "git merge -h"  to get help, the option "--no-ff" is left out of the list of options.

I am running git version 2.10.0, and running git merge --help contains these lines:

       --ff
           When the merge resolves as a fast-forward, only update the branch pointer, without creating a merge commit. This is the default behavior.

       --no-ff
           Create a merge commit even when the merge resolves as a fast-forward. This is the default behaviour when merging an annotated (and possibly signed) tag.

       --ff-only
           Refuse to merge and exit with a non-zero status unless the current HEAD is already up-to-date or the merge can be resolved as a fast-forward.



This e-mail, including attachments, may include confidential and/or
proprietary information, and may be used only by the person or entity
to which it is addressed. If the reader of this e-mail is not the intended
recipient or his or her authorized agent, the reader is hereby notified
that any dissemination, distribution or copying of this e-mail is
prohibited. If you have received this e-mail in error, please notify the
sender by replying to this message and delete this e-mail immediately.

Re: merge --no-ff is NOT mentioned in help

[Mike Rappazzo]

(Please reply inline)

On Wed, Nov 16, 2016 at 10:48 AM, Vanderhoof, Tzadik
<tzadik.vanderhoof@optum360.com> wrote:
> I am running:    git version 2.10.1.windows.1
>
> I typed: git merge -h
>
> and got:
>
> usage: git merge [<options>] [<commit>...]
>    or: git merge [<options>] <msg> HEAD <commit>
>    or: git merge --abort
>
>     -n                    do not show a diffstat at the end of the merge
>     --stat                show a diffstat at the end of the merge
>     --summary             (synonym to --stat)
>     --log[=<n>]           add (at most <n>) entries from shortlog to merge commit message
>     --squash              create a single commit instead of doing a merge
>     --commit              perform a commit if the merge succeeds (default)
>     -e, --edit            edit message before committing
>     --ff                  allow fast-forward (default)
>     --ff-only             abort if fast-forward is not possible
>     --rerere-autoupdate   update the index with reused conflict resolution if possible
>     --verify-signatures   verify that the named commit has a valid GPG signature
>     -s, --strategy <strategy>
>                           merge strategy to use
>     -X, --strategy-option <option=value>
>                           option for selected merge strategy
>     -m, --message <message>
>                           merge commit message (for a non-fast-forward merge)
>     -v, --verbose         be more verbose
>     -q, --quiet           be more quiet
>     --abort               abort the current in-progress merge
>     --allow-unrelated-histories
>                           allow merging unrelated histories
>     --progress            force progress reporting
>     -S, --gpg-sign[=<key-id>]
>                           GPG sign commit
>     --overwrite-ignore    update ignored files (default)
>
> Notice there is NO mention of the "--no-ff" option

I understand.  On my system I can reproduce this by providing a bad
argument to `git merge`.  This is the output from the arg setup.  For
"boolean" arguments (like '--ff'), there is an automatic counter
argument with "no-" in there ('--no-ff') to disable the option.  Maybe
it would make sense to word the output to include both.


>
> -----Original Message-----
> From: Mike Rappazzo [mailto:rappazzo@gmail.com]
> Sent: Wednesday, November 16, 2016 7:37 AM
> To: Vanderhoof, Tzadik
> Cc: git@vger.kernel.org
> Subject: Re: merge --no-ff is NOT mentioned in help
>
> On Wed, Nov 16, 2016 at 10:16 AM, Vanderhoof, Tzadik <tzadik.vanderhoof@optum360.com> wrote:
>> When I do: "git merge -h"  to get help, the option "--no-ff" is left out of the list of options.
>
> I am running git version 2.10.0, and running git merge --help contains these lines:
>
>        --ff
>            When the merge resolves as a fast-forward, only update the branch pointer, without creating a merge commit. This is the default behavior.
>
>        --no-ff
>            Create a merge commit even when the merge resolves as a fast-forward. This is the default behaviour when merging an annotated (and possibly signed) tag.
>
>        --ff-only
>            Refuse to merge and exit with a non-zero status unless the current HEAD is already up-to-date or the merge can be resolved as a fast-forward.
>
>
>
> This e-mail, including attachments, may include confidential and/or
> proprietary information, and may be used only by the person or entity
> to which it is addressed. If the reader of this e-mail is not the intended
> recipient or his or her authorized agent, the reader is hereby notified
> that any dissemination, distribution or copying of this e-mail is
> prohibited. If you have received this e-mail in error, please notify the
> sender by replying to this message and delete this e-mail immediately.

RE: merge --no-ff is NOT mentioned in help

[Vanderhoof, Tzadik]

-----Original Message-----
From: Mike Rappazzo [mailto:rappazzo@gmail.com] 
Sent: Wednesday, November 16, 2016 7:58 AM
To: Vanderhoof, Tzadik
Cc: git@vger.kernel.org
Subject: Re: merge --no-ff is NOT mentioned in help

>(Please reply inline)
>
>On Wed, Nov 16, 2016 at 10:48 AM, Vanderhoof, Tzadik <tzadik.vanderhoof@optum360.com> wrote:
>> I am running:    git version 2.10.1.windows.1
>>
>> I typed: git merge -h
>>
>> and got:
>>
>> usage: git merge [<options>] [<commit>...]
>>    or: git merge [<options>] <msg> HEAD <commit>
>>    or: git merge --abort
>>
>>     -n                    do not show a diffstat at the end of the merge
>>     --stat                show a diffstat at the end of the merge
>>     --summary             (synonym to --stat)
>>     --log[=<n>]           add (at most <n>) entries from shortlog to merge commit message
>>     --squash              create a single commit instead of doing a merge
>>     --commit              perform a commit if the merge succeeds (default)
>>     -e, --edit            edit message before committing
>>     --ff                  allow fast-forward (default)
>>     --ff-only             abort if fast-forward is not possible
>>     --rerere-autoupdate   update the index with reused conflict resolution if possible
>>     --verify-signatures   verify that the named commit has a valid GPG signature
>>     -s, --strategy <strategy>
>>                           merge strategy to use
>>     -X, --strategy-option <option=value>
>>                           option for selected merge strategy
>>     -m, --message <message>
>>                           merge commit message (for a non-fast-forward merge)
>>     -v, --verbose         be more verbose
>>     -q, --quiet           be more quiet
>>     --abort               abort the current in-progress merge
>>     --allow-unrelated-histories
>>                           allow merging unrelated histories
>>     --progress            force progress reporting
>>     -S, --gpg-sign[=<key-id>]
>>                           GPG sign commit
>>     --overwrite-ignore    update ignored files (default)
>>
>> Notice there is NO mention of the "--no-ff" option
>
>I understand.  On my system I can reproduce this by providing a bad argument to `git merge`.  This is the output from the arg setup.  For "boolean" arguments (like '--ff'), there is an automatic counter argument with "no-" in there ('--no-ff') to disable the option.  Maybe it would make sense to word the output to include both.
>

Would you accept a pull request from me for this change?

>
>>
>> -----Original Message-----
>> From: Mike Rappazzo [mailto:rappazzo@gmail.com]
>> Sent: Wednesday, November 16, 2016 7:37 AM
>> To: Vanderhoof, Tzadik
>> Cc: git@vger.kernel.org
>> Subject: Re: merge --no-ff is NOT mentioned in help
>>
>> On Wed, Nov 16, 2016 at 10:16 AM, Vanderhoof, Tzadik <tzadik.vanderhoof@optum360.com> wrote:
>>> When I do: "git merge -h"  to get help, the option "--no-ff" is left out of the list of options.
>>
>> I am running git version 2.10.0, and running git merge --help contains these lines:
>>
>>        --ff
>>            When the merge resolves as a fast-forward, only update the branch pointer, without creating a merge commit. This is the default behavior.
>>
>>        --no-ff
>>            Create a merge commit even when the merge resolves as a fast-forward. This is the default behaviour when merging an annotated (and possibly signed) tag.
>>
>>        --ff-only
>>            Refuse to merge and exit with a non-zero status unless the current HEAD is already up-to-date or the merge can be resolved as a fast-forward.

This e-mail, including attachments, may include confidential and/or
proprietary information, and may be used only by the person or entity
to which it is addressed. If the reader of this e-mail is not the intended
recipient or his or her authorized agent, the reader is hereby notified
that any dissemination, distribution or copying of this e-mail is
prohibited. If you have received this e-mail in error, please notify the
sender by replying to this message and delete this e-mail immediately.

Re: merge --no-ff is NOT mentioned in help

[Junio C Hamano]

Mike Rappazzo <rappazzo@gmail.com> writes:

> (Please reply inline)

Indeed ;-)

> On Wed, Nov 16, 2016 at 10:48 AM, Vanderhoof, Tzadik
> <tzadik.vanderhoof@optum360.com> wrote:
>> I am running:    git version 2.10.1.windows.1
>>
>> I typed: git merge -h
>>
>> and got:
>>
>> usage: git merge [<options>] [<commit>...]
>>    or: git merge [<options>] <msg> HEAD <commit>
>>    or: git merge --abort
>>
>>     -n                    do not show a diffstat at the end of the merge
>>...
>>     --overwrite-ignore    update ignored files (default)
>>
>> Notice there is NO mention of the "--no-ff" option
>
> I understand.  On my system I can reproduce this by providing a bad
> argument to `git merge`.  This is the output from the arg setup.  For
> "boolean" arguments (like '--ff'), there is an automatic counter
> argument with "no-" in there ('--no-ff') to disable the option.  Maybe
> it would make sense to word the output to include both.

I think that was a deliberate design decision to avoid cluttering
the short help text with mention of both --option and --no-option.

People interested may want to try the attached single-liner patch to
see how the output from _ALL_ commands that use parse-options API
looks when given "-h".  It could be that the result may not be too
bad.

I suspect that we may discover that some options that should be
marked with NONEG are not marked along the way, which need to be
fixed.


 parse-options.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/parse-options.c b/parse-options.c
index 312a85dbde..348be6b240 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -626,7 +626,9 @@ static int usage_with_options_internal(struct parse_opt_ctx_t *ctx,
 		if (opts->long_name && opts->short_name)
 			pos += fprintf(outfile, ", ");
 		if (opts->long_name)
-			pos += fprintf(outfile, "--%s", opts->long_name);
+			pos += fprintf(outfile, "--%s%s", 
+				       (opts->flags & PARSE_OPT_NONEG) ? "" : "[no-]",
+				       opts->long_name);
 		if (opts->type == OPTION_NUMBER)
 			pos += utf8_fprintf(outfile, _("-NUM"));
 

Re: merge --no-ff is NOT mentioned in help

[Torsten Bögershausen]

On 17/11/16 18:10, Junio C Hamano wrote:
> Mike Rappazzo <rappazzo@gmail.com> writes:
>
>> (Please reply inline)
> Indeed ;-)
>
>> On Wed, Nov 16, 2016 at 10:48 AM, Vanderhoof, Tzadik
>> <tzadik.vanderhoof@optum360.com> wrote:
>>> I am running:    git version 2.10.1.windows.1
>>>
>>> I typed: git merge -h
>>>
>>> and got:
>>>
>>> usage: git merge [<options>] [<commit>...]
>>>     or: git merge [<options>] <msg> HEAD <commit>
>>>     or: git merge --abort
>>>
>>>      -n                    do not show a diffstat at the end of the merge
>>> ...
>>>      --overwrite-ignore    update ignored files (default)
>>>
>>> Notice there is NO mention of the "--no-ff" option
>> I understand.  On my system I can reproduce this by providing a bad
>> argument to `git merge`.  This is the output from the arg setup.  For
>> "boolean" arguments (like '--ff'), there is an automatic counter
>> argument with "no-" in there ('--no-ff') to disable the option.  Maybe
>> it would make sense to word the output to include both.
> I think that was a deliberate design decision to avoid cluttering
> the short help text with mention of both --option and --no-option.
>
> People interested may want to try the attached single-liner patch to
> see how the output from _ALL_ commands that use parse-options API
> looks when given "-h".  It could be that the result may not be too
> bad.
>
> I suspect that we may discover that some options that should be
> marked with NONEG are not marked along the way, which need to be
> fixed.
>
>
>   parse-options.c | 4 +++-
>   1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/parse-options.c b/parse-options.c
> index 312a85dbde..348be6b240 100644
> --- a/parse-options.c
> +++ b/parse-options.c
> @@ -626,7 +626,9 @@ static int usage_with_options_internal(struct parse_opt_ctx_t *ctx,
>   		if (opts->long_name && opts->short_name)
>   			pos += fprintf(outfile, ", ");
>   		if (opts->long_name)
> -			pos += fprintf(outfile, "--%s", opts->long_name);
> +			pos += fprintf(outfile, "--%s%s",
> +				       (opts->flags & PARSE_OPT_NONEG) ? "" : "[no-]",
> +				       opts->long_name);
>   		if (opts->type == OPTION_NUMBER)
>   			pos += utf8_fprintf(outfile, _("-NUM"));
>   
+1 from my side
(As I once spend some time to find out that the "no--" is automatically available)

Re: merge --no-ff is NOT mentioned in help

[Jeff King]

On Thu, Nov 17, 2016 at 09:10:22AM -0800, Junio C Hamano wrote:

> People interested may want to try the attached single-liner patch to
> see how the output from _ALL_ commands that use parse-options API
> looks when given "-h".  It could be that the result may not be too
> bad.

The output is less ugly than I expected, but still a bit cluttered IMHO.
I was surprised that the column-adjustment did not need tweaked, but the
code correctly increments "pos" from the return value of fprintf, which
just works.

Looking at the output for --ff, though:

   --[no-]ff             allow fast-forward (default)

I do not think it's improving the situation nearly as much as if we made
the primary option "--no-ff" with a NONEG flga, and then added back in a
HIDDEN "--ff". I thought we had done that in other cases, but I can't
seem to find any. But it would make "--no-ff" the primary form, which
makes sense, as "--ff" is already the default.

Another option would be to teach parse-options to somehow treat the
negated form as primary in the help text. That's a bit more code, but
might be usable in other places.

-Peff

RE: merge --no-ff is NOT mentioned in help

[Vanderhoof, Tzadik]

> On Thu, Nov 17, 2016 at 09:10:22AM -0800, Junio C Hamano wrote:
> 
> > People interested may want to try the attached single-liner patch to 
> > see how the output from _ALL_ commands that use parse-options API 
> > looks when given "-h".  It could be that the result may not be too 
> > bad.
> 
> The output is less ugly than I expected, but still a bit cluttered IMHO.
> I was surprised that the column-adjustment did not need tweaked, but the code correctly increments "pos" from the return value of fprintf, which just works.
> 
> Looking at the output for --ff, though:
> 
>    --[no-]ff             allow fast-forward (default)
> 
> I do not think it's improving the situation nearly as much as if we made the primary option "--no-ff" with a NONEG flga, and then added back in a HIDDEN "--ff". I thought we had done that in other cases, but I can't seem to find any. But it would make "--no-ff" the primary form, which makes sense, as "--ff" is already the default.
> 
> Another option would be to teach parse-options to somehow treat the negated form as primary in the help text. That's a bit more code, but might be usable in other places.
> 
> -Peff
>

What about leaving the help as is, but adding a sentence at the end (or beginning?) like: "The following options may be negated by adding 'no-' after the double dashes"?

This e-mail, including attachments, may include confidential and/or
proprietary information, and may be used only by the person or entity
to which it is addressed. If the reader of this e-mail is not the intended
recipient or his or her authorized agent, the reader is hereby notified
that any dissemination, distribution or copying of this e-mail is
prohibited. If you have received this e-mail in error, please notify the
sender by replying to this message and delete this e-mail immediately.