From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 05 Sep 2013 21:23:52 GMT
Subject: Re: [PATCH v4 7/8] update-ref: support multiple simultaneous updates
Message-ID: <xmqqk3ivgdxz.fsf@gitster.dls.corp.google.com>
In-Reply-To: <5228EA62.7030606@kitware.com>

Brad King <brad.king@kitware.com> writes:

> On 09/04/2013 05:27 PM, Junio C Hamano wrote:
>> I am not saying the above is the best format, but the point is that
>> the mode of the operation defines the structure
>
> Great, thanks for your comments.  Based on that I've prototyped a
> new format.  Rather than jumping straight to the patch, here is my
> proposed format documentation for review:
>
> -------------------------------------------------------------------------
> With `--stdin`, update-ref reads instructions from standard input and
> performs all modifications together.  Specify commands of the form:
>
> 	create SP <ref> SP <newvalue> LF
> 	update SP <ref> SP <newvalue> [SP <oldvalue>] LF
> 	delete SP <ref> [SP <oldvalue>] LF
> 	verify SP <ref> [SP <oldvalue>] LF
> 	option SP <opt> LF
>
> Quote fields containing whitespace as if they were strings in C source
> code.  Alternatively, use `-z` to specify commands without quoting:
>
> 	create SP <ref> NUL <newvalue> NUL
> 	update SP <ref> NUL <newvalue> NUL [<oldvalue>] NUL
> 	delete SP <ref> NUL [<oldvalue>] NUL
> 	verify SP <ref> NUL [<oldvalue>] NUL
> 	option SP <opt> NUL

That SP in '-z' format looks strange.  Was there a reason why NUL
was inappropriate?

> Lines of any other format or a repeated <ref> produce an error.
> Command meanings are:
>
> create::
> 	Create <ref> with <newvalue> only if it does not exist.
>
> update::
> 	Update <ref> to be <newvalue>, verifying <oldvalue> if given.
> 	Specify a zero <newvalue> to delete a ref and/or a zero
> 	<oldvalue> to make sure that a ref does not exist.
>
> delete::
> 	Delete <ref>, verifying <oldvalue> if given.
>
> verify::
> 	Verify <ref> against <oldvalue> but do not change it.  If
> 	<oldvalue> zero or missing, the ref must not exist.
>
> option::
> 	Specify an option to take effect for following commands.
> 	Valid options are `deref` and `no-deref` to specify whether
> 	to dereference symbolic refs.

This last one is somewhat peculiar, especially because it says
"following command*s*".

How would I request to update refs HEAD and next in an all-or-none
fashion, while applying 'no-deref' only to HEAD but not next?

	update refs/heads/next <newvalue>
	option --no-deref
        update HEAD <newvalue>

sounds somewhat convoluted.

When I said "create or update" in the message you are responding to,
I did not mean that we should have two separate commands.  The
regular command line does create-or-update; if it exists already, it
is an update, and if it does not, it is a create.

If we were to have two, I would say we should have:

	create-or-update <ref> <newvalue> [<oldvalue>]
	create-or-update-no-deref <ref> <newvalue> [<oldvalue>]
        
An old value of 0{40} would mean "I should be the one creating; if
somebody else created it while I was preparing this request, please
fail".

Similarly for delete:

	delete <ref> [<oldvalue>]
        delete-no-deref <ref> [<oldvalue>]

Also how would one set the reflog message for the proposed update?