summaryrefslogtreecommitdiff
path: root/refs.h
diff options
context:
space:
mode:
authorDavid Turner <dturner@twopensource.com>2016-02-25 15:05:46 -0500
committerJunio C Hamano <gitster@pobox.com>2016-02-25 12:35:31 -0800
commit49386868de1cebebfb1e9f9527560e17197ad94f (patch)
tree4c75dd3a81515d9248e1f940977bf3a837c04d62 /refs.h
parent754884255bb580df159e58defa81cdd30b5c430c (diff)
downloadgit-49386868de1cebebfb1e9f9527560e17197ad94f.tar.gz
refs: document transaction semanticsdt/initial-ref-xn-commit-doc
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>
Diffstat (limited to 'refs.h')
-rw-r--r--refs.h12
1 files changed, 12 insertions, 0 deletions
diff --git a/refs.h b/refs.h
index 7a04077489..19ebebcce0 100644
--- a/refs.h
+++ b/refs.h
@@ -109,6 +109,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
@@ -124,6 +129,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;