Merge branch 'dt/initial-ref-xn-commit-doc'

* dt/initial-ref-xn-commit-doc:
refs: document transaction semantics

diff --combined refs.h
index 3c3da29bf0064cd189a6b0c8dc1a7daeb953150e,19ebebcce0e90586a44e903294ccd30599406c1f..2f3decb432cfeda97fd5da7f16dd4e5b725b59bc
--- 1/refs.h
--- 2/refs.h
+++ b/refs.h
@@@ -109,6 -109,11 +109,11 @@@ extern int dwim_log(const char *str, in
   *   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 +129,13 @@@
   *
   * 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;
  
@@@ -292,7 -304,7 +304,7 @@@ extern char *shorten_unambiguous_ref(co
  /** rename ref, return 0 on success **/
  extern int rename_ref(const char *oldref, const char *newref, const char *logmsg);
  
 -extern int create_symref(const char *ref, const char *refs_heads_master, const char *logmsg);
 +extern int create_symref(const char *refname, const char *target, const char *logmsg);
  
  enum action_on_err {
        UPDATE_REFS_MSG_ON_ERR,