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 */