I thought it would be better in the api docs, since it's a design decision that all backends should follow. 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@xxxxxxxxxxxxxxxx> > --- > 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; > -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html