Re: [PATCH v2] merge-options.txt: correct wording of --no-commit option

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 19, 2019, 19:32 UTC
Message-ID: <xmqqk1hv1sms.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <20190219170709.25463-1-newren@gmail.com>

Elijah Newren <newren@gmail.com> writes:

Show 9 quoted lines

> +With --no-commit perform the merge and stop just before creating
> +a merge commit, to give the user a chance to inspect and further
> +tweak the merge result before committing.
> ++
> +Note that fast-forward updates do not need to create a merge
> +commit and therefore there is no way to stop those merges with
> +--no-commit.  Thus, if you want to ensure your branch is not
> +changed or updated by the merge command, use --no-ff with
> +--no-commit.

While the above is an improvement (so I'll queue it on 'pu' not to lose sight of it), I find the use of "do not need to" above somewhat misleading. It solicits a reaction "ok, we know it does not need to, but it could prepare to create one to allow us to further muck with it, no?".

IOW, a fast-forward by definition does not create a merge by itself, so there is nowhere to stop during a creation of a merge. So at least:

	s/do not need to/do not/

It also may be a good idea to consider detecting this case and be a bit more helpful, perhaps with end-user experience looking like...

  $ git checkout master^0
  $ git merge --no-commit next
  Updating 0d0ac3826a..ee538a81fe
  Fast-forward
    ...diffstat follows here...
  hint: merge completed without creating a commit.
  hint: if you wanted to prepare for a manually tweaked merge,
  hint: do "git reset --keep ORIG_HEAD" followed by
  hint: "git merge --no-ff --no-commit next".

or even

  $ git checkout master^0
  $ git merge --no-commit next
  warning: defaulting to --no-ff, given a --no-commit request
  Automatic merge went well; stopped before committing as requested
  hint: if you'd rather have a fast-forward without creating a commit,
  hint: do "git reset --keep next" now.

I do not have a strong preference among three (the third option being not doing anything), but if pressed, I'd say that the last one might be the most user-friendly, even though it feels a bit too magical and trying to be smarter than its own good.

In any case, the hint for the "recovery" procedure needs to be carefully written.