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