refs: document transaction semantics
Add some comments on ref transaction semantics to refs.h Signed-off-by: David Turner <dturner@twopensource.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
David Turner committed
Feb 25, 2016 at 15:05 UTC
49386868de1cebebfb1e9f9527560e17197ad94f
1 file changed
+12
refs.h
+12
@@ -109,6 +109,11 @@ extern int dwim_log(const char *str, int len, unsigned char *sha1, char **ref);
109
* If this succeeds, the ref updates will have taken place and
110
* the transaction cannot be rolled back.
111
*
112
+ * - Instead of `ref_transaction_commit`, use
113
+ * `initial_ref_transaction_commit()` if the ref database is known
114
+ * to be empty (e.g. during clone). This is likely to be much
115
+ * faster.
116
+ *
117
* - At any time call `ref_transaction_free()` to discard the
118
* transaction and free associated resources. In particular,
119
* this rolls back the transaction if it has not been
@@ -124,6 +129,13 @@ extern int dwim_log(const char *str, int len, unsigned char *sha1, char **ref);
129
*
130
* The message is appended to err without first clearing err.
131
* err will not be '\n' terminated.
132
+ *
133
+ * Caveats
134
+ * -------
135
+ *
136
+ * Note that no locks are taken, and no refs are read, until
137
+ * `ref_transaction_commit` is called. So `ref_transaction_verify`
138
+ * won't report a verification failure until the commit is attempted.
139
*/
140
struct ref_transaction;
141