Skip to content

Commit

Permalink
refs: tidy up and adjust visibility of the ref_update flags
Browse files Browse the repository at this point in the history 
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.

* Their 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 <[email protected]>
Signed-off-by: Junio C Hamano <[email protected]>
  • Loading branch information
@mhagger @gitster
mhagger authored and gitster committed Nov 6, 2017
1 parent 62c72d1 commit 5ac95fe
Show file tree
Hide file tree
Showing 3 changed files with 99 additions and 80 deletions.
67 changes: 39 additions & 28 deletions refs.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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
* 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_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 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_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).
*
Expand All @@ -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
Expand Down
45 changes: 45 additions & 0 deletions refs/files-backend.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
67 changes: 15 additions & 52 deletions refs/refs-internal.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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;

Expand Down

0 comments on commit 5ac95fe

Please sign in to comment.