update_ref(): improve documentation
Add a docstring for update_ref(), emphasizing its similarity to ref_transaction_update(). Rename its parameters to match those of ref_transaction_update(). Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Reviewed-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Michael Haggerty committed
Feb 17, 2015 at 18:00 UTC
4b7b520b9f761704400a82285d0812fd9e50957f
2 files changed
+14
-7
refs.c
+4
-4
@@ -3738,8 +3738,8 @@ int ref_transaction_verify(struct ref_transaction *transaction,
3738
flags, NULL, err);
3739
}
3740
3741
-int update_ref(const char *action, const char *refname,
3742
- const unsigned char *sha1, const unsigned char *oldval,
3741
+int update_ref(const char *msg, const char *refname,
3742
+ const unsigned char *new_sha1, const unsigned char *old_sha1,
3743
unsigned int flags, enum action_on_err onerr)
3744
{
3745
struct ref_transaction *t;
@@ -3747,8 +3747,8 @@ int update_ref(const char *action, const char *refname,
3747
3748
t = ref_transaction_begin(&err);
3749
if (!t ||
3750
- ref_transaction_update(t, refname, sha1, oldval,
3751
- flags, action, &err) ||
3750
+ ref_transaction_update(t, refname, new_sha1, old_sha1,
3751
+ flags, msg, &err) ||
3752
ref_transaction_commit(t, &err)) {
3753
const char *str = "update_ref failed for ref '%s': %s";
3754
refs.h
+10
-3
@@ -344,9 +344,16 @@ int ref_transaction_commit(struct ref_transaction *transaction,
344
*/
345
void ref_transaction_free(struct ref_transaction *transaction);
346
347
-/** Lock a ref and then write its file */
348
-int update_ref(const char *action, const char *refname,
349
- const unsigned char *sha1, const unsigned char *oldval,
347
+/**
348
+ * Lock, update, and unlock a single reference. This function
349
+ * basically does a transaction containing a single call to
350
+ * ref_transaction_update(). The parameters to this function have the
351
+ * same meaning as the corresponding parameters to
352
+ * ref_transaction_update(). Handle errors as requested by the `onerr`
353
+ * argument.
354
+ */
355
+int update_ref(const char *msg, const char *refname,
356
+ const unsigned char *new_sha1, const unsigned char *old_sha1,
357
unsigned int flags, enum action_on_err onerr);
358
359
extern int parse_hide_refs_config(const char *var, const char *value, const char *);