struct ref_transaction *ref_transaction_begin(struct strbuf *err);
/*
- * The following functions add a reference check or update to a
- * ref_transaction. In all of them, refname is the name of the
- * reference to be affected. The functions make internal copies of
- * refname and msg, so the caller retains ownership of these parameters.
- * flags can be REF_NODEREF; it is passed to update_ref_lock().
+ * Reference transaction updates
+ *
+ * The following four functions add a reference check or update to a
+ * ref_transaction. They have some common similar parameters:
+ *
+ * transaction -- a pointer to an open ref_transaction, obtained
+ * from ref_transaction_begin().
+ *
+ * refname -- the name of the reference to be affected.
+ *
+ * flags -- flags affecting the update, passed to
+ * update_ref_lock(). Can be REF_NODEREF, which means that
+ * symbolic references should not be followed.
+ *
+ * msg -- a message describing the change (for the reflog).
+ *
+ * err -- a strbuf for receiving a description of any error that
+ * might have occured.
+ *
+ * The functions make internal copies of refname and msg, so the
+ * caller retains ownership of these parameters.
+ *
+ * The functions return 0 on success and non-zero on failure. A
+ * failure means that the transaction as a whole has failed and needs
+ * to be rolled back.
*/
/*
- * Add a reference update to transaction. new_sha1 is the value that
- * the reference should have after the update, or null_sha1 if it should
- * be deleted. If old_sha1 is non-NULL, then it is the value
- * that the reference should have had before the update, or null_sha1 if
- * it must not have existed beforehand.
- * Function returns 0 on success and non-zero on failure. A failure to update
- * means that the transaction as a whole has failed and will need to be
- * rolled back.
+ * Add a reference update to transaction. new_sha1 is the value that
+ * the reference should have after the update, or null_sha1 if it
+ * should be deleted. If new_sha1 is NULL, then the reference is not
+ * changed at all. old_sha1 is the value that the reference must have
+ * before the update, or null_sha1 if it must not have existed
+ * beforehand. The old value is checked after the lock is taken to
+ * prevent races. If the old value doesn't agree with old_sha1, the
+ * whole transaction fails. If old_sha1 is NULL, then the previous
+ * value is not checked.
+ *
+ * See the above comment "Reference transaction updates" for more
+ * information.
*/
int ref_transaction_update(struct ref_transaction *transaction,
const char *refname,
struct strbuf *err);
/*
- * Add a reference creation to transaction. new_sha1 is the value
- * that the reference should have after the update; it must not be the
- * null SHA-1. It is verified that the reference does not exist
+ * Add a reference creation to transaction. new_sha1 is the value that
+ * the reference should have after the update; it must not be
+ * null_sha1. It is verified that the reference does not exist
* already.
- * Function returns 0 on success and non-zero on failure. A failure to create
- * means that the transaction as a whole has failed and will need to be
- * rolled back.
+ *
+ * See the above comment "Reference transaction updates" for more
+ * information.
*/
int ref_transaction_create(struct ref_transaction *transaction,
const char *refname,
struct strbuf *err);
/*
- * Add a reference deletion to transaction. If old_sha1 is non-NULL, then
- * it holds the value that the reference should have had before
- * the update (which must not be the null SHA-1).
- * Function returns 0 on success and non-zero on failure. A failure to delete
- * means that the transaction as a whole has failed and will need to be
- * rolled back.
+ * Add a reference deletion to transaction. If old_sha1 is non-NULL,
+ * then it holds the value that the reference should have had before
+ * the update (which must not be null_sha1).
+ *
+ * See the above comment "Reference transaction updates" for more
+ * information.
*/
int ref_transaction_delete(struct ref_transaction *transaction,
const char *refname,
unsigned int flags, const char *msg,
struct strbuf *err);
+/*
+ * Verify, within a transaction, that refname has the value old_sha1,
+ * or, if old_sha1 is null_sha1, then verify that the reference
+ * doesn't exist. old_sha1 must be non-NULL.
+ *
+ * See the above comment "Reference transaction updates" for more
+ * information.
+ */
+int ref_transaction_verify(struct ref_transaction *transaction,
+ const char *refname,
+ const unsigned char *old_sha1,
+ unsigned int flags,
+ struct strbuf *err);
+
/*
* Commit all of the changes that have been queued in transaction, as
* atomically as possible.
*/
void ref_transaction_free(struct ref_transaction *transaction);
-/** Lock a ref and then write its file */
-int update_ref(const char *action, const char *refname,
- const unsigned char *sha1, const unsigned char *oldval,
+/**
+ * Lock, update, and unlock a single reference. This function
+ * basically does a transaction containing a single call to
+ * ref_transaction_update(). The parameters to this function have the
+ * same meaning as the corresponding parameters to
+ * ref_transaction_update(). Handle errors as requested by the `onerr`
+ * argument.
+ */
+int update_ref(const char *msg, const char *refname,
+ const unsigned char *new_sha1, const unsigned char *old_sha1,
unsigned int flags, enum action_on_err onerr);
extern int parse_hide_refs_config(const char *var, const char *value, const char *);