freshlybakedca.ke
Git fork
1#ifndef REFS_H
2#define REFS_H
3
4#include "commit.h"
5#include "repository.h"
6#include "repo-settings.h"
7
8struct fsck_options;
9struct object_id;
10struct ref_store;
11struct strbuf;
12struct string_list;
13struct string_list_item;
14struct worktree;
15
16enum ref_storage_format ref_storage_format_by_name(const char *name);
17const char *ref_storage_format_to_name(enum ref_storage_format ref_storage_format);
18
19enum ref_transaction_error {
20 /* Default error code */
21 REF_TRANSACTION_ERROR_GENERIC = -1,
22 /* Ref name conflict like A vs A/B */
23 REF_TRANSACTION_ERROR_NAME_CONFLICT = -2,
24 /* Ref to be created already exists */
25 REF_TRANSACTION_ERROR_CREATE_EXISTS = -3,
26 /* ref expected but doesn't exist */
27 REF_TRANSACTION_ERROR_NONEXISTENT_REF = -4,
28 /* Provided old_oid or old_target of reference doesn't match actual */
29 REF_TRANSACTION_ERROR_INCORRECT_OLD_VALUE = -5,
30 /* Provided new_oid or new_target is invalid */
31 REF_TRANSACTION_ERROR_INVALID_NEW_VALUE = -6,
32 /* Expected ref to be symref, but is a regular ref */
33 REF_TRANSACTION_ERROR_EXPECTED_SYMREF = -7,
34 /* Cannot create ref due to case-insensitive filesystem */
35 REF_TRANSACTION_ERROR_CASE_CONFLICT = -8,
36};
37
38/*
39 * Resolve a reference, recursively following symbolic references.
40 *
41 * Return the name of the non-symbolic reference that ultimately pointed
42 * at the resolved object name. The return value, if not NULL, is a
43 * pointer into either a static buffer or the input ref.
44 *
45 * If oid is non-NULL, store the referred-to object's name in it.
46 *
47 * If the reference cannot be resolved to an object, the behavior
48 * depends on the RESOLVE_REF_READING flag:
49 *
50 * - If RESOLVE_REF_READING is set, return NULL.
51 *
52 * - If RESOLVE_REF_READING is not set, clear oid and return the name of
53 * the last reference name in the chain, which will either be a non-symbolic
54 * reference or an undefined reference. If this is a prelude to
55 * "writing" to the ref, the return value is the name of the ref
56 * that will actually be created or changed.
57 *
58 * If the RESOLVE_REF_NO_RECURSE flag is passed, only resolves one
59 * level of symbolic reference. The value stored in oid for a symbolic
60 * reference will always be null_oid in this case, and the return
61 * value is the reference that the symref refers to directly.
62 *
63 * If flags is non-NULL, set the value that it points to the
64 * combination of REF_ISPACKED (if the reference was found among the
65 * packed references), REF_ISSYMREF (if the initial reference was a
66 * symbolic reference), REF_BAD_NAME (if the reference name is ill
67 * formed --- see RESOLVE_REF_ALLOW_BAD_NAME below), and REF_ISBROKEN
68 * (if the ref is malformed or has a bad name). See refs.h for more detail
69 * on each flag.
70 *
71 * If ref is not a properly-formatted, normalized reference, return
72 * NULL. If more than MAXDEPTH recursive symbolic lookups are needed,
73 * give up and return NULL.
74 *
75 * RESOLVE_REF_ALLOW_BAD_NAME allows resolving refs even when their
76 * name is invalid according to git-check-ref-format(1). If the name
77 * is bad then the value stored in oid will be null_oid and the two
78 * flags REF_ISBROKEN and REF_BAD_NAME will be set.
79 *
80 * Even with RESOLVE_REF_ALLOW_BAD_NAME, names that escape the refs/
81 * directory and do not consist of all caps and underscores cannot be
82 * resolved. The function returns NULL for such ref names.
83 * Caps and underscores refers to the pseudorefs, such as HEAD,
84 * FETCH_HEAD and friends, that all live outside of the refs/ directory.
85 */
86#define RESOLVE_REF_READING 0x01
87#define RESOLVE_REF_NO_RECURSE 0x02
88#define RESOLVE_REF_ALLOW_BAD_NAME 0x04
89
90const char *refs_resolve_ref_unsafe(struct ref_store *refs,
91 const char *refname,
92 int resolve_flags,
93 struct object_id *oid,
94 int *flags);
95
96char *refs_resolve_refdup(struct ref_store *refs,
97 const char *refname, int resolve_flags,
98 struct object_id *oid, int *flags);
99
100int refs_read_ref_full(struct ref_store *refs, const char *refname,
101 int resolve_flags, struct object_id *oid, int *flags);
102
103int refs_read_ref(struct ref_store *refs, const char *refname, struct object_id *oid);
104
105#define NOT_A_SYMREF -2
106
107/*
108 * Read the symbolic ref named "refname" and write its immediate referent into
109 * the provided buffer. Referent is left empty if "refname" is not a symbolic
110 * ref. It does not resolve the symbolic reference recursively in case the
111 * target is also a symbolic ref.
112 *
113 * Returns 0 on success, -2 if the "refname" is not a symbolic ref,
114 * -1 otherwise.
115 */
116int refs_read_symbolic_ref(struct ref_store *ref_store, const char *refname,
117 struct strbuf *referent);
118
119/*
120 * Return 0 if a reference named refname could be created without
121 * conflicting with the name of an existing reference. Otherwise,
122 * return a negative value and write an explanation to err. If extras
123 * is non-NULL, it is a list of additional refnames with which refname
124 * is not allowed to conflict. If skip is non-NULL, ignore potential
125 * conflicts with refs in skip (e.g., because they are scheduled for
126 * deletion in the same operation). Behavior is undefined if the same
127 * name is listed in both extras and skip.
128 *
129 * Two reference names conflict if one of them exactly matches the
130 * leading components of the other; e.g., "foo/bar" conflicts with
131 * both "foo" and with "foo/bar/baz" but not with "foo/bar" or
132 * "foo/barbados".
133 *
134 * If `initial_transaction` is truish, then all collision checks with
135 * preexisting refs are skipped.
136 *
137 * extras and skip must be sorted.
138 */
139enum ref_transaction_error refs_verify_refname_available(struct ref_store *refs,
140 const char *refname,
141 const struct string_list *extras,
142 const struct string_list *skip,
143 unsigned int initial_transaction,
144 struct strbuf *err);
145
146int refs_ref_exists(struct ref_store *refs, const char *refname);
147
148int should_autocreate_reflog(enum log_refs_config log_all_ref_updates,
149 const char *refname);
150
151int is_branch(const char *refname);
152
153#define REF_STORE_CREATE_ON_DISK_IS_WORKTREE (1 << 0)
154
155int ref_store_create_on_disk(struct ref_store *refs, int flags, struct strbuf *err);
156
157/*
158 * Release all memory and resources associated with the ref store.
159 */
160void ref_store_release(struct ref_store *ref_store);
161
162/*
163 * Remove the ref store from disk. This deletes all associated data.
164 */
165int ref_store_remove_on_disk(struct ref_store *refs, struct strbuf *err);
166
167/*
168 * Return the peeled value of the oid currently being iterated via
169 * for_each_ref(), etc. This is equivalent to calling:
170 *
171 * peel_object(r, oid, &peeled);
172 *
173 * with the "oid" value given to the each_ref_fn callback, except
174 * that some ref storage may be able to answer the query without
175 * actually loading the object in memory.
176 */
177int peel_iterated_oid(struct repository *r,
178 const struct object_id *base, struct object_id *peeled);
179
180/**
181 * Resolve refname in the nested "gitlink" repository in the specified
182 * submodule (which must be non-NULL). If the resolution is
183 * successful, return 0 and set oid to the name of the object;
184 * otherwise, return a non-zero value.
185 */
186int repo_resolve_gitlink_ref(struct repository *r,
187 const char *submodule, const char *refname,
188 struct object_id *oid);
189
190/*
191 * Return true iff abbrev_name is a possible abbreviation for
192 * full_name according to the rules defined by ref_rev_parse_rules in
193 * refs.c.
194 */
195int refname_match(const char *abbrev_name, const char *full_name);
196
197/*
198 * Given a 'prefix' expand it by the rules in 'ref_rev_parse_rules' and add
199 * the results to 'prefixes'
200 */
201struct strvec;
202void expand_ref_prefix(struct strvec *prefixes, const char *prefix);
203
204int expand_ref(struct repository *r, const char *str, int len, struct object_id *oid, char **ref);
205int repo_dwim_ref(struct repository *r, const char *str, int len,
206 struct object_id *oid, char **ref, int nonfatal_dangling_mark);
207int repo_dwim_log(struct repository *r, const char *str, int len, struct object_id *oid, char **ref);
208
209/*
210 * Retrieves the default branch name for newly-initialized repositories.
211 *
212 * The return value is an allocated string.
213 */
214char *repo_default_branch_name(struct repository *r, int quiet);
215
216/*
217 * Copy "name" to "sb", expanding any special @-marks as handled by
218 * repo_interpret_branch_name(). The result is a non-qualified branch name
219 * (so "foo" or "origin/master" instead of "refs/heads/foo" or
220 * "refs/remotes/origin/master").
221 *
222 * Note that the resulting name may not be a syntactically valid refname.
223 *
224 * If "allowed" is non-zero, restrict the set of allowed expansions. See
225 * repo_interpret_branch_name() for details.
226 */
227void copy_branchname(struct strbuf *sb, const char *name,
228 unsigned allowed);
229
230/*
231 * Like copy_branchname() above, but confirm that the result is
232 * syntactically valid to be used as a local branch name in refs/heads/.
233 *
234 * The return value is "0" if the result is valid, and "-1" otherwise.
235 */
236int check_branch_ref(struct strbuf *sb, const char *name);
237
238/*
239 * Similar for a tag name in refs/tags/.
240 *
241 * The return value is "0" if the result is valid, and "-1" otherwise.
242 */
243int check_tag_ref(struct strbuf *sb, const char *name);
244
245/*
246 * A ref_transaction represents a collection of reference updates that
247 * should succeed or fail together.
248 *
249 * Calling sequence
250 * ----------------
251 *
252 * - Allocate and initialize a `struct ref_transaction` by calling
253 * `ref_transaction_begin()`.
254 *
255 * - Specify the intended ref updates by calling one or more of the
256 * following functions:
257 * - `ref_transaction_update()`
258 * - `ref_transaction_create()`
259 * - `ref_transaction_delete()`
260 * - `ref_transaction_verify()`
261 *
262 * - Then either:
263 *
264 * - Optionally call `ref_transaction_prepare()` to prepare the
265 * transaction. This locks all references, checks preconditions,
266 * etc. but doesn't finalize anything. If this step fails, the
267 * transaction has been closed and can only be freed. If this step
268 * succeeds, then `ref_transaction_commit()` is almost certain to
269 * succeed. However, you can still call `ref_transaction_abort()`
270 * if you decide not to commit the transaction after all.
271 *
272 * - Call `ref_transaction_commit()` to execute the transaction,
273 * make the changes permanent, and release all locks. If you
274 * haven't already called `ref_transaction_prepare()`, then
275 * `ref_transaction_commit()` calls it for you.
276 *
277 * Or
278 *
279 * - Call `ref_transaction_begin()` with REF_TRANSACTION_FLAG_INITIAL if the
280 * ref database is known to be empty and have no other writers (e.g. during
281 * clone). This is likely to be much faster than without the flag.
282 *
283 * - Then finally, call `ref_transaction_free()` to free the
284 * `ref_transaction` data structure.
285 *
286 * At any time before calling `ref_transaction_commit()`, you can call
287 * `ref_transaction_abort()` to abort the transaction, rollback any
288 * locks, and free any associated resources (including the
289 * `ref_transaction` data structure).
290 *
291 * Putting it all together, a complete reference update looks like
292 *
293 * struct ref_transaction *transaction;
294 * struct strbuf err = STRBUF_INIT;
295 * int ret = 0;
296 *
297 * transaction = ref_store_transaction_begin(refs, 0, &err);
298 * if (!transaction ||
299 * ref_transaction_update(...) ||
300 * ref_transaction_create(...) ||
301 * ...etc... ||
302 * ref_transaction_commit(transaction, &err)) {
303 * error("%s", err.buf);
304 * ret = -1;
305 * }
306 * ref_transaction_free(transaction);
307 * strbuf_release(&err);
308 * return ret;
309 *
310 * Error handling
311 * --------------
312 *
313 * On error, transaction functions append a message about what
314 * went wrong to the 'err' argument. The message mentions what
315 * ref was being updated (if any) when the error occurred so it
316 * can be passed to 'die' or 'error' as-is.
317 *
318 * The message is appended to err without first clearing err.
319 * err will not be '\n' terminated.
320 *
321 * Caveats
322 * -------
323 *
324 * Note that no locks are taken, and no refs are read, until
325 * `ref_transaction_prepare()` or `ref_transaction_commit()` is
326 * called. So, for example, `ref_transaction_verify()` won't report a
327 * verification failure until the commit is attempted.
328 */
329struct ref_transaction;
330
331/*
332 * Bit values set in the flags argument passed to each_ref_fn() and
333 * stored in ref_iterator::flags. Other bits are for internal use
334 * only:
335 */
336
337/* Reference is a symbolic reference. */
338#define REF_ISSYMREF 0x01
339
340/* Reference is a packed reference. */
341#define REF_ISPACKED 0x02
342
343/*
344 * Reference cannot be resolved to an object name: dangling symbolic
345 * reference (directly or indirectly), corrupt reference file,
346 * reference exists but name is bad, or symbolic reference refers to
347 * ill-formatted reference name.
348 */
349#define REF_ISBROKEN 0x04
350
351/*
352 * Reference name is not well formed.
353 *
354 * See git-check-ref-format(1) for the definition of well formed ref names.
355 */
356#define REF_BAD_NAME 0x08
357
358/*
359 * The signature for the callback function for the for_each_*()
360 * functions below. The memory pointed to by the refname and oid
361 * arguments is only guaranteed to be valid for the duration of a
362 * single callback invocation.
363 */
364typedef int each_ref_fn(const char *refname, const char *referent,
365 const struct object_id *oid, int flags, void *cb_data);
366
367/*
368 * The following functions invoke the specified callback function for
369 * each reference indicated. If the function ever returns a nonzero
370 * value, stop the iteration and return that value. Please note that
371 * it is not safe to modify references while an iteration is in
372 * progress, unless the same callback function invocation that
373 * modifies the reference also returns a nonzero value to immediately
374 * stop the iteration. Returned references are sorted.
375 */
376int refs_head_ref(struct ref_store *refs,
377 each_ref_fn fn, void *cb_data);
378int refs_for_each_ref(struct ref_store *refs,
379 each_ref_fn fn, void *cb_data);
380int refs_for_each_ref_in(struct ref_store *refs, const char *prefix,
381 each_ref_fn fn, void *cb_data);
382int refs_for_each_tag_ref(struct ref_store *refs,
383 each_ref_fn fn, void *cb_data);
384int refs_for_each_branch_ref(struct ref_store *refs,
385 each_ref_fn fn, void *cb_data);
386int refs_for_each_remote_ref(struct ref_store *refs,
387 each_ref_fn fn, void *cb_data);
388int refs_for_each_replace_ref(struct ref_store *refs,
389 each_ref_fn fn, void *cb_data);
390
391/*
392 * references matching any pattern in "exclude_patterns" are omitted from the
393 * result set on a best-effort basis.
394 */
395int refs_for_each_fullref_in(struct ref_store *refs, const char *prefix,
396 const char **exclude_patterns,
397 each_ref_fn fn, void *cb_data);
398
399/**
400 * iterate all refs in "patterns" by partitioning patterns into disjoint sets
401 * and iterating the longest-common prefix of each set.
402 *
403 * references matching any pattern in "exclude_patterns" are omitted from the
404 * result set on a best-effort basis.
405 *
406 * callers should be prepared to ignore references that they did not ask for.
407 */
408int refs_for_each_fullref_in_prefixes(struct ref_store *refs,
409 const char *namespace,
410 const char **patterns,
411 const char **exclude_patterns,
412 each_ref_fn fn, void *cb_data);
413
414/* iterates all refs that match the specified glob pattern. */
415int refs_for_each_glob_ref(struct ref_store *refs, each_ref_fn fn,
416 const char *pattern, void *cb_data);
417
418int refs_for_each_glob_ref_in(struct ref_store *refs, each_ref_fn fn,
419 const char *pattern, const char *prefix, void *cb_data);
420
421int refs_head_ref_namespaced(struct ref_store *refs, each_ref_fn fn, void *cb_data);
422
423/*
424 * references matching any pattern in "exclude_patterns" are omitted from the
425 * result set on a best-effort basis.
426 */
427int refs_for_each_namespaced_ref(struct ref_store *refs,
428 const char **exclude_patterns,
429 each_ref_fn fn, void *cb_data);
430
431/* can be used to learn about broken ref and symref */
432int refs_for_each_rawref(struct ref_store *refs, each_ref_fn fn, void *cb_data);
433int refs_for_each_rawref_in(struct ref_store *refs, const char *prefix,
434 each_ref_fn fn, void *cb_data);
435
436/*
437 * Iterates over all refs including root refs, i.e. pseudorefs and HEAD.
438 */
439int refs_for_each_include_root_refs(struct ref_store *refs, each_ref_fn fn,
440 void *cb_data);
441
442/*
443 * Normalizes partial refs to their fully qualified form.
444 * Will prepend <prefix> to the <pattern> if it doesn't start with 'refs/'.
445 * <prefix> will default to 'refs/' if NULL.
446 *
447 * item.string will be set to the result.
448 * item.util will be set to NULL if <pattern> contains glob characters, or
449 * non-NULL if it doesn't.
450 */
451void normalize_glob_ref(struct string_list_item *item, const char *prefix,
452 const char *pattern);
453
454static inline const char *has_glob_specials(const char *pattern)
455{
456 return strpbrk(pattern, "?*[");
457}
458
459void refs_warn_dangling_symrefs(struct ref_store *refs, FILE *fp,
460 const char *indent, int dry_run,
461 const struct string_list *refnames);
462
463/*
464 * Flags for controlling behaviour of pack_refs()
465 * PACK_REFS_PRUNE: Prune loose refs after packing
466 * PACK_REFS_AUTO: Pack refs on a best effort basis. The heuristics and end
467 * result are decided by the ref backend. Backends may ignore
468 * this flag and fall back to a normal repack.
469 */
470#define PACK_REFS_PRUNE (1 << 0)
471#define PACK_REFS_AUTO (1 << 1)
472
473struct pack_refs_opts {
474 unsigned int flags;
475 struct ref_exclusions *exclusions;
476 struct string_list *includes;
477};
478
479/*
480 * Write a packed-refs file for the current repository.
481 * flags: Combination of the above PACK_REFS_* flags.
482 */
483int refs_pack_refs(struct ref_store *refs, struct pack_refs_opts *opts);
484
485/*
486 * Optimize the ref store. The exact behavior is up to the backend.
487 * For the files backend, this is equivalent to packing refs.
488 */
489int refs_optimize(struct ref_store *refs, struct pack_refs_opts *opts);
490
491/*
492 * Setup reflog before using. Fill in err and return -1 on failure.
493 */
494int refs_create_reflog(struct ref_store *refs, const char *refname,
495 struct strbuf *err);
496
497/**
498 * Reads log for the value of ref during at_time (in which case "cnt" should be
499 * negative) or the reflog "cnt" entries from the top (in which case "at_time"
500 * should be 0).
501 *
502 * If we found the reflog entry in question, returns 0 (and details of the
503 * entry can be found in the out-parameters).
504 *
505 * If we ran out of reflog entries, the out-parameters are filled with the
506 * details of the oldest entry we did find, and the function returns 1. Note
507 * that there is one important special case here! If the reflog was empty
508 * and the caller asked for the 0-th cnt, we will return "1" but leave the
509 * "oid" field untouched.
510 **/
511int read_ref_at(struct ref_store *refs,
512 const char *refname, unsigned int flags,
513 timestamp_t at_time, int cnt,
514 struct object_id *oid, char **msg,
515 timestamp_t *cutoff_time, int *cutoff_tz, int *cutoff_cnt);
516
517/** Check if a particular reflog exists */
518int refs_reflog_exists(struct ref_store *refs, const char *refname);
519
520/*
521 * Delete the specified reference. If old_oid is non-NULL, then
522 * verify that the current value of the reference is old_oid before
523 * deleting it. If old_oid is NULL, delete the reference if it
524 * exists, regardless of its old value. It is an error for old_oid to
525 * be null_oid. msg and flags are passed through to
526 * ref_transaction_delete().
527 */
528int refs_delete_ref(struct ref_store *refs, const char *msg,
529 const char *refname,
530 const struct object_id *old_oid,
531 unsigned int flags);
532
533/*
534 * Delete the specified references. If there are any problems, emit
535 * errors but attempt to keep going (i.e., the deletes are not done in
536 * an all-or-nothing transaction). msg and flags are passed through to
537 * ref_transaction_delete().
538 */
539int refs_delete_refs(struct ref_store *refs, const char *msg,
540 struct string_list *refnames, unsigned int flags);
541
542/** Delete a reflog */
543int refs_delete_reflog(struct ref_store *refs, const char *refname);
544
545/*
546 * Callback to process a reflog entry found by the iteration functions (see
547 * below).
548 *
549 * The committer parameter is a single string, in the form
550 * "$GIT_COMMITTER_NAME <$GIT_COMMITTER_EMAIL>" (without double quotes).
551 *
552 * The timestamp parameter gives the time when entry was created as the number
553 * of seconds since the UNIX epoch.
554 *
555 * The tz parameter gives the timezone offset for the user who created
556 * the reflog entry, and its value gives a positive or negative offset
557 * from UTC. Its absolute value is formed by multiplying the hour
558 * part by 100 and adding the minute part. For example, 1 hour ahead
559 * of UTC, CET == "+0100", is represented as positive one hundred (not
560 * positive sixty).
561 *
562 * The msg parameter is a single complete line; a reflog message given
563 * to refs_delete_ref, refs_update_ref, etc. is returned to the
564 * callback normalized---each run of whitespaces are squashed into a
565 * single whitespace, trailing whitespace, if exists, is trimmed, and
566 * then a single LF is added at the end.
567 *
568 * The cb_data is a caller-supplied pointer given to the iterator
569 * functions.
570 */
571typedef int each_reflog_ent_fn(const char *refname,
572 struct object_id *old_oid,
573 struct object_id *new_oid,
574 const char *committer,
575 timestamp_t timestamp,
576 int tz, const char *msg,
577 void *cb_data);
578
579/* Iterate over reflog entries in the log for `refname`. */
580
581/* oldest entry first */
582int refs_for_each_reflog_ent(struct ref_store *refs, const char *refname,
583 each_reflog_ent_fn fn, void *cb_data);
584
585/* youngest entry first */
586int refs_for_each_reflog_ent_reverse(struct ref_store *refs,
587 const char *refname,
588 each_reflog_ent_fn fn,
589 void *cb_data);
590
591/*
592 * The signature for the callback function for the refs_for_each_reflog()
593 * functions below. The memory pointed to by the refname argument is only
594 * guaranteed to be valid for the duration of a single callback invocation.
595 */
596typedef int each_reflog_fn(const char *refname, void *cb_data);
597
598/*
599 * Calls the specified function for each reflog file until it returns nonzero,
600 * and returns the value. Reflog file order is unspecified.
601 */
602int refs_for_each_reflog(struct ref_store *refs, each_reflog_fn fn, void *cb_data);
603
604#define REFNAME_ALLOW_ONELEVEL 1
605#define REFNAME_REFSPEC_PATTERN 2
606
607/*
608 * Return 0 iff refname has the correct format for a refname according
609 * to the rules described in Documentation/git-check-ref-format.adoc.
610 * If REFNAME_ALLOW_ONELEVEL is set in flags, then accept one-level
611 * reference names. If REFNAME_REFSPEC_PATTERN is set in flags, then
612 * allow a single "*" wildcard character in the refspec. No leading or
613 * repeated slashes are accepted.
614 */
615int check_refname_format(const char *refname, int flags);
616
617/*
618 * Check the reference database for consistency. Return 0 if refs and
619 * reflogs are consistent, and non-zero otherwise. The errors will be
620 * written to stderr.
621 */
622int refs_fsck(struct ref_store *refs, struct fsck_options *o,
623 struct worktree *wt);
624
625/*
626 * Apply the rules from check_refname_format, but mutate the result until it
627 * is acceptable, and place the result in "out".
628 */
629void sanitize_refname_component(const char *refname, struct strbuf *out);
630
631const char *prettify_refname(const char *refname);
632
633char *refs_shorten_unambiguous_ref(struct ref_store *refs,
634 const char *refname, int strict);
635
636/** rename ref, return 0 on success **/
637int refs_rename_ref(struct ref_store *refs, const char *oldref,
638 const char *newref, const char *logmsg);
639
640/** copy ref, return 0 on success **/
641int refs_copy_existing_ref(struct ref_store *refs, const char *oldref,
642 const char *newref, const char *logmsg);
643
644int refs_update_symref(struct ref_store *refs, const char *refname,
645 const char *target, const char *logmsg);
646
647int refs_update_symref_extended(struct ref_store *refs, const char *refname,
648 const char *target, const char *logmsg,
649 struct strbuf *referent, int create_only);
650
651enum action_on_err {
652 UPDATE_REFS_MSG_ON_ERR,
653 UPDATE_REFS_DIE_ON_ERR,
654 UPDATE_REFS_QUIET_ON_ERR
655};
656
657enum ref_transaction_flag {
658 /*
659 * The ref transaction is part of the initial creation of the ref store
660 * and can thus assume that the ref store is completely empty. This
661 * allows the backend to perform the transaction more efficiently by
662 * skipping certain checks.
663 *
664 * It is a bug to set this flag when there might be other processes
665 * accessing the repository or if there are existing references that
666 * might conflict with the ones being created. All old_oid values must
667 * either be absent or null_oid.
668 */
669 REF_TRANSACTION_FLAG_INITIAL = (1 << 0),
670
671 /*
672 * The transaction mechanism by default fails all updates if any conflict
673 * is detected. This flag allows transactions to partially apply updates
674 * while rejecting updates which do not match the expected state.
675 */
676 REF_TRANSACTION_ALLOW_FAILURE = (1 << 1),
677};
678
679/*
680 * Begin a reference transaction. The reference transaction must
681 * be freed by calling ref_transaction_free().
682 */
683struct ref_transaction *ref_store_transaction_begin(struct ref_store *refs,
684 unsigned int flags,
685 struct strbuf *err);
686
687/*
688 * Reference transaction updates
689 *
690 * The following four functions add a reference check or update to a
691 * ref_transaction. They have some common similar parameters:
692 *
693 * transaction -- a pointer to an open ref_transaction, obtained
694 * from ref_transaction_begin().
695 *
696 * refname -- the name of the reference to be affected.
697 *
698 * new_oid -- the object ID that should be set to be the new value
699 * of the reference. Some functions allow this parameter to be
700 * NULL, meaning that the reference is not changed, or
701 * null_oid, meaning that the reference should be deleted. A
702 * copy of this value is made in the transaction.
703 *
704 * old_oid -- the object ID that the reference must have before
705 * the update. Some functions allow this parameter to be NULL,
706 * meaning that the old value of the reference is not checked,
707 * or null_oid, meaning that the reference must not exist
708 * before the update. A copy of this value is made in the
709 * transaction.
710 *
711 * new_target -- the target reference that the reference will be
712 * updated to point to. If the reference is a regular reference,
713 * it will be converted to a symbolic reference. Cannot be set
714 * together with `new_oid`. A copy of this value is made in the
715 * transaction.
716 *
717 * old_target -- the reference that the reference must be pointing to.
718 * Canont be set together with `old_oid`. A copy of this value is
719 * made in the transaction.
720 *
721 * flags -- flags affecting the update, passed to
722 * update_ref_lock(). Possible flags: REF_NO_DEREF,
723 * REF_FORCE_CREATE_REFLOG. See those constants for more
724 * information.
725 *
726 * msg -- a message describing the change (for the reflog).
727 *
728 * err -- a strbuf for receiving a description of any error that
729 * might have occurred.
730 *
731 * The functions make internal copies of refname and msg, so the
732 * caller retains ownership of these parameters.
733 *
734 * The functions return 0 on success and non-zero on failure. A
735 * failure means that the transaction as a whole has failed and needs
736 * to be rolled back.
737 */
738
739/*
740 * The following flags can be passed to ref_transaction_update() etc.
741 * Internally, they are stored in `ref_update::flags`, along with some
742 * internal flags.
743 */
744
745/*
746 * Act on the ref directly; i.e., without dereferencing symbolic refs.
747 * If this flag is not specified, then symbolic references are
748 * dereferenced and the update is applied to the referent.
749 */
750#define REF_NO_DEREF (1 << 0)
751
752/*
753 * Force the creation of a reflog for this reference, even if it
754 * didn't previously have a reflog.
755 */
756#define REF_FORCE_CREATE_REFLOG (1 << 1)
757
758/*
759 * Blindly write an object_id. This is useful for testing data corruption
760 * scenarios.
761 */
762#define REF_SKIP_OID_VERIFICATION (1 << 10)
763
764/*
765 * Skip verifying refname. This is useful for testing data corruption scenarios.
766 */
767#define REF_SKIP_REFNAME_VERIFICATION (1 << 11)
768
769/*
770 * Skip creation of a reflog entry, even if it would have otherwise been
771 * created.
772 */
773#define REF_SKIP_CREATE_REFLOG (1 << 12)
774
775/*
776 * When writing a REF_LOG_ONLY record, use the old and new object IDs provided
777 * in the update instead of resolving the old object ID. The caller must also
778 * set both REF_HAVE_OLD and REF_HAVE_NEW.
779 */
780#define REF_LOG_USE_PROVIDED_OIDS (1 << 13)
781
782/*
783 * Bitmask of all of the flags that are allowed to be passed in to
784 * ref_transaction_update() and friends:
785 */
786#define REF_TRANSACTION_UPDATE_ALLOWED_FLAGS \
787 (REF_NO_DEREF | REF_FORCE_CREATE_REFLOG | REF_SKIP_OID_VERIFICATION | \
788 REF_SKIP_REFNAME_VERIFICATION | REF_SKIP_CREATE_REFLOG | REF_LOG_USE_PROVIDED_OIDS)
789
790/*
791 * Add a reference update to transaction. `new_oid` is the value that
792 * the reference should have after the update, or `null_oid` if it
793 * should be deleted. If `new_oid` is NULL, then the reference is not
794 * changed at all. `old_oid` is the value that the reference must have
795 * before the update, or `null_oid` if it must not have existed
796 * beforehand. The old value is checked after the lock is taken to
797 * prevent races. If the old value doesn't agree with old_oid, the
798 * whole transaction fails. If old_oid is NULL, then the previous
799 * value is not checked. If `old_target` is not NULL, treat the reference
800 * as a symbolic ref and validate that its target before the update is
801 * `old_target`. If the `new_target` is not NULL, then the reference
802 * will be updated to a symbolic ref which targets `new_target`.
803 * Together, these allow us to update between regular refs and symrefs.
804 *
805 * See the above comment "Reference transaction updates" for more
806 * information.
807 */
808int ref_transaction_update(struct ref_transaction *transaction,
809 const char *refname,
810 const struct object_id *new_oid,
811 const struct object_id *old_oid,
812 const char *new_target,
813 const char *old_target,
814 unsigned int flags, const char *msg,
815 struct strbuf *err);
816
817/*
818 * Similar to `ref_transaction_update`, but this function is only for adding
819 * a reflog update. Supports providing custom committer information. The index
820 * field can be utiltized to order updates as desired. When set to zero, the
821 * updates default to being ordered by refname.
822 */
823int ref_transaction_update_reflog(struct ref_transaction *transaction,
824 const char *refname,
825 const struct object_id *new_oid,
826 const struct object_id *old_oid,
827 const char *committer_info,
828 const char *msg,
829 uint64_t index,
830 struct strbuf *err);
831
832/*
833 * Add a reference creation to transaction. new_oid is the value that
834 * the reference should have after the update; it must not be
835 * null_oid. It is verified that the reference does not exist
836 * already.
837 *
838 * See the above comment "Reference transaction updates" for more
839 * information.
840 */
841int ref_transaction_create(struct ref_transaction *transaction,
842 const char *refname,
843 const struct object_id *new_oid,
844 const char *new_target,
845 unsigned int flags, const char *msg,
846 struct strbuf *err);
847
848/*
849 * Add a reference deletion to transaction. If old_oid is non-NULL,
850 * then it holds the value that the reference should have had before
851 * the update (which must not be null_oid).
852 *
853 * See the above comment "Reference transaction updates" for more
854 * information.
855 */
856int ref_transaction_delete(struct ref_transaction *transaction,
857 const char *refname,
858 const struct object_id *old_oid,
859 const char *old_target,
860 unsigned int flags,
861 const char *msg,
862 struct strbuf *err);
863
864/*
865 * Verify, within a transaction, that refname has the value old_oid,
866 * or, if old_oid is null_oid, then verify that the reference
867 * doesn't exist. old_oid must be non-NULL.
868 *
869 * See the above comment "Reference transaction updates" for more
870 * information.
871 */
872int ref_transaction_verify(struct ref_transaction *transaction,
873 const char *refname,
874 const struct object_id *old_oid,
875 const char *old_target,
876 unsigned int flags,
877 struct strbuf *err);
878
879/*
880 * Perform the preparatory stages of committing `transaction`. Acquire
881 * any needed locks, check preconditions, etc.; basically, do as much
882 * as possible to ensure that the transaction will be able to go
883 * through, stopping just short of making any irrevocable or
884 * user-visible changes. The updates that this function prepares can
885 * be finished up by calling `ref_transaction_commit()` or rolled back
886 * by calling `ref_transaction_abort()`.
887 *
888 * On success, return 0 and leave the transaction in "prepared" state.
889 * On failure, abort the transaction, write an error message to `err`,
890 * and return one of the `TRANSACTION_*` constants.
891 *
892 * Callers who don't need such fine-grained control over committing
893 * reference transactions should just call `ref_transaction_commit()`.
894 */
895int ref_transaction_prepare(struct ref_transaction *transaction,
896 struct strbuf *err);
897
898/*
899 * Commit all of the changes that have been queued in transaction, as
900 * atomically as possible. On success, return 0 and leave the
901 * transaction in "closed" state. On failure, roll back the
902 * transaction, write an error message to `err`, and return one of the
903 * `TRANSACTION_*` constants
904 */
905int ref_transaction_commit(struct ref_transaction *transaction,
906 struct strbuf *err);
907
908/*
909 * Abort `transaction`, which has been begun and possibly prepared,
910 * but not yet committed.
911 */
912int ref_transaction_abort(struct ref_transaction *transaction,
913 struct strbuf *err);
914
915/*
916 * Execute the given callback function for each of the reference updates which
917 * have been queued in the given transaction. `old_oid` and `new_oid` may be
918 * `NULL` pointers depending on whether the update has these object IDs set or
919 * not.
920 */
921typedef void ref_transaction_for_each_queued_update_fn(const char *refname,
922 const struct object_id *old_oid,
923 const struct object_id *new_oid,
924 void *cb_data);
925void ref_transaction_for_each_queued_update(struct ref_transaction *transaction,
926 ref_transaction_for_each_queued_update_fn cb,
927 void *cb_data);
928
929/*
930 * Execute the given callback function for each of the reference updates which
931 * have been rejected in the given transaction.
932 */
933typedef void ref_transaction_for_each_rejected_update_fn(const char *refname,
934 const struct object_id *old_oid,
935 const struct object_id *new_oid,
936 const char *old_target,
937 const char *new_target,
938 enum ref_transaction_error err,
939 void *cb_data);
940void ref_transaction_for_each_rejected_update(struct ref_transaction *transaction,
941 ref_transaction_for_each_rejected_update_fn cb,
942 void *cb_data);
943
944/*
945 * Translate errors to human readable error messages.
946 */
947const char *ref_transaction_error_msg(enum ref_transaction_error err);
948
949/*
950 * Free `*transaction` and all associated data.
951 */
952void ref_transaction_free(struct ref_transaction *transaction);
953
954/**
955 * Lock, update, and unlock a single reference. This function
956 * basically does a transaction containing a single call to
957 * ref_transaction_update(). The parameters to this function have the
958 * same meaning as the corresponding parameters to
959 * ref_transaction_update(). Handle errors as requested by the `onerr`
960 * argument.
961 */
962int refs_update_ref(struct ref_store *refs, const char *msg, const char *refname,
963 const struct object_id *new_oid, const struct object_id *old_oid,
964 unsigned int flags, enum action_on_err onerr);
965
966int parse_hide_refs_config(const char *var, const char *value, const char *,
967 struct strvec *);
968
969/*
970 * Check whether a ref is hidden. If no namespace is set, both the first and
971 * the second parameter point to the full ref name. If a namespace is set and
972 * the ref is inside that namespace, the first parameter is a pointer to the
973 * name of the ref with the namespace prefix removed. If a namespace is set and
974 * the ref is outside that namespace, the first parameter is NULL. The second
975 * parameter always points to the full ref name.
976 */
977int ref_is_hidden(const char *, const char *, const struct strvec *);
978
979/*
980 * Returns an array of patterns to use as excluded_patterns, if none of the
981 * hidden references use the token '!' or '^'.
982 */
983const char **hidden_refs_to_excludes(const struct strvec *hide_refs);
984
985/*
986 * Prefix all exclude patterns with the namespace, if any. This is required
987 * because exclude patterns apply to the stripped reference name, not the full
988 * reference name with the namespace.
989 */
990const char **get_namespaced_exclude_patterns(const char **exclude_patterns,
991 const char *namespace,
992 struct strvec *out);
993
994/* Is this a per-worktree ref living in the refs/ namespace? */
995int is_per_worktree_ref(const char *refname);
996
997/* Describes how a refname relates to worktrees */
998enum ref_worktree_type {
999 REF_WORKTREE_CURRENT, /* implicitly per worktree, eg. HEAD or
1000 refs/bisect/SOMETHING */
1001 REF_WORKTREE_MAIN, /* explicitly in main worktree, eg.
1002 main-worktree/HEAD */
1003 REF_WORKTREE_OTHER, /* explicitly in named worktree, eg.
1004 worktrees/bla/HEAD */
1005 REF_WORKTREE_SHARED, /* the default, eg. refs/heads/main */
1006};
1007
1008/*
1009 * Parse a `maybe_worktree_ref` as a ref that possibly refers to a worktree ref
1010 * (ie. either REFNAME, main-worktree/REFNAME or worktree/WORKTREE/REFNAME). It
1011 * returns what kind of ref was found, and in case of REF_WORKTREE_OTHER, the
1012 * worktree name is returned in `worktree_name` (pointing into
1013 * `maybe_worktree_ref`) and `worktree_name_length`. The bare refname (the
1014 * refname stripped of prefixes) is returned in `bare_refname`. The
1015 * `worktree_name`, `worktree_name_length` and `bare_refname` arguments may be
1016 * NULL.
1017 */
1018enum ref_worktree_type parse_worktree_ref(const char *maybe_worktree_ref,
1019 const char **worktree_name,
1020 int *worktree_name_length,
1021 const char **bare_refname);
1022
1023enum expire_reflog_flags {
1024 EXPIRE_REFLOGS_DRY_RUN = 1 << 0,
1025 EXPIRE_REFLOGS_UPDATE_REF = 1 << 1,
1026 EXPIRE_REFLOGS_REWRITE = 1 << 2,
1027};
1028
1029/*
1030 * The following interface is used for reflog expiration. The caller
1031 * calls refs_reflog_expire(), supplying it with three callback functions,
1032 * of the following types. The callback functions define the
1033 * expiration policy that is desired.
1034 *
1035 * reflog_expiry_prepare_fn -- Called once after the reference is
1036 * locked. Called with the OID of the locked reference.
1037 *
1038 * reflog_expiry_should_prune_fn -- Called once for each entry in the
1039 * existing reflog. It should return true iff that entry should be
1040 * pruned.
1041 *
1042 * reflog_expiry_cleanup_fn -- Called once before the reference is
1043 * unlocked again.
1044 */
1045typedef void reflog_expiry_prepare_fn(const char *refname,
1046 const struct object_id *oid,
1047 void *cb_data);
1048typedef int reflog_expiry_should_prune_fn(struct object_id *ooid,
1049 struct object_id *noid,
1050 const char *email,
1051 timestamp_t timestamp, int tz,
1052 const char *message, void *cb_data);
1053typedef void reflog_expiry_cleanup_fn(void *cb_data);
1054
1055/*
1056 * Expire reflog entries for the specified reference.
1057 * flags is a combination of the constants in
1058 * enum expire_reflog_flags. The three function pointers are described
1059 * above. On success, return zero.
1060 */
1061int refs_reflog_expire(struct ref_store *refs,
1062 const char *refname,
1063 unsigned int flags,
1064 reflog_expiry_prepare_fn prepare_fn,
1065 reflog_expiry_should_prune_fn should_prune_fn,
1066 reflog_expiry_cleanup_fn cleanup_fn,
1067 void *policy_cb_data);
1068
1069struct ref_store *get_main_ref_store(struct repository *r);
1070
1071/**
1072 * Submodules
1073 * ----------
1074 *
1075 * If you want to iterate the refs of a submodule you first need to add the
1076 * submodules object database. You can do this by a code-snippet like
1077 * this:
1078 *
1079 * const char *path = "path/to/submodule"
1080 * if (add_submodule_odb(path))
1081 * die("Error submodule '%s' not populated.", path);
1082 *
1083 * `add_submodule_odb()` will return zero on success. If you
1084 * do not do this you will get an error for each ref that it does not point
1085 * to a valid object.
1086 *
1087 * Note: As a side-effect of this you cannot safely assume that all
1088 * objects you lookup are available in superproject. All submodule objects
1089 * will be available the same way as the superprojects objects.
1090 *
1091 * Example:
1092 * --------
1093 *
1094 * ----
1095 * static int handle_remote_ref(const char *refname,
1096 * const unsigned char *sha1, int flags, void *cb_data)
1097 * {
1098 * struct strbuf *output = cb_data;
1099 * strbuf_addf(output, "%s\n", refname);
1100 * return 0;
1101 * }
1102 *
1103 */
1104
1105/*
1106 * Return the ref_store instance for the specified submodule. For the
1107 * main repository, use submodule==NULL; such a call cannot fail. For
1108 * a submodule, the submodule must exist and be a nonbare repository,
1109 * otherwise return NULL. If the requested reference store has not yet
1110 * been initialized, initialize it first.
1111 *
1112 * For backwards compatibility, submodule=="" is treated the same as
1113 * submodule==NULL.
1114 */
1115struct ref_store *repo_get_submodule_ref_store(struct repository *repo,
1116 const char *submodule);
1117struct ref_store *get_worktree_ref_store(const struct worktree *wt);
1118
1119/*
1120 * Some of the names specified by refs have special meaning to Git.
1121 * Organize these namespaces in a common 'ref_namespace' array for
1122 * reference from multiple places in the codebase.
1123 */
1124
1125struct ref_namespace_info {
1126 const char *ref;
1127 enum decoration_type decoration;
1128
1129 /*
1130 * If 'exact' is true, then we must match the 'ref' exactly.
1131 * Otherwise, use a prefix match.
1132 *
1133 * 'ref_updated' is for internal use. It represents whether the
1134 * 'ref' value was replaced from its original literal version.
1135 */
1136 unsigned exact:1,
1137 ref_updated:1;
1138};
1139
1140enum ref_namespace {
1141 NAMESPACE_HEAD,
1142 NAMESPACE_BRANCHES,
1143 NAMESPACE_TAGS,
1144 NAMESPACE_REMOTE_REFS,
1145 NAMESPACE_STASH,
1146 NAMESPACE_REPLACE,
1147 NAMESPACE_NOTES,
1148 NAMESPACE_PREFETCH,
1149 NAMESPACE_REWRITTEN,
1150
1151 /* Must be last */
1152 NAMESPACE__COUNT
1153};
1154
1155/* See refs.c for the contents of this array. */
1156extern struct ref_namespace_info ref_namespace[NAMESPACE__COUNT];
1157
1158/*
1159 * Some ref namespaces can be modified by config values or environment
1160 * variables. Modify a namespace as specified by its ref_namespace key.
1161 */
1162void update_ref_namespace(enum ref_namespace namespace, char *ref);
1163
1164/*
1165 * Check whether the provided name names a root reference. This function only
1166 * performs a syntactic check.
1167 *
1168 * A root ref is a reference that lives in the root of the reference hierarchy.
1169 * These references must conform to special syntax:
1170 *
1171 * - Their name must be all-uppercase or underscores ("_").
1172 *
1173 * - Their name must end with "_HEAD". As a special rule, "HEAD" is a root
1174 * ref, as well.
1175 *
1176 * - Their name may not contain a slash.
1177 *
1178 * There is a special set of irregular root refs that exist due to historic
1179 * reasons, only. This list shall not be expanded in the future:
1180 *
1181 * - AUTO_MERGE
1182 *
1183 * - BISECT_EXPECTED_REV
1184 *
1185 * - NOTES_MERGE_PARTIAL
1186 *
1187 * - NOTES_MERGE_REF
1188 *
1189 * - MERGE_AUTOSTASH
1190 */
1191int is_root_ref(const char *refname);
1192
1193/*
1194 * Pseudorefs are refs that have different semantics compared to
1195 * "normal" refs. These refs can thus not be stored in the ref backend,
1196 * but must always be accessed via the filesystem. The following refs
1197 * are pseudorefs:
1198 *
1199 * - FETCH_HEAD may contain multiple object IDs, and each one of them
1200 * carries additional metadata like where it came from.
1201 *
1202 * - MERGE_HEAD may contain multiple object IDs when merging multiple
1203 * heads.
1204 *
1205 * Reading, writing or deleting references must consistently go either
1206 * through the filesystem (pseudorefs) or through the reference
1207 * backend (normal ones).
1208 */
1209int is_pseudo_ref(const char *refname);
1210
1211/*
1212 * The following flags can be passed to `repo_migrate_ref_storage_format()`:
1213 *
1214 * - REPO_MIGRATE_REF_STORAGE_FORMAT_DRYRUN: perform a dry-run migration
1215 * without touching the main repository. The result will be written into a
1216 * temporary ref storage directory.
1217 *
1218 * - REPO_MIGRATE_REF_STORAGE_FORMAT_SKIP_REFLOG: skip migration of reflogs.
1219 */
1220#define REPO_MIGRATE_REF_STORAGE_FORMAT_DRYRUN (1 << 0)
1221#define REPO_MIGRATE_REF_STORAGE_FORMAT_SKIP_REFLOG (1 << 1)
1222
1223/*
1224 * Migrate the ref storage format used by the repository to the
1225 * specified one.
1226 */
1227int repo_migrate_ref_storage_format(struct repository *repo,
1228 enum ref_storage_format format,
1229 unsigned int flags,
1230 struct strbuf *err);
1231
1232/*
1233 * Reference iterators
1234 *
1235 * A reference iterator encapsulates the state of an in-progress
1236 * iteration over references. Create an instance of `struct
1237 * ref_iterator` via one of the functions in this module.
1238 *
1239 * A freshly-created ref_iterator doesn't yet point at a reference. To
1240 * advance the iterator, call ref_iterator_advance(). If successful,
1241 * this sets the iterator's refname, oid, and flags fields to describe
1242 * the next reference and returns ITER_OK. The data pointed at by
1243 * refname and oid belong to the iterator; if you want to retain them
1244 * after calling ref_iterator_advance() again or calling
1245 * ref_iterator_free(), you must make a copy. When the iteration has
1246 * been exhausted, ref_iterator_advance() releases any resources
1247 * associated with the iteration, frees the ref_iterator object, and
1248 * returns ITER_DONE. If you want to abort the iteration early, call
1249 * ref_iterator_free(), which also frees the ref_iterator object and
1250 * any associated resources. If there was an internal error advancing
1251 * to the next entry, ref_iterator_advance() aborts the iteration,
1252 * frees the ref_iterator, and returns ITER_ERROR.
1253 *
1254 * The reference currently being looked at can be peeled by calling
1255 * ref_iterator_peel(). This function is often faster than peel_ref(),
1256 * so it should be preferred when iterating over references.
1257 *
1258 * Putting it all together, a typical iteration looks like this:
1259 *
1260 * int ok;
1261 * struct ref_iterator *iter = ...;
1262 *
1263 * while ((ok = ref_iterator_advance(iter)) == ITER_OK) {
1264 * if (want_to_stop_iteration()) {
1265 * ok = ITER_DONE;
1266 * break;
1267 * }
1268 *
1269 * // Access information about the current reference:
1270 * if (!(iter->flags & REF_ISSYMREF))
1271 * printf("%s is %s\n", iter->refname, oid_to_hex(iter->oid));
1272 *
1273 * // If you need to peel the reference:
1274 * ref_iterator_peel(iter, &oid);
1275 * }
1276 *
1277 * if (ok != ITER_DONE)
1278 * handle_error();
1279 * ref_iterator_free(iter);
1280 */
1281struct ref_iterator;
1282
1283/*
1284 * These flags are passed to refs_ref_iterator_begin() (and do_for_each_ref(),
1285 * which feeds it).
1286 */
1287enum do_for_each_ref_flags {
1288 /*
1289 * Include broken references in a do_for_each_ref*() iteration, which
1290 * would normally be omitted. This includes both refs that point to
1291 * missing objects (a true repository corruption), ones with illegal
1292 * names (which we prefer not to expose to callers), as well as
1293 * dangling symbolic refs (i.e., those that point to a non-existent
1294 * ref; this is not a corruption, but as they have no valid oid, we
1295 * omit them from normal iteration results).
1296 */
1297 DO_FOR_EACH_INCLUDE_BROKEN = (1 << 0),
1298
1299 /*
1300 * Only include per-worktree refs in a do_for_each_ref*() iteration.
1301 * Normally this will be used with a files ref_store, since that's
1302 * where all reference backends will presumably store their
1303 * per-worktree refs.
1304 */
1305 DO_FOR_EACH_PER_WORKTREE_ONLY = (1 << 1),
1306
1307 /*
1308 * Omit dangling symrefs from output; this only has an effect with
1309 * INCLUDE_BROKEN, since they are otherwise not included at all.
1310 */
1311 DO_FOR_EACH_OMIT_DANGLING_SYMREFS = (1 << 2),
1312
1313 /*
1314 * Include root refs i.e. HEAD and pseudorefs along with the regular
1315 * refs.
1316 */
1317 DO_FOR_EACH_INCLUDE_ROOT_REFS = (1 << 3),
1318};
1319
1320/*
1321 * Return an iterator that goes over each reference in `refs` for
1322 * which the refname begins with prefix. If trim is non-zero, then
1323 * trim that many characters off the beginning of each refname.
1324 * The output is ordered by refname.
1325 */
1326struct ref_iterator *refs_ref_iterator_begin(
1327 struct ref_store *refs,
1328 const char *prefix, const char **exclude_patterns,
1329 int trim, enum do_for_each_ref_flags flags);
1330
1331/*
1332 * Advance the iterator to the first or next item and return ITER_OK.
1333 * If the iteration is exhausted, free the resources associated with
1334 * the ref_iterator and return ITER_DONE. On errors, free the iterator
1335 * resources and return ITER_ERROR. It is a bug to use ref_iterator or
1336 * call this function again after it has returned ITER_DONE or
1337 * ITER_ERROR.
1338 */
1339int ref_iterator_advance(struct ref_iterator *ref_iterator);
1340
1341enum ref_iterator_seek_flag {
1342 /*
1343 * When the REF_ITERATOR_SEEK_SET_PREFIX flag is set, the iterator's prefix is
1344 * updated to match the provided string, affecting all subsequent iterations. If
1345 * not, the iterator seeks to the specified reference and clears any previously
1346 * set prefix.
1347 */
1348 REF_ITERATOR_SEEK_SET_PREFIX = (1 << 0),
1349};
1350
1351/*
1352 * Seek the iterator to the first reference matching the given seek string.
1353 * The seek string is matched as a literal string, without regard for path
1354 * separators. If seek is NULL or the empty string, seek the iterator to the
1355 * first reference again.
1356 *
1357 * This function is expected to behave as if a new ref iterator has been
1358 * created, but allows reuse of existing iterators for optimization.
1359 *
1360 * Returns 0 on success, a negative error code otherwise.
1361 */
1362int ref_iterator_seek(struct ref_iterator *ref_iterator, const char *refname,
1363 unsigned int flags);
1364
1365/*
1366 * If possible, peel the reference currently being viewed by the
1367 * iterator. Return 0 on success.
1368 */
1369int ref_iterator_peel(struct ref_iterator *ref_iterator,
1370 struct object_id *peeled);
1371
1372/* Free the reference iterator and any associated resources. */
1373void ref_iterator_free(struct ref_iterator *ref_iterator);
1374
1375/*
1376 * The common backend for the for_each_*ref* functions. Call fn for
1377 * each reference in iter. If the iterator itself ever returns
1378 * ITER_ERROR, return -1. If fn ever returns a non-zero value, stop
1379 * the iteration and return that value. Otherwise, return 0. In any
1380 * case, free the iterator when done. This function is basically an
1381 * adapter between the callback style of reference iteration and the
1382 * iterator style.
1383 */
1384int do_for_each_ref_iterator(struct ref_iterator *iter,
1385 each_ref_fn fn, void *cb_data);
1386
1387#endif /* REFS_H */