patchDocumentation/merge-options: clarify --squash behavior

Add a note to the --squash option for git-merge to clarify its behavior with respect to --commit. When --squash is supplied, 'option_commit' is silently dropped. This can be surprising to a user who tries to override the no-commit behavior of squash using --commit explicitly.

Signed-off-by: Vishal Verma <vishal.l.verma@intel.com>
---

There may be an argument to make --commit 'just work' with squash, but that might involve changing option_commit from OPT_BOOL to something that can distinguish between the default, what's requested on the command line, or the --no- version.

 Documentation/merge-options.txt | 3 +++
 1 file changed, 3 insertions(+)

Vishal Verma <vishal.l.verma@intel.com> writes:

I think it is bad to silently ignore the option. With or without this documentation update, I think it is sensible to update the code so that it errors out when "--squash --commit" are both given at the same time, just like when "--squash --no-ff" is given.

Or make it "just work" as you said. Using a boolean variable as tristate is something we do in many places and it by itself is not a rocket science. You initialize the variable to -1 (unset), let parse_options() to set it to 0/1 when "--[no-]commit" is seen, and inspect after parse_options() finishes. If the variable is still -1, you know the user wants "the default" behaviour.

The "default" behaviour you are proposing would probably be something like

        if (option_commit < 0) {
                /* 
                 * default to record the result in a commit.
                 * but --squash traditionally does not.
                 */
                if (!squash)
                        option_commit = 1;
                else
                        option_commit = 0;
        }

But I suspect that the option parsing part is the least difficult in the "make it just work" change. That is because I think that the machinery to record the result in a commit is not expecting to be asked to create a single-parent commit to record the result of the squashing, so there may be need for adjusting to how the result wants to be recorded before the code makes a commit.

On Thu, 2019-04-25 at 13:16 +0900, Junio C Hamano wrote:

Yes that makes sense.

Ah I see - I was conflating OPT_BOOL with the parameter being a boolean as well without checking, but I see now that isn't the case.

Yes I was going to try to allow the commit option as an experiment, and just see what happens. For now I'll send a v2 that has a doc update as well as prints a warning using the above technique.

I'll dig more into what allowing --commit actually means (as time allows) - I'm definitely a newbie with git internals, and indeed this is my first posting here.

Thanks for the feedback!

	-Vishal

From: Vishal Verma <vishal@stellar.sh>

Convert option_commit to tristate, representing the states of 'default/untouched', 'enabled-by-cli', 'disabled-by-cli'. With this in place, check whether option_commit was enabled by cli when squashing a merge. If so, error out, as this is not supported.

Add a note to the --squash option for git-merge to clarify the incompatibility.

Previously, when --squash was supplied, 'option_commit' was silently dropped. This could have been surprising to a user who tried to override the no-commit behavior of squash using --commit explicitly.

Cc: Junio C Hamano <gitster@pobox.com>
Cc: Rafael Ascensão <rafa.almas@gmail.com>
Signed-off-by: Vishal Verma <vishal@stellar.sh>
---

v2:
 - Error out when both --squash and --commit are supplied (Junio)
 - Adjust the documentation accordingly.

 Documentation/merge-options.txt |  2 ++
 builtin/merge.c                 | 18 +++++++++++++++++-
 2 files changed, 19 insertions(+), 1 deletion(-)