From: Brad King <brad.king@kitware.com>
Date: Thu, 05 Sep 2013 23:44:26 GMT
Subject: Re: [PATCH v4 7/8] update-ref: support multiple simultaneous updates
Message-ID: <5229175A.4070203@kitware.com>
In-Reply-To: <xmqqk3ivgdxz.fsf@gitster.dls.corp.google.com>

On 9/5/2013 5:23 PM, Junio C Hamano wrote:
> Brad King <brad.king@kitware.com> writes:
>> 	create SP <ref> NUL <newvalue> NUL
>> 	update SP <ref> NUL <newvalue> NUL [<oldvalue>] NUL
> 
> That SP in '-z' format looks strange.  Was there a reason why NUL
> was inappropriate?

The precedent I saw in the -z survey I posted is that NUL is used
to terminate fields that can contain arbitrary text but otherwise
SP or TAB is still used to terminate simple fields.  I recall no
cases that use NUL after fields that only contain simple values.

>> option::
>> 	Specify an option to take effect for following commands.
> 
> 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?

You're right.  It will be simpler for clients to generate each
sequence of options followed by a <ref> command without worrying
about options possibly generated for preceding <ref>s.  So:

option::
	Modify behavior of the next command naming a <ref>.
	The only valid option is `no-deref` to avoid dereferencing
	a symbolic ref.

> 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 nice thing about "create" is that it implies oldvalue=zero, just
as "delete" implies newvalue=zero.  The symmetry feels clean.  Also,
in -z mode we need to treat an empty string <oldvalue> as missing
rather than zero.  The only way to specify create with the "update"
command is with literal 40 "0" as <oldvalue>.

> 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.

The proposed update command can be used for create, update, delete,
or verify with proper arguments and use of 40 "0".  The other <ref>
commands are for convenience, shorter input, and statement of intent.

> 	create-or-update-no-deref <ref> <newvalue> [<oldvalue>]
>         delete-no-deref <ref> [<oldvalue>]
> 
> Also how would one set the reflog message for the proposed update?

This is why I proposed a separate option command.  It can be used
both for no-deref and for other options we want to add later e.g.

  option SP message SP <reason> LF

and with -z:

  option SP message SP <reason> NUL

For now I think it is sufficient for the -m <reason> command-line
option to set the same message for all updates.  The option command
leaves room to add a per-ref message later.

BTW, the reasons I propose message as an option rather than its own
command are:

* It is simpler to document the reach of the one option command
  (affects next <ref>) in one place rather than separately for
  each option-like command.

* It reduces the number of commands that do not take a <ref>.

-Brad