From: Brad King <brad.king@kitware.com>
Date: Thu, 05 Sep 2013 20:32:34 GMT
Subject: Re: [PATCH v4 7/8] update-ref: support multiple simultaneous updates
Message-ID: <5228EA62.7030606@kitware.com>
In-Reply-To: <xmqqd2ool1ks.fsf@gitster.dls.corp.google.com>

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

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.

Use 40 "0" or the empty string to specify a zero value, except that
with `-z` an empty <oldvalue> is considered missing.

If all <ref>s can be locked with matching <oldvalue>s
simultaneously, all modifications are performed.  Otherwise, no
modifications are performed.  Note that while each individual
<ref> is updated or deleted atomically, a concurrent reader may
still see a subset of the modifications.
-------------------------------------------------------------------------

Thanks,
-Brad