Re: [PATCH v4 3/3] t, doc: update tests, reference for "--force-if-includes"

[Junio C Hamano <gitster@pobox.com>]

Srinidhi Kaushik <shrinidhi.kaushik@gmail.com> writes:

> Subject: Re: [PATCH v4 3/3] t, doc: update tests, reference for "--force-if-includes"

good.

> * t/t5533-push-cas.sh:
>     Updates test cases for "compare-and-swap" when used along with
>     "--force-if-includes" helps mitigate overwrites when remote
>     ref are updated in the background.
>
> * Documentation:
>     Adds reference for the new option, configuration setting
>     ("push.useForceIfIncludes") and advise messages.

s/Updates/Update/; s/Adds/Add/;

> +push.useForceIfIncludes::
> +	If set to "true", it is equivalent to specifying "--force-if-includes"
> +	as an argument to linkgit:git-push[1]. Adding "--no-force-if-includes"

s/as an argument to/on the command line of/ would be better.

Some readers differenciate arguments and options and we are
discussing an option, not an argument.

> +Alternatively, specifying "--force-if-includes" an an ancillary option along
> +with "--force-with-lease[=<refname>]" (i.e., without saying what exact commit
> +the ref on the remote side must be pointing at, or which refs on the remote
> +side are being protected) at the time of "push" will verify if updates from the
> +remote-tracking refs that may have been implicitly updated in the background
> +are integrated locally before allowing a forced update.

OK.  A user who wants to know more can refer to --force-if-includes
from here pretty easily.

> @@ -341,6 +348,19 @@ one branch, use a `+` in front of the refspec to push (e.g `git push
>  origin +master` to force a push to the `master` branch). See the
>  `<refspec>...` section above for details.
>  
> +--[no-]force-if-includes::
> +	Force an update only if the tip of the remote-tracking ref
> +	has been integrated locally.
> ++
> +This option verifies if the tip of the remote-tracking ref on which
> +a local branch has based on (for a rewrite), is reachable from at
> +least one of the "reflog" entries of the local branch about to be
> +updated by force on the remote.

The latter half of this sentence is quite a mouthful, and after
reading it three times, it is not quite clear.

> +The check ensures that any updates
> +from the remote have been incorporated locally by rejecting a push
> +if that is not the case.

OK.

> ++
> +Specifying "--no-force-if-includes" disables this behavior.

Do we want to add:

    It is a no-op unless "--force-with-lease[=<refname>]" without exact
    object name is used at the same time.

here or somewhere nearby?


> +test_expect_success 'background updates of REMOTE can be mitigated with "--force-if-includes"' '
> +	rm -rf src dst &&
> +	git init --bare src.bare &&
> +	test_when_finished "rm -rf src.bare" &&
> +	git clone --no-local src.bare dst &&
> +	test_when_finished "rm -rf dst" &&
> +	(
> +		cd dst &&
> +		test_commit G &&
> +		git push origin master:master
> +	) &&
> +	git clone --no-local src.bare dst2 &&
> +	test_when_finished "rm -rf dst2" &&
> +	(
> +		cd dst2 &&
> +		test_commit H &&
> +		git push
> +	) &&
> +	(
> +		cd dst &&
> +		test_commit I &&
> +		git fetch origin &&
> +		test_must_fail git push --force-with-lease --force-if-includes origin

I briefly wondered if it makes sense to also check if
--force-with-lease alone (or with --no-force-if-includes)
successfully pushes in this case, but I think we are OK without such
a test.  After all, we won't test "--force" alone, either, as we
expect that to work (and should be tested elsewhere).

> +	)
> +'
> +
> +test_expect_success 'background updates of REMOTE can be mitigated with "push.useForceIfIncludes"' '
> +	rm -rf src dst &&
> +	git init --bare src.bare &&
> +	test_when_finished "rm -rf src.bare" &&
> +	git clone --no-local src.bare dst &&
> +	test_when_finished "rm -rf dst" &&
> +	(
> +		cd dst &&
> +		test_commit G &&
> +		git push origin master:master
> +	) &&
> +	git clone --no-local src.bare dst2 &&
> +	test_when_finished "rm -rf dst2" &&
> +	(
> +		cd dst2 &&
> +		test_commit H &&
> +		git push
> +	) &&
> +	(
> +		cd dst &&
> +		test_commit I &&
> +		git fetch origin &&
> +		git config --local push.useForceIfIncludes "true" &&
> +		test_must_fail git push --force-if-includes origin

I am not sure what is tested here.  I thought with or without the
configuration variable, the feature is a no-op unless a lazy
force-with-lease is in use?

Perhaps you meant to test

		test_must_fail git push --force-with-lease origin

instead?

> +	)
> +'
> +
>  test_done

Thanks.