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