refs: document the fields of struct ref_value
[gitweb.git] / refs.c
diff --git a/refs.c b/refs.c
index a465ff319c9ea78ce118ab0f98a965c9209324f4..ed1b4cf9b6140685a55d47fd8abc3526295307f3 100644 (file)
--- a/refs.c
+++ b/refs.c
@@ -108,7 +108,19 @@ struct ref_entry;
  * (ref_entry->flag & REF_DIR) is zero.
  */
 struct ref_value {
+       /*
+        * The name of the object to which this reference resolves
+        * (which may be a tag object).  If REF_ISBROKEN, this is
+        * null.  If REF_ISSYMREF, then this is the name of the object
+        * referred to by the last reference in the symlink chain.
+        */
        unsigned char sha1[20];
+
+       /*
+        * If REF_KNOWS_PEELED, then this field holds the peeled value
+        * of this reference, or null if the reference is known not to
+        * be peelable.
+        */
        unsigned char peeled[20];
 };
 
@@ -157,7 +169,17 @@ struct ref_dir {
        struct ref_entry **entries;
 };
 
-/* ISSYMREF=0x01, ISPACKED=0x02, and ISBROKEN=0x04 are public interfaces */
+/*
+ * Bit values for ref_entry::flag.  REF_ISSYMREF=0x01,
+ * REF_ISPACKED=0x02, and REF_ISBROKEN=0x04 are public values; see
+ * refs.h.
+ */
+
+/*
+ * The field ref_entry->u.value.peeled of this value entry contains
+ * the correct peeled value for the reference, which might be
+ * null_sha1 if the reference is not a tag or if it is broken.
+ */
 #define REF_KNOWS_PEELED 0x08
 
 /* ref_entry represents a directory of references */
@@ -804,11 +826,38 @@ static const char *parse_ref_line(char *line, unsigned char *sha1)
        return line;
 }
 
+/*
+ * Read f, which is a packed-refs file, into dir.
+ *
+ * A comment line of the form "# pack-refs with: " may contain zero or
+ * more traits. We interpret the traits as follows:
+ *
+ *   No traits:
+ *
+ *      Probably no references are peeled. But if the file contains a
+ *      peeled value for a reference, we will use it.
+ *
+ *   peeled:
+ *
+ *      References under "refs/tags/", if they *can* be peeled, *are*
+ *      peeled in this file. References outside of "refs/tags/" are
+ *      probably not peeled even if they could have been, but if we find
+ *      a peeled value for such a reference we will use it.
+ *
+ *   fully-peeled:
+ *
+ *      All references in the file that can be peeled are peeled.
+ *      Inversely (and this is more important), any references in the
+ *      file for which no peeled value is recorded is not peelable. This
+ *      trait should typically be written alongside "peeled" for
+ *      compatibility with older clients, but we do not require it
+ *      (i.e., "peeled" is a no-op if "fully-peeled" is set).
+ */
 static void read_packed_refs(FILE *f, struct ref_dir *dir)
 {
        struct ref_entry *last = NULL;
        char refline[PATH_MAX];
-       int flag = REF_ISPACKED;
+       enum { PEELED_NONE, PEELED_TAGS, PEELED_FULLY } peeled = PEELED_NONE;
 
        while (fgets(refline, sizeof(refline), f)) {
                unsigned char sha1[20];
@@ -817,15 +866,20 @@ static void read_packed_refs(FILE *f, struct ref_dir *dir)
 
                if (!strncmp(refline, header, sizeof(header)-1)) {
                        const char *traits = refline + sizeof(header) - 1;
-                       if (strstr(traits, " peeled "))
-                               flag |= REF_KNOWS_PEELED;
+                       if (strstr(traits, " fully-peeled "))
+                               peeled = PEELED_FULLY;
+                       else if (strstr(traits, " peeled "))
+                               peeled = PEELED_TAGS;
                        /* perhaps other traits later as well */
                        continue;
                }
 
                refname = parse_ref_line(refline, sha1);
                if (refname) {
-                       last = create_ref_entry(refname, sha1, flag, 1);
+                       last = create_ref_entry(refname, sha1, REF_ISPACKED, 1);
+                       if (peeled == PEELED_FULLY ||
+                           (peeled == PEELED_TAGS && !prefixcmp(refname, "refs/tags/")))
+                               last->flag |= REF_KNOWS_PEELED;
                        add_ref(dir, last);
                        continue;
                }
@@ -833,8 +887,15 @@ static void read_packed_refs(FILE *f, struct ref_dir *dir)
                    refline[0] == '^' &&
                    strlen(refline) == 42 &&
                    refline[41] == '\n' &&
-                   !get_sha1_hex(refline + 1, sha1))
+                   !get_sha1_hex(refline + 1, sha1)) {
                        hashcpy(last->u.value.peeled, sha1);
+                       /*
+                        * Regardless of what the file header said,
+                        * we definitely know the value of *this*
+                        * reference:
+                        */
+                       last->flag |= REF_KNOWS_PEELED;
+               }
        }
 }
 
