get_loose_ref_cache(): new function
[git/git.git] / refs / ref-cache.h
CommitLineData
958f9646
MH
1#ifndef REFS_REF_CACHE_H
2#define REFS_REF_CACHE_H
3
df308759
MH
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
7c22bc8a
MH
14struct ref_cache {
15 struct ref_entry *root;
e00d1a4f 16
df308759
MH
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;
7c22bc8a
MH
25};
26
958f9646
MH
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
e00d1a4f
MH
88 /* The ref_cache containing this entry: */
89 struct ref_cache *cache;
958f9646
MH
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 */
e00d1a4f 183struct ref_entry *create_dir_entry(struct ref_cache *cache,
958f9646
MH
184 const char *dirname, size_t len,
185 int incomplete);
186
187struct ref_entry *create_ref_entry(const char *refname,
188 const unsigned char *sha1, int flag,
189 int check_name);
190
7c22bc8a
MH
191/*
192 * Return a pointer to a new `ref_cache`. Its top-level starts out
df308759
MH
193 * marked incomplete. If `fill_ref_dir` is non-NULL, it is the
194 * function called to fill in incomplete directories in the
195 * `ref_cache` when they are accessed. If it is NULL, then the whole
196 * `ref_cache` must be filled (including clearing its directories'
197 * `REF_INCOMPLETE` bits) before it is used.
7c22bc8a 198 */
df308759
MH
199struct ref_cache *create_ref_cache(struct ref_store *refs,
200 fill_ref_dir_fn *fill_ref_dir);
7c22bc8a
MH
201
202/*
203 * Free the `ref_cache` and all of its associated data.
204 */
205void free_ref_cache(struct ref_cache *cache);
958f9646
MH
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 * If refname is a reference name, find the ref_dir within the dir
239 * tree that should hold refname. If refname is a directory name
240 * (i.e., it ends in '/'), then return that ref_dir itself. dir must
241 * represent the top-level directory and must already be complete.
242 * Sort ref_dirs and recurse into subdirectories as necessary. If
243 * mkdir is set, then create any missing directories; otherwise,
244 * return NULL if the desired directory cannot be found.
245 */
246struct ref_dir *find_containing_dir(struct ref_dir *dir,
247 const char *refname, int mkdir);
248
249/*
250 * Find the value entry with the given name in dir, sorting ref_dirs
251 * and recursing into subdirectories as necessary. If the name is not
252 * found or it corresponds to a directory entry, return NULL.
253 */
254struct ref_entry *find_ref_entry(struct ref_dir *dir, const char *refname);
255
256struct ref_iterator *cache_ref_iterator_begin(struct ref_dir *dir);
257
258typedef int each_ref_entry_fn(struct ref_entry *entry, void *cb_data);
259
260/*
5c7bba77
MH
261 * Call `fn` for each reference in `dir`. Recurse into subdirectories,
262 * sorting them before iterating. This function does not sort `dir`
263 * itself; it should be sorted beforehand. `fn` is called for all
264 * references, including broken ones.
958f9646 265 */
5c7bba77 266int do_for_each_entry_in_dir(struct ref_dir *dir,
958f9646
MH
267 each_ref_entry_fn fn, void *cb_data);
268
269/*
270 * Peel the entry (if possible) and return its new peel_status. If
271 * repeel is true, re-peel the entry even if there is an old peeled
272 * value that is already stored in it.
273 *
274 * It is OK to call this function with a packed reference entry that
275 * might be stale and might even refer to an object that has since
276 * been garbage-collected. In such a case, if the entry has
277 * REF_KNOWS_PEELED then leave the status unchanged and return
278 * PEEL_PEELED or PEEL_NON_TAG; otherwise, return PEEL_INVALID.
279 */
280enum peel_status peel_entry(struct ref_entry *entry, int repeel);
281
282/*
283 * Load all of the refs from `dir` into our in-memory cache.
284 */
285void prime_ref_dir(struct ref_dir *dir);
286
287#endif /* REFS_REF_CACHE_H */