Re: [PATCH 7/7] push: document --lockref

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 14, 2013, 19:17 UTC
Message-ID: <7v61wdgdd1.fsf@alter.siamese.dyndns.org>
In-Reply-To: <51E1B5DB.9080904@kdbg.org>

Johannes Sixt <j6t@kdbg.org> writes:

Show 10 quoted lines

> All you have been saying is that you find your
>
>    git push --lockref there topic
>
> is more useful than my
>
>    git push --lockref there +topic
>
> You are trading crystal clear semantics to save users ONE character to
> type. IMO, it's a bad deal.

Think how you would explain the option in a tutorial for those who use the push.default=simple semantics.

"""
	You usually do

		$ git pull [--rebase]

	to integrate with the shared branch and push it back with

		$ git push

	Sometimes the project wants to rewind the tip of such a
	shared branch (perhaps a bad commit included inappropriate
	material that should not be in the history).  You cordinate
	the decision to do such a rewinding with others in the
	project, you "git rebase [-i]" to prepare a replacement
	history, and then try to push tthe result out.  However

		$ git push

	will fail, because this does not fast-forward.  But you and
	your colleagues agreed that the project wants this new
	history!

        With older Git, the only way to make this push go through
        was to "--force" it.  That will risk losing work of other
        people who were not aware of the collective decision to
        rewind this shared branch [discussion of lockref safety
        comes here].  Instead you can use

		$ git push --lockref

"""

How does the last line look with your "--lockref does not override must-fast-forward" proposal?

"""

	If your current branch is configured to push to update the
	branch 'frotz' of the remote 'origin' (replace these two
	appropriately for your situation), you would say:

		$ git push --lockref origin +HEAD:frotz

"""

How is that crystal clear? You are just making things more complex and harder to learn (I was tempted to add "for no good reason" here, but I'd assume that probably you haven't explained your reasons well enough to be heard).

Show 7 quoted lines

> The crystal clear semantics would be:
>
>  - to override no-ff safety, use +refspec;
>
>  - to override "mismatch" safety, do not use --lockref/use --no-lockref;
>
>  - do not use --force unless you know the consequences.

Alternatively, this is also crystal clear

 - to use the full safety, do not use anything funky

 - to push a history that does not fast-forward safely, use
   --lockref

 - do not use --force unless you know the consequences.

and that is what the patch does.

> I actually think that by implying allow-no-ff in --lockref, you are
> hurting users who have configured a push refspec without a + prefix:
> They suddenly do not get the push denied when it is not a fast-forward
> anymore.

Of course, that is why you should not use --lockref when you do not have to. It is a tool to loosen "must fast-forward" in a more controlled way than the traditional "--force".

 For example, when you have

Show 11 quoted lines

>
>     [remote "ko"]
>         push = master
>         push = +pu
>
> and you accidentally rewound master before the point that is already
> published, then
>
>    git push --lockref ko
>
> will happily push the rewound master.

Yes, and I am not (and I do expect nobody is) stupid to use --lockref in such a situation where there is no need to do so.