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