@@ -1202,6 +1263,8 @@ int peel_ref(const char *refname, unsigned char *sha1)
        if (current_ref && (current_ref->name == refname
                || !strcmp(current_ref->name, refname))) {
                if (current_ref->flag & REF_KNOWS_PEELED) {
+                       if (is_null_sha1(current_ref->u.value.peeled))
+                           return -1;
                        hashcpy(sha1, current_ref->u.value.peeled);
                        return 0;
                }
@@ -1223,9 +1286,16 @@ int peel_ref(const char *refname, unsigned char *sha1)
        }
 
 fallback:
-       o = parse_object(base);
-       if (o && o->type == OBJ_TAG) {
-               o = deref_tag(o, refname, 0);
+       o = lookup_unknown_object(base);
+       if (o->type == OBJ_NONE) {
+               int type = sha1_object_info(base, NULL);
+               if (type < 0)
+                       return -1;
+               o->type = type;
+       }
+
+       if (o->type == OBJ_TAG) {
+               o = deref_tag_noverify(o);
                if (o) {
                        hashcpy(sha1, o->sha1);
                        return 0;
@@ -1756,32 +1826,24 @@ int delete_ref(const char *refname, const unsigned char *sha1, int delopt)
        struct ref_lock *lock;
        int err, i = 0, ret = 0, flag = 0;
 
-       lock = lock_ref_sha1_basic(refname, sha1, 0, &flag);
+       lock = lock_ref_sha1_basic(refname, sha1, delopt, &flag);
        if (!lock)
                return 1;
        if (!(flag & REF_ISPACKED) || flag & REF_ISSYMREF) {
                /* loose */
-               const char *path;
-
-               if (!(delopt & REF_NODEREF)) {
-                       i = strlen(lock->lk->filename) - 5; /* .lock */
-                       lock->lk->filename[i] = 0;
-                       path = lock->lk->filename;
-               } else {
-                       path = git_path("%s", refname);
-               }
-               err = unlink_or_warn(path);
+               i = strlen(lock->lk->filename) - 5; /* .lock */
+               lock->lk->filename[i] = 0;
+               err = unlink_or_warn(lock->lk->filename);
                if (err && errno != ENOENT)
                        ret = 1;
 
-               if (!(delopt & REF_NODEREF))
-                       lock->lk->filename[i] = '.';
+               lock->lk->filename[i] = '.';
        }
        /* removing the loose one could have resurrected an earlier
         * packed one.  Also, if it was not loose we need to repack
         * without it.
         */
-       ret |= repack_without_ref(refname);
+       ret |= repack_without_ref(lock->ref_name);
 
        unlink_or_warn(git_path("logs/%s", lock->ref_name));
        invalidate_ref_cache(NULL);