refs / ref-cache.hon commit read_packed_refs(): make parsing of the header line more robust (a881169)
   1#ifndef REFS_REF_CACHE_H
   2#define REFS_REF_CACHE_H
   3
   4struct ref_dir;
   5
   6/*
   7 * If this ref_cache is filled lazily, this function is used to load
   8 * information into the specified ref_dir (shallow or deep, at the
   9 * option of the ref_store). dirname includes a trailing slash.
  10 */
  11typedef void fill_ref_dir_fn(struct ref_store *ref_store,
  12                             struct ref_dir *dir, const char *dirname);
  13
  14struct ref_cache {
  15        struct ref_entry *root;
  16
  17        /* A pointer to the ref_store whose cache this is: */
  18        struct ref_store *ref_store;
  19
  20        /*
  21         * Function used (if necessary) to lazily-fill cache. May be
  22         * NULL.
  23         */
  24        fill_ref_dir_fn *fill_ref_dir;
  25};
  26
  27/*
  28 * Information used (along with the information in ref_entry) to
  29 * describe a single cached reference.  This data structure only
  30 * occurs embedded in a union in struct ref_entry, and only when
  31 * (ref_entry->flag & REF_DIR) is zero.
  32 */
  33struct ref_value {
  34        /*
  35         * The name of the object to which this reference resolves
  36         * (which may be a tag object).  If REF_ISBROKEN, this is
  37         * null.  If REF_ISSYMREF, then this is the name of the object
  38         * referred to by the last reference in the symlink chain.
  39         */
  40        struct object_id oid;
  41
  42        /*
  43         * If REF_KNOWS_PEELED, then this field holds the peeled value
  44         * of this reference, or null if the reference is known not to
  45         * be peelable.  See the documentation for peel_ref() for an
  46         * exact definition of "peelable".
  47         */
  48        struct object_id peeled;
  49};
  50
  51/*
  52 * Information used (along with the information in ref_entry) to
  53 * describe a level in the hierarchy of references.  This data
  54 * structure only occurs embedded in a union in struct ref_entry, and
  55 * only when (ref_entry.flag & REF_DIR) is set.  In that case,
  56 * (ref_entry.flag & REF_INCOMPLETE) determines whether the references
  57 * in the directory have already been read:
  58 *
  59 *     (ref_entry.flag & REF_INCOMPLETE) unset -- a directory of loose
  60 *         or packed references, already read.
  61 *
  62 *     (ref_entry.flag & REF_INCOMPLETE) set -- a directory of loose
  63 *         references that hasn't been read yet (nor has any of its
  64 *         subdirectories).
  65 *
  66 * Entries within a directory are stored within a growable array of
  67 * pointers to ref_entries (entries, nr, alloc).  Entries 0 <= i <
  68 * sorted are sorted by their component name in strcmp() order and the
  69 * remaining entries are unsorted.
  70 *
  71 * Loose references are read lazily, one directory at a time.  When a
  72 * directory of loose references is read, then all of the references
  73 * in that directory are stored, and REF_INCOMPLETE stubs are created
  74 * for any subdirectories, but the subdirectories themselves are not
  75 * read.  The reading is triggered by get_ref_dir().
  76 */
  77struct ref_dir {
  78        int nr, alloc;
  79
  80        /*
  81         * Entries with index 0 <= i < sorted are sorted by name.  New
  82         * entries are appended to the list unsorted, and are sorted
  83         * only when required; thus we avoid the need to sort the list
  84         * after the addition of every reference.
  85         */
  86        int sorted;
  87
  88        /* The ref_cache containing this entry: */
  89        struct ref_cache *cache;
  90
  91        struct ref_entry **entries;
  92};
  93
  94/*
  95 * Bit values for ref_entry::flag.  REF_ISSYMREF=0x01,
  96 * REF_ISPACKED=0x02, REF_ISBROKEN=0x04 and REF_BAD_NAME=0x08 are
  97 * public values; see refs.h.
  98 */
  99
 100/*
 101 * The field ref_entry->u.value.peeled of this value entry contains
 102 * the correct peeled value for the reference, which might be
 103 * null_sha1 if the reference is not a tag or if it is broken.
 104 */
 105#define REF_KNOWS_PEELED 0x10
 106
 107/* ref_entry represents a directory of references */
 108#define REF_DIR 0x20
 109
 110/*
 111 * Entry has not yet been read from disk (used only for REF_DIR
 112 * entries representing loose references)
 113 */
 114#define REF_INCOMPLETE 0x40
 115
 116/*
 117 * A ref_entry represents either a reference or a "subdirectory" of
 118 * references.
 119 *
 120 * Each directory in the reference namespace is represented by a
 121 * ref_entry with (flags & REF_DIR) set and containing a subdir member
 122 * that holds the entries in that directory that have been read so
 123 * far.  If (flags & REF_INCOMPLETE) is set, then the directory and
 124 * its subdirectories haven't been read yet.  REF_INCOMPLETE is only
 125 * used for loose reference directories.
 126 *
 127 * References are represented by a ref_entry with (flags & REF_DIR)
 128 * unset and a value member that describes the reference's value.  The
 129 * flag member is at the ref_entry level, but it is also needed to
 130 * interpret the contents of the value field (in other words, a
 131 * ref_value object is not very much use without the enclosing
 132 * ref_entry).
 133 *
 134 * Reference names cannot end with slash and directories' names are
 135 * always stored with a trailing slash (except for the top-level
 136 * directory, which is always denoted by "").  This has two nice
 137 * consequences: (1) when the entries in each subdir are sorted
 138 * lexicographically by name (as they usually are), the references in
 139 * a whole tree can be generated in lexicographic order by traversing
 140 * the tree in left-to-right, depth-first order; (2) the names of
 141 * references and subdirectories cannot conflict, and therefore the
 142 * presence of an empty subdirectory does not block the creation of a
 143 * similarly-named reference.  (The fact that reference names with the
 144 * same leading components can conflict *with each other* is a
 145 * separate issue that is regulated by refs_verify_refname_available().)
 146 *
 147 * Please note that the name field contains the fully-qualified
 148 * reference (or subdirectory) name.  Space could be saved by only
 149 * storing the relative names.  But that would require the full names
 150 * to be generated on the fly when iterating in do_for_each_ref(), and
 151 * would break callback functions, who have always been able to assume
 152 * that the name strings that they are passed will not be freed during
 153 * the iteration.
 154 */
 155struct ref_entry {
 156        unsigned char flag; /* ISSYMREF? ISPACKED? */
 157        union {
 158                struct ref_value value; /* if not (flags&REF_DIR) */
 159                struct ref_dir subdir; /* if (flags&REF_DIR) */
 160        } u;
 161        /*
 162         * The full name of the reference (e.g., "refs/heads/master")
 163         * or the full name of the directory with a trailing slash
 164         * (e.g., "refs/heads/"):
 165         */
 166        char name[FLEX_ARRAY];
 167};
 168
 169/*
 170 * Return the index of the entry with the given refname from the
 171 * ref_dir (non-recursively), sorting dir if necessary.  Return -1 if
 172 * no such entry is found.  dir must already be complete.
 173 */
 174int search_ref_dir(struct ref_dir *dir, const char *refname, size_t len);
 175
 176struct ref_dir *get_ref_dir(struct ref_entry *entry);
 177
 178/*
 179 * Create a struct ref_entry object for the specified dirname.
 180 * dirname is the name of the directory with a trailing slash (e.g.,
 181 * "refs/heads/") or "" for the top-level directory.
 182 */
 183struct ref_entry *create_dir_entry(struct ref_cache *cache,
 184                                   const char *dirname, size_t len,
 185                                   int incomplete);
 186
 187struct ref_entry *create_ref_entry(const char *refname,
 188                                   const struct object_id *oid, int flag);
 189
 190/*
 191 * Return a pointer to a new `ref_cache`. Its top-level starts out
 192 * marked incomplete. If `fill_ref_dir` is non-NULL, it is the
 193 * function called to fill in incomplete directories in the
 194 * `ref_cache` when they are accessed. If it is NULL, then the whole
 195 * `ref_cache` must be filled (including clearing its directories'
 196 * `REF_INCOMPLETE` bits) before it is used, and `refs` can be NULL,
 197 * too.
 198 */
 199struct ref_cache *create_ref_cache(struct ref_store *refs,
 200                                   fill_ref_dir_fn *fill_ref_dir);
 201
 202/*
 203 * Free the `ref_cache` and all of its associated data.
 204 */
 205void free_ref_cache(struct ref_cache *cache);
 206
 207/*
 208 * Add a ref_entry to the end of dir (unsorted).  Entry is always
 209 * stored directly in dir; no recursion into subdirectories is
 210 * done.
 211 */
 212void add_entry_to_dir(struct ref_dir *dir, struct ref_entry *entry);
 213
 214/*
 215 * Remove the entry with the given name from dir, recursing into
 216 * subdirectories as necessary.  If refname is the name of a directory
 217 * (i.e., ends with '/'), then remove the directory and its contents.
 218 * If the removal was successful, return the number of entries
 219 * remaining in the directory entry that contained the deleted entry.
 220 * If the name was not found, return -1.  Please note that this
 221 * function only deletes the entry from the cache; it does not delete
 222 * it from the filesystem or ensure that other cache entries (which
 223 * might be symbolic references to the removed entry) are updated.
 224 * Nor does it remove any containing dir entries that might be made
 225 * empty by the removal.  dir must represent the top-level directory
 226 * and must already be complete.
 227 */
 228int remove_entry_from_dir(struct ref_dir *dir, const char *refname);
 229
 230/*
 231 * Add a ref_entry to the ref_dir (unsorted), recursing into
 232 * subdirectories as necessary.  dir must represent the top-level
 233 * directory.  Return 0 on success.
 234 */
 235int add_ref_entry(struct ref_dir *dir, struct ref_entry *ref);
 236
 237/*
 238 * Find the value entry with the given name in dir, sorting ref_dirs
 239 * and recursing into subdirectories as necessary.  If the name is not
 240 * found or it corresponds to a directory entry, return NULL.
 241 */
 242struct ref_entry *find_ref_entry(struct ref_dir *dir, const char *refname);
 243
 244/*
 245 * Start iterating over references in `cache`. If `prefix` is
 246 * specified, only include references whose names start with that
 247 * prefix. If `prime_dir` is true, then fill any incomplete
 248 * directories before beginning the iteration. The output is ordered
 249 * by refname.
 250 */
 251struct ref_iterator *cache_ref_iterator_begin(struct ref_cache *cache,
 252                                              const char *prefix,
 253                                              int prime_dir);
 254
 255/*
 256 * Peel the entry (if possible) and return its new peel_status.  If
 257 * repeel is true, re-peel the entry even if there is an old peeled
 258 * value that is already stored in it.
 259 *
 260 * It is OK to call this function with a packed reference entry that
 261 * might be stale and might even refer to an object that has since
 262 * been garbage-collected.  In such a case, if the entry has
 263 * REF_KNOWS_PEELED then leave the status unchanged and return
 264 * PEEL_PEELED or PEEL_NON_TAG; otherwise, return PEEL_INVALID.
 265 */
 266enum peel_status peel_entry(struct ref_entry *entry, int repeel);
 267
 268#endif /* REFS_REF_CACHE_H */