Re: [PATCH] refs: document transaction semantics

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

David Turner <dturner@twopensource.com> writes:

> I thought it would be better in the api docs, since it's a design
> decision that all backends should follow.

Makes sense; as this describes an already available API, it
shouldn't have to wait for the remainder of your series and can just
go to 'master' (or even to 'maint' if we wanted to), right?



> On Thu, 2016-02-25 at 15:05 -0500, David Turner wrote:
>> Add some comments on ref transaction semantics to refs.h
>> 
>> Signed-off-by: David Turner <dturner@twopensource.com>
>> ---
>>  refs.h | 12 ++++++++++++
>>  1 file changed, 12 insertions(+)
>> 
>> diff --git a/refs.h b/refs.h
>> index c0964f5..9b3eaf3 100644
>> --- a/refs.h
>> +++ b/refs.h
>> @@ -112,6 +112,11 @@ extern int dwim_log(const char *str, int len,
>> unsigned char *sha1, char **ref);
>>   *   If this succeeds, the ref updates will have taken place and
>>   *   the transaction cannot be rolled back.
>>   *
>> + * - Instead of `ref_transaction_commit`, use
>> + *   `initial_ref_transaction_commit()` if the ref database is known
>> + *   to be empty (e.g. during clone).  This is likely to be much
>> + *   faster.
>> + *
>>   * - At any time call `ref_transaction_free()` to discard the
>>   *   transaction and free associated resources.  In particular,
>>   *   this rolls back the transaction if it has not been
>> @@ -127,6 +132,13 @@ extern int dwim_log(const char *str, int len,
>> unsigned char *sha1, char **ref);
>>   *
>>   * The message is appended to err without first clearing err.
>>   * err will not be '\n' terminated.
>> + *
>> + * Caveats
>> + * -------
>> + *
>> + * Note that no locks are taken, and no refs are read, until
>> + * `ref_transaction_commit` is called.  So `ref_transaction_verify`
>> + * won't report a verification failure until the commit is
>> attempted.
>>   */
>>  struct ref_transaction;
>>