From: Michael Haggerty <mhagger@alum.mit.edu>
To: Junio C Hamano <gitster@pobox.com>
Cc: Eric Sunshine <sunshine@sunshineco.com>,
git@vger.kernel.org, Michael Haggerty <mhagger@alum.mit.edu>
Subject: [PATCH 5/7] refs: tidy up and adjust visibility of the `ref_update` flags
Date: Sat, 28 Oct 2017 11:49:54 +0200 [thread overview]
Message-ID: <da4974c47a7fd72e41513218e0c824d4d6377b8c.1509183413.git.mhagger@alum.mit.edu> (raw)
In-Reply-To: <cover.1509183413.git.mhagger@alum.mit.edu>
The constants used for `ref_update::flags` were rather disorganized:
* The definitions in `refs.h` were not close to the functions that
used them.
* Maybe constants were defined in `refs-internal.h`, making them
visible to the whole refs module, when in fact they only made sense
for the files backend.
* The documentation wasn't very consistent and partly still referred
to sha1s rather than oids.
* The numerical values followed no rational scheme
Fix all of these problems. The main functional improvement is that
some constants' visibility is now limited to `files-backend.c`.
Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
---
refs.h | 65 +++++++++++++++++++++++++++++---------------------
refs/files-backend.c | 45 +++++++++++++++++++++++++++++++++++
refs/refs-internal.h | 67 ++++++++++++----------------------------------------
3 files changed, 98 insertions(+), 79 deletions(-)
diff --git a/refs.h b/refs.h
index 4ffef9502d..7dc022a809 100644
--- a/refs.h
+++ b/refs.h
@@ -335,22 +335,6 @@ void warn_dangling_symrefs(FILE *fp, const char *msg_fmt,
*/
int refs_pack_refs(struct ref_store *refs, unsigned int flags);
-/*
- * Flags controlling ref_transaction_update(), ref_transaction_create(), etc.
- * REF_NODEREF: act on the ref directly, instead of dereferencing
- * symbolic references.
- *
- * Other flags are reserved for internal use.
- */
-#define REF_NODEREF 0x01
-#define REF_FORCE_CREATE_REFLOG 0x40
-
-/*
- * Flags that can be passed in to ref_transaction_update
- */
-#define REF_TRANSACTION_UPDATE_ALLOWED_FLAGS \
- (REF_NODEREF | REF_FORCE_CREATE_REFLOG)
-
/*
* Setup reflog before using. Fill in err and return -1 on failure.
*/
@@ -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
* the update. Some functions allow this parameter to be NULL,
* meaning that the old value of the reference is not checked,
- * or null_sha1, meaning that the reference must not exist
+ * or null_oid, meaning that the reference must not exist
* before the update. A copy of this value is made in the
* transaction.
*
* flags -- flags affecting the update, passed to
- * update_ref_lock(). Can be REF_NODEREF, which means that
- * symbolic references should not be followed.
+ * update_ref_lock(). Possible flags: REF_NODEREF,
+ * REF_FORCE_CREATE_REFLOG. See those constants for more
+ * information.
*
* msg -- a message describing the change (for the reflog).
*
@@ -509,11 +494,37 @@ struct ref_transaction *ref_transaction_begin(struct strbuf *err);
*/
/*
- * Add a reference update to transaction. new_oid is the value that
- * the reference should have after the update, or null_oid if it
- * should be deleted. If new_oid is NULL, then the reference is not
- * changed at all. old_oid is the value that the reference must have
- * before the update, or null_oid if it must not have existed
+ * The following flags can be passed to ref_transaction_update() etc.
+ * Internally, they are stored in `ref_update::flags`, along with some
+ * internal flags.
+ */
+
+/*
+ * Act on the ref directly; i.e., without dereferencing symbolic refs.
+ * If this flag is not specified, then symbolic references are
+ * dereferenced and the update is applied to the referent.
+ */
+#define REF_NODEREF (1 << 0)
+
+/*
+ * Force the creation of a reflog for this reference, even if it
+ * didn't previously have a reflog.
+ */
+#define REF_FORCE_CREATE_REFLOG (1 << 1)
+
+/*
+ * Bitmask of all of the flags that are allowed to be passed in to
+ * ref_transaction_update() and friends:
+ */
+#define REF_TRANSACTION_UPDATE_ALLOWED_FLAGS \
+ (REF_NODEREF | REF_FORCE_CREATE_REFLOG)
+
+/*
+ * Add a reference update to transaction. `new_oid` is the value that
+ * the reference should have after the update, or `null_oid` if it
+ * should be deleted. If `new_oid` is NULL, then the reference is not
+ * changed at all. `old_oid` is the value that the reference must have
+ * before the update, or `null_oid` 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_oid, the
* whole transaction fails. If old_oid is NULL, then the previous
diff --git a/refs/files-backend.c b/refs/files-backend.c
index a47771e4d4..bbeafe1db7 100644
--- a/refs/files-backend.c
+++ b/refs/files-backend.c
@@ -10,6 +10,51 @@
#include "../object.h"
#include "../dir.h"
+/*
+ * This backend uses the following flags in `ref_update::flags` for
+ * internal bookkeeping purposes. Their numerical values must not
+ * conflict with REF_NODEREF, REF_FORCE_CREATE_REFLOG, REF_HAVE_NEW,
+ * REF_HAVE_OLD, or REF_ISPRUNING, which are also stored in
+ * `ref_update::flags`.
+ */
+
+/*
+ * Used as a flag in ref_update::flags when a loose ref is being
+ * pruned. This flag must only be used when REF_NODEREF is set.
+ */
+#define REF_ISPRUNING (1 << 4)
+
+/*
+ * Flag passed to lock_ref_sha1_basic() telling it to tolerate broken
+ * refs (i.e., because the reference is about to be deleted anyway).
+ */
+#define REF_DELETING (1 << 5)
+
+/*
+ * Used as a flag in ref_update::flags when the lockfile needs to be
+ * committed.
+ */
+#define REF_NEEDS_COMMIT (1 << 6)
+
+/*
+ * Used as a flag in ref_update::flags when we want to log a ref
+ * update but not actually perform it. This is used when a symbolic
+ * ref update is split up.
+ */
+#define REF_LOG_ONLY (1 << 7)
+
+/*
+ * Used as a flag in ref_update::flags when the ref_update was via an
+ * update to HEAD.
+ */
+#define REF_UPDATE_VIA_HEAD (1 << 8)
+
+/*
+ * Used as a flag in ref_update::flags when the loose reference has
+ * been deleted.
+ */
+#define REF_DELETED_LOOSE (1 << 9)
+
struct ref_lock {
char *ref_name;
struct lock_file lk;
diff --git a/refs/refs-internal.h b/refs/refs-internal.h
index b0f3e300c7..2ea02dcbe4 100644
--- a/refs/refs-internal.h
+++ b/refs/refs-internal.h
@@ -8,58 +8,22 @@
*/
/*
- * Flag passed to lock_ref_sha1_basic() telling it to tolerate broken
- * refs (i.e., because the reference is about to be deleted anyway).
+ * The following flags can appear in `ref_update::flags`. Their
+ * numerical values must not conflict with those of REF_NODEREF and
+ * REF_FORCE_CREATE_REFLOG, which are also stored in
+ * `ref_update::flags`.
*/
-#define REF_DELETING 0x02
/*
- * Used as a flag in ref_update::flags when a loose ref is being
- * pruned. This flag must only be used when REF_NODEREF is set.
+ * The reference should be updated to new_sha1.
*/
-#define REF_ISPRUNING 0x04
+#define REF_HAVE_NEW (1 << 2)
/*
- * Used as a flag in ref_update::flags when the reference should be
- * updated to new_sha1.
+ * The current reference's value should be checked to make sure that
+ * it agrees with old_sha1.
*/
-#define REF_HAVE_NEW 0x08
-
-/*
- * Used as a flag in ref_update::flags when old_sha1 should be
- * checked.
- */
-#define REF_HAVE_OLD 0x10
-
-/*
- * Used as a flag in ref_update::flags when the lockfile needs to be
- * committed.
- */
-#define REF_NEEDS_COMMIT 0x20
-
-/*
- * 0x40 is REF_FORCE_CREATE_REFLOG, so skip it if you're adding a
- * value to ref_update::flags
- */
-
-/*
- * Used as a flag in ref_update::flags when we want to log a ref
- * update but not actually perform it. This is used when a symbolic
- * ref update is split up.
- */
-#define REF_LOG_ONLY 0x80
-
-/*
- * Internal flag, meaning that the containing ref_update was via an
- * update to HEAD.
- */
-#define REF_UPDATE_VIA_HEAD 0x100
-
-/*
- * Used as a flag in ref_update::flags when the loose reference has
- * been deleted.
- */
-#define REF_DELETED_LOOSE 0x200
+#define REF_HAVE_OLD (1 << 3)
/*
* Return the length of time to retry acquiring a loose reference lock
@@ -141,23 +105,22 @@ int copy_reflog_msg(char *buf, const char *msg);
* not exist before update.
*/
struct ref_update {
-
/*
- * If (flags & REF_HAVE_NEW), set the reference to this value:
+ * If (flags & REF_HAVE_NEW), set the reference to this value
+ * (or delete it, if `new_oid` is `null_oid`).
*/
struct object_id new_oid;
/*
* If (flags & REF_HAVE_OLD), check that the reference
- * previously had this value:
+ * previously had this value (or didn't previously exist, if
+ * `old_oid` is `null_oid`).
*/
struct object_id old_oid;
/*
- * One or more of REF_HAVE_NEW, REF_HAVE_OLD, REF_NODEREF,
- * REF_DELETING, REF_ISPRUNING, REF_LOG_ONLY,
- * REF_UPDATE_VIA_HEAD, REF_NEEDS_COMMIT, and
- * REF_DELETED_LOOSE:
+ * One or more of REF_NODEREF, REF_FORCE_CREATE_REFLOG,
+ * REF_HAVE_NEW, REF_HAVE_OLD, or backend-specific flags.
*/
unsigned int flags;
--
2.14.1
next prev parent reply other threads:[~2017-10-28 9:50 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-10-28 9:49 [PATCH 0/7] Tidy up the constants related to ref_update::flags Michael Haggerty
2017-10-28 9:49 ` [PATCH 1/7] files_transaction_prepare(): don't leak flags to packed transaction Michael Haggerty
2017-10-30 4:44 ` Junio C Hamano
2017-11-05 6:46 ` Michael Haggerty
2017-11-06 1:28 ` Junio C Hamano
2017-10-28 9:49 ` [PATCH 2/7] prune_ref(): call `ref_transaction_add_update()` directly Michael Haggerty
2017-10-28 9:49 ` [PATCH 3/7] ref_transaction_update(): die on disallowed flags Michael Haggerty
2017-10-28 9:49 ` [PATCH 4/7] ref_transaction_add_update(): remove a check Michael Haggerty
2017-10-28 9:49 ` Michael Haggerty [this message]
2017-11-01 8:18 ` [PATCH 5/7] refs: tidy up and adjust visibility of the `ref_update` flags Martin Ågren
2017-11-05 7:19 ` Michael Haggerty
2017-10-28 9:49 ` [PATCH 6/7] refs: rename constant `REF_NODEREF` to `REF_NO_DEREF` Michael Haggerty
2017-10-30 4:56 ` Junio C Hamano
2017-10-28 9:49 ` [PATCH 7/7] refs: rename constant `REF_ISPRUNING` to `REF_IS_PRUNING` Michael Haggerty
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=da4974c47a7fd72e41513218e0c824d4d6377b8c.1509183413.git.mhagger@alum.mit.edu \
--to=mhagger@alum.mit.edu \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=sunshine@sunshineco.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).