Re: [PATCH 5/7] refs: tidy up and adjust visibility of the `ref_update` flags

From

MÅMartin Ågren <martin.agren@gmail.com>

Date

Nov 1, 2017, 08:18 UTC

Message-ID

<20171101081808.5962-1-martin.agren@gmail.com>

In-Reply-To

<da4974c47a7fd72e41513218e0c824d4d6377b8c.1509183413.git.mhagger@alum.mit.edu>

On 28 October 2017 at 11:49, Michael Haggerty <mhagger@alum.mit.edu> wrote:

> The constants used for `ref_update::flags` were rather disorganized:

> * The documentation wasn't very consistent and partly still referred
>   to sha1s rather than oids.

> @@ -478,22 +462,23 @@ struct ref_transaction *ref_transaction_begin(struct strbuf *err);
>   *
>   *     refname -- the name of the reference to be affected.
>   *
> - *     new_sha1 -- the SHA-1 that should be set to be the new value of
> + *     new_oid -- the SHA-1 that should be set to be the new value of
>   *         the reference. Some functions allow this parameter to be
>   *         NULL, meaning that the reference is not changed, or
> - *         null_sha1, meaning that the reference should be deleted. A
> + *         null_oid, meaning that the reference should be deleted. A
>   *         copy of this value is made in the transaction.
>   *
> - *     old_sha1 -- the SHA-1 value that the reference must have before
> + *     old_oid -- the SHA-1 value that the reference must have before

Martin

-- >8 --

diff --git a/refs.h b/refs.h
index f0958e5bf..18582a408 100644
--- a/refs.h
+++ b/refs.h
@@ -126,7 +126,7 @@ int peel_ref(const char *refname, struct object_id *oid);
 /**
  * Resolve refname in the nested "gitlink" repository in the specified
  * submodule (which must be non-NULL). If the resolution is
- * successful, return 0 and set sha1 to the name of the object;
+ * successful, return 0 and set oid to the name of the object;
  * otherwise, return a non-zero value.
  */
 int resolve_gitlink_ref(const char *submodule, const char *refname,
@@ -260,7 +260,7 @@ struct ref_transaction;
 
 /*
  * The signature for the callback function for the for_each_*()
- * functions below.  The memory pointed to by the refname and sha1
+ * functions below.  The memory pointed to by the refname and oid
  * arguments is only guaranteed to be valid for the duration of a
  * single callback invocation.
  */
@@ -354,7 +354,7 @@ int reflog_exists(const char *refname);
 
 /*
  * Delete the specified reference. If old_oid is non-NULL, then
- * verify that the current value of the reference is old_sha1 before
+ * verify that the current value of the reference is old_oid before
  * deleting it. If old_oid is NULL, delete the reference if it
  * exists, regardless of its old value. It is an error for old_oid to
  * be null_oid. msg and flags are passed through to
@@ -462,13 +462,13 @@ struct ref_transaction *ref_transaction_begin(struct strbuf *err);
  *
  *     refname -- the name of the reference to be affected.
  *
- *     new_oid -- the SHA-1 that should be set to be the new value of
- *         the reference. Some functions allow this parameter to be
+ *     new_oid -- the object ID that should be set to be the new value
+ *         of the reference. Some functions allow this parameter to be
  *         NULL, meaning that the reference is not changed, or
  *         null_oid, meaning that the reference should be deleted. A
  *         copy of this value is made in the transaction.
  *
- *     old_oid -- the SHA-1 value that the reference must have before
+ *     old_oid -- the object ID that the reference must have before
  *         the update. Some functions allow this parameter to be NULL,
  *         meaning that the old value of the reference is not checked,
  *         or null_oid, meaning that the reference must not exist
@@ -633,7 +633,7 @@ int ref_transaction_abort(struct ref_transaction *transaction,
  * It is a bug to call this function when there might be other
  * processes accessing the repository or if there are existing
  * references that might conflict with the ones being created. All
- * old_sha1 values must either be absent or NULL_SHA1.
+ * old_oid values must either be absent or null_oid.
  */
 int initial_ref_transaction_commit(struct ref_transaction *transaction,
 				   struct strbuf *err);

-- 
2.15.0.415.gac1375d7e