blob: 935cdd1ece3db3af483cb2225f204966c0e6cfa5 [file] [log] [blame]
Daniel Barkalow95fc7512005-06-06 16:31:29 -04001#ifndef REFS_H
2#define REFS_H
3
Jonathan Tanec06b052020-09-01 15:28:08 -07004#include "cache.h"
Derrick Stoleeb9342b32022-08-05 17:58:36 +00005#include "commit.h"
Jonathan Tanec06b052020-09-01 15:28:08 -07006
Nguyễn Thái Ngọc Duy504c4d42017-03-18 09:03:11 +07007struct object_id;
Nguyễn Thái Ngọc Duy077be782017-03-26 09:42:29 +07008struct ref_store;
Elijah Newrenef3ca952018-08-15 10:54:05 -07009struct repository;
Nguyễn Thái Ngọc Duy504c4d42017-03-18 09:03:11 +070010struct strbuf;
11struct string_list;
Elijah Newrenef3ca952018-08-15 10:54:05 -070012struct string_list_item;
Nguyễn Thái Ngọc Duy17eff962017-04-24 17:01:22 +070013struct worktree;
Nguyễn Thái Ngọc Duy504c4d42017-03-18 09:03:11 +070014
Ronnie Sahlbergb416af52014-04-16 15:26:44 -070015/*
Michael Haggertyfb58c8d2015-06-22 16:03:05 +020016 * Resolve a reference, recursively following symbolic refererences.
17 *
René Scharfe54fad662017-09-23 11:41:45 +020018 * Return the name of the non-symbolic reference that ultimately pointed
19 * at the resolved object name. The return value, if not NULL, is a
20 * pointer into either a static buffer or the input ref.
21 *
brian m. carlson49e61472017-10-15 22:07:09 +000022 * If oid is non-NULL, store the referred-to object's name in it.
Michael Haggertyfb58c8d2015-06-22 16:03:05 +020023 *
24 * If the reference cannot be resolved to an object, the behavior
25 * depends on the RESOLVE_REF_READING flag:
26 *
27 * - If RESOLVE_REF_READING is set, return NULL.
28 *
brian m. carlson49e61472017-10-15 22:07:09 +000029 * - If RESOLVE_REF_READING is not set, clear oid and return the name of
Michael Haggertyfb58c8d2015-06-22 16:03:05 +020030 * the last reference name in the chain, which will either be a non-symbolic
31 * reference or an undefined reference. If this is a prelude to
32 * "writing" to the ref, the return value is the name of the ref
33 * that will actually be created or changed.
34 *
35 * If the RESOLVE_REF_NO_RECURSE flag is passed, only resolves one
brian m. carlson49e61472017-10-15 22:07:09 +000036 * level of symbolic reference. The value stored in oid for a symbolic
37 * reference will always be null_oid in this case, and the return
Michael Haggertyfb58c8d2015-06-22 16:03:05 +020038 * value is the reference that the symref refers to directly.
39 *
40 * If flags is non-NULL, set the value that it points to the
41 * combination of REF_ISPACKED (if the reference was found among the
42 * packed references), REF_ISSYMREF (if the initial reference was a
43 * symbolic reference), REF_BAD_NAME (if the reference name is ill
44 * formed --- see RESOLVE_REF_ALLOW_BAD_NAME below), and REF_ISBROKEN
45 * (if the ref is malformed or has a bad name). See refs.h for more detail
46 * on each flag.
47 *
48 * If ref is not a properly-formatted, normalized reference, return
49 * NULL. If more than MAXDEPTH recursive symbolic lookups are needed,
50 * give up and return NULL.
51 *
52 * RESOLVE_REF_ALLOW_BAD_NAME allows resolving refs even when their
53 * name is invalid according to git-check-ref-format(1). If the name
brian m. carlson49e61472017-10-15 22:07:09 +000054 * is bad then the value stored in oid will be null_oid and the two
Michael Haggertyfb58c8d2015-06-22 16:03:05 +020055 * flags REF_ISBROKEN and REF_BAD_NAME will be set.
56 *
57 * Even with RESOLVE_REF_ALLOW_BAD_NAME, names that escape the refs/
58 * directory and do not consist of all caps and underscores cannot be
59 * resolved. The function returns NULL for such ref names.
60 * Caps and underscores refers to the special refs, such as HEAD,
61 * FETCH_HEAD and friends, that all live outside of the refs/ directory.
62 */
63#define RESOLVE_REF_READING 0x01
64#define RESOLVE_REF_NO_RECURSE 0x02
65#define RESOLVE_REF_ALLOW_BAD_NAME 0x04
66
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +070067const char *refs_resolve_ref_unsafe(struct ref_store *refs,
68 const char *refname,
69 int resolve_flags,
brian m. carlson49e61472017-10-15 22:07:09 +000070 struct object_id *oid,
Ævar Arnfjörð Bjarmasonce14de02022-01-26 15:37:01 +010071 int *flags);
Ævar Arnfjörð Bjarmason25a33b32021-10-16 11:39:26 +020072
Michael Haggerty1354c9b2016-03-31 06:19:22 +020073const char *resolve_ref_unsafe(const char *refname, int resolve_flags,
brian m. carlson49e61472017-10-15 22:07:09 +000074 struct object_id *oid, int *flags);
Michael Haggertyfb58c8d2015-06-22 16:03:05 +020075
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +070076char *refs_resolve_refdup(struct ref_store *refs,
77 const char *refname, int resolve_flags,
brian m. carlson0f2dc722017-10-15 22:06:55 +000078 struct object_id *oid, int *flags);
Michael Haggerty1354c9b2016-03-31 06:19:22 +020079char *resolve_refdup(const char *refname, int resolve_flags,
brian m. carlson0f2dc722017-10-15 22:06:55 +000080 struct object_id *oid, int *flags);
Michael Haggertyfb58c8d2015-06-22 16:03:05 +020081
Michael Haggerty1354c9b2016-03-31 06:19:22 +020082int read_ref_full(const char *refname, int resolve_flags,
brian m. carlson34c290a2017-10-15 22:06:56 +000083 struct object_id *oid, int *flags);
84int read_ref(const char *refname, struct object_id *oid);
Michael Haggertyfb58c8d2015-06-22 16:03:05 +020085
Patrick Steinhardtcd475b32022-03-01 10:33:46 +010086int refs_read_symbolic_ref(struct ref_store *ref_store, const char *refname,
87 struct strbuf *referent);
88
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +070089/*
90 * Return 0 if a reference named refname could be created without
91 * conflicting with the name of an existing reference. Otherwise,
92 * return a negative value and write an explanation to err. If extras
93 * is non-NULL, it is a list of additional refnames with which refname
94 * is not allowed to conflict. If skip is non-NULL, ignore potential
95 * conflicts with refs in skip (e.g., because they are scheduled for
96 * deletion in the same operation). Behavior is undefined if the same
97 * name is listed in both extras and skip.
98 *
99 * Two reference names conflict if one of them exactly matches the
100 * leading components of the other; e.g., "foo/bar" conflicts with
101 * both "foo" and with "foo/bar/baz" but not with "foo/bar" or
102 * "foo/barbados".
103 *
104 * extras and skip must be sorted.
105 */
106
107int refs_verify_refname_available(struct ref_store *refs,
108 const char *refname,
Michael Haggertyb05855b2017-04-16 08:41:26 +0200109 const struct string_list *extras,
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +0700110 const struct string_list *skip,
111 struct strbuf *err);
112
Han-Wen Nienhuys3f9f1ac2020-08-21 16:59:34 +0000113int refs_ref_exists(struct ref_store *refs, const char *refname);
114
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200115int ref_exists(const char *refname);
Michael Haggertyfb58c8d2015-06-22 16:03:05 +0200116
Cornelius Weig341fb282017-01-27 11:09:47 +0100117int should_autocreate_reflog(const char *refname);
118
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200119int is_branch(const char *refname);
Michael Haggertyfb58c8d2015-06-22 16:03:05 +0200120
Denton Liu55454422019-04-29 04:28:14 -0400121int refs_init_db(struct strbuf *err);
David Turner6fb5acf2016-09-04 18:08:41 +0200122
Michael Haggertyfb58c8d2015-06-22 16:03:05 +0200123/*
Jeff King36a31792021-01-20 14:44:43 -0500124 * Return the peeled value of the oid currently being iterated via
125 * for_each_ref(), etc. This is equivalent to calling:
126 *
127 * peel_object(oid, &peeled);
128 *
129 * with the "oid" value given to the each_ref_fn callback, except
130 * that some ref storage may be able to answer the query without
131 * actually loading the object in memory.
Michael Haggertyfb58c8d2015-06-22 16:03:05 +0200132 */
Jeff King36a31792021-01-20 14:44:43 -0500133int peel_iterated_oid(const struct object_id *base, struct object_id *peeled);
Michael Haggertyfb58c8d2015-06-22 16:03:05 +0200134
135/**
Michael Haggertya8355bb2016-09-04 18:08:24 +0200136 * Resolve refname in the nested "gitlink" repository in the specified
137 * submodule (which must be non-NULL). If the resolution is
Michael Haggerty78fb4572017-11-05 09:42:09 +0100138 * successful, return 0 and set oid to the name of the object;
Michael Haggertya8355bb2016-09-04 18:08:24 +0200139 * otherwise, return a non-zero value.
Michael Haggertyfb58c8d2015-06-22 16:03:05 +0200140 */
Michael Haggertya8355bb2016-09-04 18:08:24 +0200141int resolve_gitlink_ref(const char *submodule, const char *refname,
brian m. carlsona98e6102017-10-15 22:07:07 +0000142 struct object_id *oid);
Michael Haggertyfb58c8d2015-06-22 16:03:05 +0200143
144/*
145 * Return true iff abbrev_name is a possible abbreviation for
146 * full_name according to the rules defined by ref_rev_parse_rules in
147 * refs.c.
148 */
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200149int refname_match(const char *abbrev_name, const char *full_name);
Michael Haggertyfb58c8d2015-06-22 16:03:05 +0200150
Brandon Williamsb4be7412018-03-15 10:31:24 -0700151/*
152 * Given a 'prefix' expand it by the rules in 'ref_rev_parse_rules' and add
153 * the results to 'prefixes'
154 */
Jeff King873cd282020-07-28 16:23:25 -0400155struct strvec;
156void expand_ref_prefix(struct strvec *prefixes, const char *prefix);
Brandon Williamsb4be7412018-03-15 10:31:24 -0700157
Nguyễn Thái Ngọc Duy0b1dbf52019-04-06 18:34:27 +0700158int expand_ref(struct repository *r, const char *str, int len, struct object_id *oid, char **ref);
Jonathan Tanf24c30e2020-09-01 15:28:09 -0700159int repo_dwim_ref(struct repository *r, const char *str, int len,
160 struct object_id *oid, char **ref, int nonfatal_dangling_mark);
Nguyễn Thái Ngọc Duy56700902019-04-06 18:34:29 +0700161int repo_dwim_log(struct repository *r, const char *str, int len, struct object_id *oid, char **ref);
Jonathan Tanec06b052020-09-01 15:28:08 -0700162static inline int dwim_ref(const char *str, int len, struct object_id *oid,
Jonathan Tanf24c30e2020-09-01 15:28:09 -0700163 char **ref, int nonfatal_dangling_mark)
Jonathan Tanec06b052020-09-01 15:28:08 -0700164{
Jonathan Tanf24c30e2020-09-01 15:28:09 -0700165 return repo_dwim_ref(the_repository, str, len, oid, ref,
166 nonfatal_dangling_mark);
Jonathan Tanec06b052020-09-01 15:28:08 -0700167}
brian m. carlson334dc522017-10-15 22:06:59 +0000168int dwim_log(const char *str, int len, struct object_id *oid, char **ref);
Michael Haggertyfb58c8d2015-06-22 16:03:05 +0200169
170/*
Don Goodman-Wilson8747ebb2020-06-24 14:46:33 +0000171 * Retrieves the default branch name for newly-initialized repositories.
172 *
173 * The return value of `repo_default_branch_name()` is an allocated string. The
174 * return value of `git_default_branch_name()` is a singleton.
175 */
Johannes Schindelincc0f13c2020-12-11 11:36:56 +0000176const char *git_default_branch_name(int quiet);
177char *repo_default_branch_name(struct repository *r, int quiet);
Don Goodman-Wilson8747ebb2020-06-24 14:46:33 +0000178
179/*
Michael Haggerty30173b82017-05-22 16:17:44 +0200180 * A ref_transaction represents a collection of reference updates that
181 * should succeed or fail together.
Ronnie Sahlbergb416af52014-04-16 15:26:44 -0700182 *
183 * Calling sequence
184 * ----------------
Michael Haggerty30173b82017-05-22 16:17:44 +0200185 *
Ronnie Sahlbergb416af52014-04-16 15:26:44 -0700186 * - Allocate and initialize a `struct ref_transaction` by calling
187 * `ref_transaction_begin()`.
188 *
Michael Haggerty30173b82017-05-22 16:17:44 +0200189 * - Specify the intended ref updates by calling one or more of the
190 * following functions:
191 * - `ref_transaction_update()`
192 * - `ref_transaction_create()`
193 * - `ref_transaction_delete()`
194 * - `ref_transaction_verify()`
Ronnie Sahlbergb416af52014-04-16 15:26:44 -0700195 *
Michael Haggerty30173b82017-05-22 16:17:44 +0200196 * - Then either:
Ronnie Sahlbergb416af52014-04-16 15:26:44 -0700197 *
Michael Haggerty30173b82017-05-22 16:17:44 +0200198 * - Optionally call `ref_transaction_prepare()` to prepare the
199 * transaction. This locks all references, checks preconditions,
200 * etc. but doesn't finalize anything. If this step fails, the
201 * transaction has been closed and can only be freed. If this step
202 * succeeds, then `ref_transaction_commit()` is almost certain to
203 * succeed. However, you can still call `ref_transaction_abort()`
204 * if you decide not to commit the transaction after all.
David Turner49386862016-02-25 15:05:46 -0500205 *
Michael Haggerty30173b82017-05-22 16:17:44 +0200206 * - Call `ref_transaction_commit()` to execute the transaction,
207 * make the changes permanent, and release all locks. If you
208 * haven't already called `ref_transaction_prepare()`, then
209 * `ref_transaction_commit()` calls it for you.
210 *
211 * Or
212 *
213 * - Call `initial_ref_transaction_commit()` if the ref database is
214 * known to be empty and have no other writers (e.g. during
215 * clone). This is likely to be much faster than
216 * `ref_transaction_commit()`. `ref_transaction_prepare()` should
217 * *not* be called before `initial_ref_transaction_commit()`.
218 *
219 * - Then finally, call `ref_transaction_free()` to free the
220 * `ref_transaction` data structure.
221 *
222 * At any time before calling `ref_transaction_commit()`, you can call
223 * `ref_transaction_abort()` to abort the transaction, rollback any
224 * locks, and free any associated resources (including the
225 * `ref_transaction` data structure).
226 *
227 * Putting it all together, a complete reference update looks like
228 *
229 * struct ref_transaction *transaction;
230 * struct strbuf err = STRBUF_INIT;
231 * int ret = 0;
232 *
Junio C Hamanoc6da34a2022-04-13 15:51:33 -0700233 * transaction = ref_store_transaction_begin(refs, &err);
Michael Haggerty30173b82017-05-22 16:17:44 +0200234 * if (!transaction ||
235 * ref_transaction_update(...) ||
236 * ref_transaction_create(...) ||
237 * ...etc... ||
238 * ref_transaction_commit(transaction, &err)) {
239 * error("%s", err.buf);
240 * ret = -1;
241 * }
242 * ref_transaction_free(transaction);
243 * strbuf_release(&err);
244 * return ret;
Ronnie Sahlbergb416af52014-04-16 15:26:44 -0700245 *
246 * Error handling
247 * --------------
248 *
249 * On error, transaction functions append a message about what
250 * went wrong to the 'err' argument. The message mentions what
251 * ref was being updated (if any) when the error occurred so it
252 * can be passed to 'die' or 'error' as-is.
253 *
254 * The message is appended to err without first clearing err.
255 * err will not be '\n' terminated.
David Turner49386862016-02-25 15:05:46 -0500256 *
257 * Caveats
258 * -------
259 *
260 * Note that no locks are taken, and no refs are read, until
Michael Haggerty30173b82017-05-22 16:17:44 +0200261 * `ref_transaction_prepare()` or `ref_transaction_commit()` is
262 * called. So, for example, `ref_transaction_verify()` won't report a
263 * verification failure until the commit is attempted.
Ronnie Sahlbergb416af52014-04-16 15:26:44 -0700264 */
Michael Haggertycaa40462014-04-07 15:48:10 +0200265struct ref_transaction;
266
Michael Haggerty89df9c82013-04-14 14:54:16 +0200267/*
Michael Haggerty3bc581b2016-06-18 06:15:15 +0200268 * Bit values set in the flags argument passed to each_ref_fn() and
269 * stored in ref_iterator::flags. Other bits are for internal use
270 * only:
Michael Haggerty89df9c82013-04-14 14:54:16 +0200271 */
272
273/* Reference is a symbolic reference. */
Junio C Hamano98ac34b2011-10-19 13:45:50 -0700274#define REF_ISSYMREF 0x01
Michael Haggerty89df9c82013-04-14 14:54:16 +0200275
276/* Reference is a packed reference. */
Junio C Hamano98ac34b2011-10-19 13:45:50 -0700277#define REF_ISPACKED 0x02
Michael Haggerty89df9c82013-04-14 14:54:16 +0200278
279/*
280 * Reference cannot be resolved to an object name: dangling symbolic
Ronnie Sahlbergd0f810f2014-09-03 11:45:43 -0700281 * reference (directly or indirectly), corrupt reference file,
282 * reference exists but name is bad, or symbolic reference refers to
283 * ill-formatted reference name.
Michael Haggerty89df9c82013-04-14 14:54:16 +0200284 */
Junio C Hamano98ac34b2011-10-19 13:45:50 -0700285#define REF_ISBROKEN 0x04
Junio C Hamanof4204ab2006-11-21 23:36:35 -0800286
Linus Torvalds8a65ff72005-07-02 20:23:36 -0700287/*
Ronnie Sahlbergd0f810f2014-09-03 11:45:43 -0700288 * Reference name is not well formed.
289 *
290 * See git-check-ref-format(1) for the definition of well formed ref names.
291 */
292#define REF_BAD_NAME 0x08
293
294/*
Michael Haggerty4f78c242013-05-25 11:08:24 +0200295 * The signature for the callback function for the for_each_*()
Michael Haggerty78fb4572017-11-05 09:42:09 +0100296 * functions below. The memory pointed to by the refname and oid
Michael Haggerty4f78c242013-05-25 11:08:24 +0200297 * arguments is only guaranteed to be valid for the duration of a
298 * single callback invocation.
Linus Torvalds8a65ff72005-07-02 20:23:36 -0700299 */
Michael Haggerty4f78c242013-05-25 11:08:24 +0200300typedef int each_ref_fn(const char *refname,
Michael Haggerty2b2a5be2015-05-25 18:38:28 +0000301 const struct object_id *oid, int flags, void *cb_data);
302
Michael Haggerty4f78c242013-05-25 11:08:24 +0200303/*
Stefan Beller4a6067c2018-08-20 18:24:16 +0000304 * The same as each_ref_fn, but also with a repository argument that
305 * contains the repository associated with the callback.
306 */
307typedef int each_repo_ref_fn(struct repository *r,
308 const char *refname,
309 const struct object_id *oid,
310 int flags,
311 void *cb_data);
312
313/*
Michael Haggerty4f78c242013-05-25 11:08:24 +0200314 * The following functions invoke the specified callback function for
315 * each reference indicated. If the function ever returns a nonzero
316 * value, stop the iteration and return that value. Please note that
317 * it is not safe to modify references while an iteration is in
318 * progress, unless the same callback function invocation that
319 * modifies the reference also returns a nonzero value to immediately
Nguyễn Thái Ngọc Duyadac8112017-03-26 09:42:41 +0700320 * stop the iteration. Returned references are sorted.
Michael Haggerty4f78c242013-05-25 11:08:24 +0200321 */
Nguyễn Thái Ngọc Duy62f0b392017-08-23 19:36:55 +0700322int refs_head_ref(struct ref_store *refs,
323 each_ref_fn fn, void *cb_data);
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +0700324int refs_for_each_ref(struct ref_store *refs,
325 each_ref_fn fn, void *cb_data);
326int refs_for_each_ref_in(struct ref_store *refs, const char *prefix,
327 each_ref_fn fn, void *cb_data);
328int refs_for_each_tag_ref(struct ref_store *refs,
329 each_ref_fn fn, void *cb_data);
330int refs_for_each_branch_ref(struct ref_store *refs,
331 each_ref_fn fn, void *cb_data);
332int refs_for_each_remote_ref(struct ref_store *refs,
333 each_ref_fn fn, void *cb_data);
334
Heba Waly126c1cc2019-11-17 21:04:46 +0000335/* just iterates the head ref. */
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200336int head_ref(each_ref_fn fn, void *cb_data);
Heba Waly126c1cc2019-11-17 21:04:46 +0000337
338/* iterates all refs. */
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200339int for_each_ref(each_ref_fn fn, void *cb_data);
Heba Waly126c1cc2019-11-17 21:04:46 +0000340
341/**
342 * iterates all refs which have a defined prefix and strips that prefix from
343 * the passed variable refname.
344 */
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200345int for_each_ref_in(const char *prefix, each_ref_fn fn, void *cb_data);
Heba Waly126c1cc2019-11-17 21:04:46 +0000346
Nguyễn Thái Ngọc Duy073cf632017-08-23 19:36:56 +0700347int refs_for_each_fullref_in(struct ref_store *refs, const char *prefix,
Jeff King67985e42021-09-24 14:48:48 -0400348 each_ref_fn fn, void *cb_data);
349int for_each_fullref_in(const char *prefix, each_ref_fn fn, void *cb_data);
Heba Waly126c1cc2019-11-17 21:04:46 +0000350
351/**
Taylor Blau16b19852021-01-20 11:04:21 -0500352 * iterate all refs in "patterns" by partitioning patterns into disjoint sets
353 * and iterating the longest-common prefix of each set.
354 *
355 * callers should be prepared to ignore references that they did not ask for.
356 */
Jeff King91e2ab12022-12-13 06:11:10 -0500357int refs_for_each_fullref_in_prefixes(struct ref_store *refs,
358 const char *namespace, const char **patterns,
359 each_ref_fn fn, void *cb_data);
360
Taylor Blau16b19852021-01-20 11:04:21 -0500361/**
Heba Waly126c1cc2019-11-17 21:04:46 +0000362 * iterate refs from the respective area.
363 */
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200364int for_each_tag_ref(each_ref_fn fn, void *cb_data);
365int for_each_branch_ref(each_ref_fn fn, void *cb_data);
366int for_each_remote_ref(each_ref_fn fn, void *cb_data);
Stefan Beller212e0f72018-08-20 18:24:19 +0000367int for_each_replace_ref(struct repository *r, each_repo_ref_fn fn, void *cb_data);
Heba Waly126c1cc2019-11-17 21:04:46 +0000368
369/* iterates all refs that match the specified glob pattern. */
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200370int for_each_glob_ref(each_ref_fn fn, const char *pattern, void *cb_data);
Heba Waly126c1cc2019-11-17 21:04:46 +0000371
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200372int for_each_glob_ref_in(each_ref_fn fn, const char *pattern,
373 const char *prefix, void *cb_data);
Linus Torvalds8a65ff72005-07-02 20:23:36 -0700374
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200375int head_ref_namespaced(each_ref_fn fn, void *cb_data);
376int for_each_namespaced_ref(each_ref_fn fn, void *cb_data);
Josh Tripletta1bea2c2011-07-05 10:54:44 -0700377
Michael Haggertyfb58c8d2015-06-22 16:03:05 +0200378/* can be used to learn about broken ref and symref */
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +0700379int refs_for_each_rawref(struct ref_store *refs, each_ref_fn fn, void *cb_data);
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200380int for_each_rawref(each_ref_fn fn, void *cb_data);
Michael Haggertyfb58c8d2015-06-22 16:03:05 +0200381
Rafael Ascensão65516f52017-11-21 21:33:41 +0000382/*
383 * Normalizes partial refs to their fully qualified form.
384 * Will prepend <prefix> to the <pattern> if it doesn't start with 'refs/'.
385 * <prefix> will default to 'refs/' if NULL.
386 *
387 * item.string will be set to the result.
388 * item.util will be set to NULL if <pattern> contains glob characters, or
389 * non-NULL if it doesn't.
390 */
391void normalize_glob_ref(struct string_list_item *item, const char *prefix,
392 const char *pattern);
393
Thomas Rast894a9d32010-03-12 18:04:26 +0100394static inline const char *has_glob_specials(const char *pattern)
395{
396 return strpbrk(pattern, "?*[");
397}
398
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200399void warn_dangling_symref(FILE *fp, const char *msg_fmt, const char *refname);
400void warn_dangling_symrefs(FILE *fp, const char *msg_fmt,
401 const struct string_list *refnames);
Junio C Hamanof8948e22009-02-08 23:27:10 -0800402
Daniel Barkalowe142a3c2008-04-27 13:39:24 -0400403/*
Michael Haggerty32d462c2013-04-22 21:52:32 +0200404 * Flags for controlling behaviour of pack_refs()
405 * PACK_REFS_PRUNE: Prune loose refs after packing
406 * PACK_REFS_ALL: Pack _all_ refs, not just tags and already packed refs
407 */
408#define PACK_REFS_PRUNE 0x0001
409#define PACK_REFS_ALL 0x0002
410
411/*
412 * Write a packed-refs file for the current repository.
413 * flags: Combination of the above PACK_REFS_* flags.
414 */
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +0700415int refs_pack_refs(struct ref_store *refs, unsigned int flags);
Michael Haggerty32d462c2013-04-22 21:52:32 +0200416
Ronnie Sahlberg835e3c92014-06-20 07:42:51 -0700417/*
David Turnera4c653d2015-07-21 17:04:50 -0400418 * Setup reflog before using. Fill in err and return -1 on failure.
Ronnie Sahlbergbd3b02d2014-06-20 07:42:50 -0700419 */
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +0700420int refs_create_reflog(struct ref_store *refs, const char *refname,
Han-Wen Nienhuys7b089122021-11-22 14:19:08 +0000421 struct strbuf *err);
422int safe_create_reflog(const char *refname, struct strbuf *err);
Erick Mattos859c3012010-05-21 21:28:36 -0300423
Shawn Pearced556fae2006-05-17 05:56:09 -0400424/** Reads log for the value of ref during at_time. **/
Nguyễn Thái Ngọc Duy7fdff472019-04-06 18:34:30 +0700425int read_ref_at(struct ref_store *refs,
426 const char *refname, unsigned int flags,
Johannes Schindelindddbad72017-04-26 21:29:31 +0200427 timestamp_t at_time, int cnt,
brian m. carlson8eb36d92017-10-15 22:07:03 +0000428 struct object_id *oid, char **msg,
Johannes Schindelindddbad72017-04-26 21:29:31 +0200429 timestamp_t *cutoff_time, int *cutoff_tz, int *cutoff_cnt);
Shawn Pearced556fae2006-05-17 05:56:09 -0400430
Ronnie Sahlberg4da58832014-05-06 15:45:52 -0700431/** Check if a particular reflog exists */
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +0700432int refs_reflog_exists(struct ref_store *refs, const char *refname);
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200433int reflog_exists(const char *refname);
Ronnie Sahlberg4da58832014-05-06 15:45:52 -0700434
Michael Haggertyfc1c2162015-06-22 16:02:52 +0200435/*
brian m. carlson2616a5e2017-10-15 22:06:50 +0000436 * Delete the specified reference. If old_oid is non-NULL, then
Michael Haggerty78fb4572017-11-05 09:42:09 +0100437 * verify that the current value of the reference is old_oid before
brian m. carlson2616a5e2017-10-15 22:06:50 +0000438 * deleting it. If old_oid is NULL, delete the reference if it
439 * exists, regardless of its old value. It is an error for old_oid to
440 * be null_oid. msg and flags are passed through to
Michael Haggerty64da4192017-05-22 16:17:38 +0200441 * ref_transaction_delete().
Michael Haggertyfc1c2162015-06-22 16:02:52 +0200442 */
Nguyễn Thái Ngọc Duyc0fe4e82017-03-26 09:42:35 +0700443int refs_delete_ref(struct ref_store *refs, const char *msg,
444 const char *refname,
brian m. carlson2616a5e2017-10-15 22:06:50 +0000445 const struct object_id *old_oid,
Nguyễn Thái Ngọc Duyc0fe4e82017-03-26 09:42:35 +0700446 unsigned int flags);
Kyle Meyer755b49a2017-02-20 20:10:32 -0500447int delete_ref(const char *msg, const char *refname,
brian m. carlson2616a5e2017-10-15 22:06:50 +0000448 const struct object_id *old_oid, unsigned int flags);
Michael Haggertyfc1c2162015-06-22 16:02:52 +0200449
Michael Haggerty98ffd5f2015-06-22 16:02:55 +0200450/*
451 * Delete the specified references. If there are any problems, emit
452 * errors but attempt to keep going (i.e., the deletes are not done in
Michael Haggerty64da4192017-05-22 16:17:38 +0200453 * an all-or-nothing transaction). msg and flags are passed through to
Michael Haggertyc5f04dd2016-06-18 06:15:10 +0200454 * ref_transaction_delete().
Michael Haggerty98ffd5f2015-06-22 16:02:55 +0200455 */
Michael Haggerty64da4192017-05-22 16:17:38 +0200456int refs_delete_refs(struct ref_store *refs, const char *msg,
457 struct string_list *refnames, unsigned int flags);
458int delete_refs(const char *msg, struct string_list *refnames,
459 unsigned int flags);
Michael Haggerty98ffd5f2015-06-22 16:02:55 +0200460
Ronnie Sahlberg4da58832014-05-06 15:45:52 -0700461/** Delete a reflog */
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +0700462int refs_delete_reflog(struct ref_store *refs, const char *refname);
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200463int delete_reflog(const char *refname);
Ronnie Sahlberg4da58832014-05-06 15:45:52 -0700464
Han-Wen Nienhuysd1eb22d2020-05-20 17:36:07 +0000465/*
466 * Callback to process a reflog entry found by the iteration functions (see
Junio C Hamanoe6e94f32021-11-28 11:25:35 -0800467 * below).
468 *
469 * The committer parameter is a single string, in the form
470 * "$GIT_COMMITTER_NAME <$GIT_COMMITTER_EMAIL>" (without double quotes).
471 *
472 * The timestamp parameter gives the time when entry was created as the number
473 * of seconds since the UNIX epoch.
474 *
475 * The tz parameter gives the timezone offset for the user who created
476 * the reflog entry, and its value gives a positive or negative offset
477 * from UTC. Its absolute value is formed by multiplying the hour
478 * part by 100 and adding the minute part. For example, 1 hour ahead
479 * of UTC, CET == "+0100", is represented as positive one hundred (not
480 * postiive sixty).
481 *
482 * The msg parameter is a single complete line; a reflog message given
483 * to refs_delete_ref, refs_update_ref, etc. is returned to the
484 * callback normalized---each run of whitespaces are squashed into a
485 * single whitespace, trailing whitespace, if exists, is trimmed, and
486 * then a single LF is added at the end.
487 *
488 * The cb_data is a caller-supplied pointer given to the iterator
489 * functions.
Han-Wen Nienhuysd1eb22d2020-05-20 17:36:07 +0000490 */
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200491typedef int each_reflog_ent_fn(
brian m. carlson9461d272017-02-21 23:47:32 +0000492 struct object_id *old_oid, struct object_id *new_oid,
Johannes Schindelindddbad72017-04-26 21:29:31 +0200493 const char *committer, timestamp_t timestamp,
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200494 int tz, const char *msg, void *cb_data);
495
Han-Wen Nienhuysd1eb22d2020-05-20 17:36:07 +0000496/* Iterate over reflog entries in the log for `refname`. */
497
498/* oldest entry first */
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +0700499int refs_for_each_reflog_ent(struct ref_store *refs, const char *refname,
500 each_reflog_ent_fn fn, void *cb_data);
Han-Wen Nienhuysd1eb22d2020-05-20 17:36:07 +0000501
502/* youngest entry first */
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +0700503int refs_for_each_reflog_ent_reverse(struct ref_store *refs,
504 const char *refname,
505 each_reflog_ent_fn fn,
506 void *cb_data);
Han-Wen Nienhuysd1eb22d2020-05-20 17:36:07 +0000507
508/*
509 * Iterate over reflog entries in the log for `refname` in the main ref store.
510 */
511
512/* oldest entry first */
Michael Haggertydfefa932011-12-12 06:38:09 +0100513int for_each_reflog_ent(const char *refname, each_reflog_ent_fn fn, void *cb_data);
Han-Wen Nienhuysd1eb22d2020-05-20 17:36:07 +0000514
515/* youngest entry first */
Junio C Hamano98f85ff2013-03-08 13:27:37 -0800516int for_each_reflog_ent_reverse(const char *refname, each_reflog_ent_fn fn, void *cb_data);
Junio C Hamano2ff81662006-12-18 01:18:16 -0800517
Nicolas Pitreeb8381c2007-02-03 13:25:43 -0500518/*
519 * Calls the specified function for each reflog file until it returns nonzero,
Nguyễn Thái Ngọc Duyadac8112017-03-26 09:42:41 +0700520 * and returns the value. Reflog file order is unspecified.
Nicolas Pitreeb8381c2007-02-03 13:25:43 -0500521 */
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +0700522int refs_for_each_reflog(struct ref_store *refs, each_ref_fn fn, void *cb_data);
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200523int for_each_reflog(each_ref_fn fn, void *cb_data);
Nicolas Pitreeb8381c2007-02-03 13:25:43 -0500524
Michael Haggerty8d9c5012011-09-15 23:10:25 +0200525#define REFNAME_ALLOW_ONELEVEL 1
526#define REFNAME_REFSPEC_PATTERN 2
527
528/*
Michael Haggertydfefa932011-12-12 06:38:09 +0100529 * Return 0 iff refname has the correct format for a refname according
530 * to the rules described in Documentation/git-check-ref-format.txt.
531 * If REFNAME_ALLOW_ONELEVEL is set in flags, then accept one-level
Michael Haggerty8d9c5012011-09-15 23:10:25 +0200532 * reference names. If REFNAME_REFSPEC_PATTERN is set in flags, then
Jacob Kellercd377f42015-07-22 14:05:33 -0700533 * allow a single "*" wildcard character in the refspec. No leading or
534 * repeated slashes are accepted.
Michael Haggerty8d9c5012011-09-15 23:10:25 +0200535 */
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200536int check_refname_format(const char *refname, int flags);
Daniel Barkalow95fc7512005-06-06 16:31:29 -0400537
Nguyễn Thái Ngọc Duy1de16ae2019-03-08 16:28:34 +0700538/*
539 * Apply the rules from check_refname_format, but mutate the result until it
540 * is acceptable, and place the result in "out".
541 */
542void sanitize_refname_component(const char *refname, struct strbuf *out);
543
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200544const char *prettify_refname(const char *refname);
Michael Haggertyfb58c8d2015-06-22 16:03:05 +0200545
Nguyễn Thái Ngọc Duy546edf32019-04-06 18:34:25 +0700546char *refs_shorten_unambiguous_ref(struct ref_store *refs,
547 const char *refname, int strict);
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200548char *shorten_unambiguous_ref(const char *refname, int strict);
Daniel Barkalowa9c37a72009-03-08 21:06:05 -0400549
Lars Hjemlic976d412006-11-28 15:47:40 +0100550/** rename ref, return 0 on success **/
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +0700551int refs_rename_ref(struct ref_store *refs, const char *oldref,
552 const char *newref, const char *logmsg);
Sahil Dua52d59cc2017-06-18 23:19:16 +0200553int rename_ref(const char *oldref, const char *newref,
554 const char *logmsg);
555
556/** copy ref, return 0 on success **/
557int refs_copy_existing_ref(struct ref_store *refs, const char *oldref,
558 const char *newref, const char *logmsg);
559int copy_existing_ref(const char *oldref, const char *newref,
560 const char *logmsg);
Lars Hjemlic976d412006-11-28 15:47:40 +0100561
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +0700562int refs_create_symref(struct ref_store *refs, const char *refname,
563 const char *target, const char *logmsg);
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200564int create_symref(const char *refname, const char *target, const char *logmsg);
Linus Torvalds0ebde322007-04-09 21:14:26 -0700565
Michael Haggertyf4124112014-04-07 15:47:56 +0200566enum action_on_err {
567 UPDATE_REFS_MSG_ON_ERR,
568 UPDATE_REFS_DIE_ON_ERR,
569 UPDATE_REFS_QUIET_ON_ERR
570};
571
Michael Haggertycaa40462014-04-07 15:48:10 +0200572/*
573 * Begin a reference transaction. The reference transaction must
Ronnie Sahlberg33f9fc52014-06-20 07:42:43 -0700574 * be freed by calling ref_transaction_free().
Michael Haggertycaa40462014-04-07 15:48:10 +0200575 */
Nguyễn Thái Ngọc Duyc0fe4e82017-03-26 09:42:35 +0700576struct ref_transaction *ref_store_transaction_begin(struct ref_store *refs,
577 struct strbuf *err);
Ronnie Sahlberg93a644e2014-05-19 10:42:34 -0700578struct ref_transaction *ref_transaction_begin(struct strbuf *err);
Michael Haggertycaa40462014-04-07 15:48:10 +0200579
580/*
Michael Haggertyd1dd7212015-02-17 18:00:23 +0100581 * Reference transaction updates
582 *
583 * The following four functions add a reference check or update to a
584 * ref_transaction. They have some common similar parameters:
585 *
586 * transaction -- a pointer to an open ref_transaction, obtained
587 * from ref_transaction_begin().
588 *
589 * refname -- the name of the reference to be affected.
590 *
Michael Haggerty5ac95fe2017-11-05 09:42:05 +0100591 * new_oid -- the object ID that should be set to be the new value
592 * of the reference. Some functions allow this parameter to be
Michael Haggertyfd2ce9c2017-05-22 16:17:32 +0200593 * NULL, meaning that the reference is not changed, or
Michael Haggerty5ac95fe2017-11-05 09:42:05 +0100594 * null_oid, meaning that the reference should be deleted. A
Michael Haggertyfd2ce9c2017-05-22 16:17:32 +0200595 * copy of this value is made in the transaction.
596 *
Michael Haggerty5ac95fe2017-11-05 09:42:05 +0100597 * old_oid -- the object ID that the reference must have before
Michael Haggertyfd2ce9c2017-05-22 16:17:32 +0200598 * the update. Some functions allow this parameter to be NULL,
599 * meaning that the old value of the reference is not checked,
Michael Haggerty5ac95fe2017-11-05 09:42:05 +0100600 * or null_oid, meaning that the reference must not exist
Michael Haggertyfd2ce9c2017-05-22 16:17:32 +0200601 * before the update. A copy of this value is made in the
602 * transaction.
603 *
Michael Haggertyd1dd7212015-02-17 18:00:23 +0100604 * flags -- flags affecting the update, passed to
Michael Haggerty91774af2017-11-05 09:42:06 +0100605 * update_ref_lock(). Possible flags: REF_NO_DEREF,
Michael Haggerty5ac95fe2017-11-05 09:42:05 +0100606 * REF_FORCE_CREATE_REFLOG. See those constants for more
607 * information.
Michael Haggertyd1dd7212015-02-17 18:00:23 +0100608 *
609 * msg -- a message describing the change (for the reflog).
610 *
611 * err -- a strbuf for receiving a description of any error that
Peter Colbergdc72b502016-06-10 15:05:26 -0400612 * might have occurred.
Michael Haggertyd1dd7212015-02-17 18:00:23 +0100613 *
614 * The functions make internal copies of refname and msg, so the
615 * caller retains ownership of these parameters.
616 *
617 * The functions return 0 on success and non-zero on failure. A
618 * failure means that the transaction as a whole has failed and needs
619 * to be rolled back.
Michael Haggertycaa40462014-04-07 15:48:10 +0200620 */
621
Michael Haggertycaa40462014-04-07 15:48:10 +0200622/*
Michael Haggerty5ac95fe2017-11-05 09:42:05 +0100623 * The following flags can be passed to ref_transaction_update() etc.
624 * Internally, they are stored in `ref_update::flags`, along with some
625 * internal flags.
626 */
627
628/*
629 * Act on the ref directly; i.e., without dereferencing symbolic refs.
630 * If this flag is not specified, then symbolic references are
631 * dereferenced and the update is applied to the referent.
632 */
Michael Haggerty91774af2017-11-05 09:42:06 +0100633#define REF_NO_DEREF (1 << 0)
Michael Haggerty5ac95fe2017-11-05 09:42:05 +0100634
635/*
636 * Force the creation of a reflog for this reference, even if it
637 * didn't previously have a reflog.
638 */
639#define REF_FORCE_CREATE_REFLOG (1 << 1)
640
641/*
Han-Wen Nienhuyse9706a12021-12-07 13:38:17 +0000642 * Blindly write an object_id. This is useful for testing data corruption
643 * scenarios.
644 */
645#define REF_SKIP_OID_VERIFICATION (1 << 10)
646
647/*
Han-Wen Nienhuys3c966c72021-12-07 13:38:18 +0000648 * Skip verifying refname. This is useful for testing data corruption scenarios.
649 */
650#define REF_SKIP_REFNAME_VERIFICATION (1 << 11)
651
652/*
Michael Haggerty5ac95fe2017-11-05 09:42:05 +0100653 * Bitmask of all of the flags that are allowed to be passed in to
654 * ref_transaction_update() and friends:
655 */
Han-Wen Nienhuys3c966c72021-12-07 13:38:18 +0000656#define REF_TRANSACTION_UPDATE_ALLOWED_FLAGS \
657 (REF_NO_DEREF | REF_FORCE_CREATE_REFLOG | REF_SKIP_OID_VERIFICATION | \
658 REF_SKIP_REFNAME_VERIFICATION)
Michael Haggerty5ac95fe2017-11-05 09:42:05 +0100659
660/*
661 * Add a reference update to transaction. `new_oid` is the value that
662 * the reference should have after the update, or `null_oid` if it
663 * should be deleted. If `new_oid` is NULL, then the reference is not
664 * changed at all. `old_oid` is the value that the reference must have
665 * before the update, or `null_oid` if it must not have existed
Michael Haggerty16180332015-02-17 18:00:21 +0100666 * beforehand. The old value is checked after the lock is taken to
brian m. carlson89f3bbd2017-10-15 22:06:53 +0000667 * prevent races. If the old value doesn't agree with old_oid, the
668 * whole transaction fails. If old_oid is NULL, then the previous
Michael Haggerty16180332015-02-17 18:00:21 +0100669 * value is not checked.
670 *
Michael Haggertyd1dd7212015-02-17 18:00:23 +0100671 * See the above comment "Reference transaction updates" for more
672 * information.
Michael Haggertycaa40462014-04-07 15:48:10 +0200673 */
Ronnie Sahlberg8e348002014-06-20 07:43:00 -0700674int ref_transaction_update(struct ref_transaction *transaction,
675 const char *refname,
brian m. carlson89f3bbd2017-10-15 22:06:53 +0000676 const struct object_id *new_oid,
677 const struct object_id *old_oid,
Michael Haggerty1d147bd2015-02-17 18:00:15 +0100678 unsigned int flags, const char *msg,
Ronnie Sahlberg8e348002014-06-20 07:43:00 -0700679 struct strbuf *err);
Michael Haggertycaa40462014-04-07 15:48:10 +0200680
681/*
brian m. carlson89f3bbd2017-10-15 22:06:53 +0000682 * Add a reference creation to transaction. new_oid is the value that
Michael Haggertyd1dd7212015-02-17 18:00:23 +0100683 * the reference should have after the update; it must not be
brian m. carlson89f3bbd2017-10-15 22:06:53 +0000684 * null_oid. It is verified that the reference does not exist
Michael Haggertycaa40462014-04-07 15:48:10 +0200685 * already.
Michael Haggertyd1dd7212015-02-17 18:00:23 +0100686 *
687 * See the above comment "Reference transaction updates" for more
688 * information.
Michael Haggertycaa40462014-04-07 15:48:10 +0200689 */
Ronnie Sahlbergb416af52014-04-16 15:26:44 -0700690int ref_transaction_create(struct ref_transaction *transaction,
691 const char *refname,
brian m. carlson89f3bbd2017-10-15 22:06:53 +0000692 const struct object_id *new_oid,
Michael Haggertyfec14ec2015-02-17 18:00:13 +0100693 unsigned int flags, const char *msg,
Ronnie Sahlbergb416af52014-04-16 15:26:44 -0700694 struct strbuf *err);
Michael Haggertycaa40462014-04-07 15:48:10 +0200695
696/*
brian m. carlson89f3bbd2017-10-15 22:06:53 +0000697 * Add a reference deletion to transaction. If old_oid is non-NULL,
Michael Haggertyd1dd7212015-02-17 18:00:23 +0100698 * then it holds the value that the reference should have had before
brian m. carlson89f3bbd2017-10-15 22:06:53 +0000699 * the update (which must not be null_oid).
Michael Haggertyd1dd7212015-02-17 18:00:23 +0100700 *
701 * See the above comment "Reference transaction updates" for more
702 * information.
Michael Haggertycaa40462014-04-07 15:48:10 +0200703 */
Ronnie Sahlberg8c8bdc02014-04-16 15:27:45 -0700704int ref_transaction_delete(struct ref_transaction *transaction,
705 const char *refname,
brian m. carlson89f3bbd2017-10-15 22:06:53 +0000706 const struct object_id *old_oid,
Michael Haggertyfb5a6bb2015-02-17 18:00:16 +0100707 unsigned int flags, const char *msg,
Ronnie Sahlberg8c8bdc02014-04-16 15:27:45 -0700708 struct strbuf *err);
Michael Haggertycaa40462014-04-07 15:48:10 +0200709
710/*
brian m. carlson89f3bbd2017-10-15 22:06:53 +0000711 * Verify, within a transaction, that refname has the value old_oid,
712 * or, if old_oid is null_oid, then verify that the reference
713 * doesn't exist. old_oid must be non-NULL.
Michael Haggertyd1dd7212015-02-17 18:00:23 +0100714 *
715 * See the above comment "Reference transaction updates" for more
716 * information.
Michael Haggerty16180332015-02-17 18:00:21 +0100717 */
718int ref_transaction_verify(struct ref_transaction *transaction,
719 const char *refname,
brian m. carlson89f3bbd2017-10-15 22:06:53 +0000720 const struct object_id *old_oid,
Michael Haggerty16180332015-02-17 18:00:21 +0100721 unsigned int flags,
722 struct strbuf *err);
723
Ronnie Sahlberg28e6a972014-05-16 14:14:38 -0700724/* Naming conflict (for example, the ref names A and A/B conflict). */
725#define TRANSACTION_NAME_CONFLICT -1
726/* All other errors. */
727#define TRANSACTION_GENERIC_ERROR -2
Michael Haggerty30173b82017-05-22 16:17:44 +0200728
729/*
Ville Skyttä64127572017-06-25 13:20:41 +0300730 * Perform the preparatory stages of committing `transaction`. Acquire
Michael Haggerty30173b82017-05-22 16:17:44 +0200731 * any needed locks, check preconditions, etc.; basically, do as much
732 * as possible to ensure that the transaction will be able to go
733 * through, stopping just short of making any irrevocable or
734 * user-visible changes. The updates that this function prepares can
735 * be finished up by calling `ref_transaction_commit()` or rolled back
736 * by calling `ref_transaction_abort()`.
737 *
738 * On success, return 0 and leave the transaction in "prepared" state.
739 * On failure, abort the transaction, write an error message to `err`,
740 * and return one of the `TRANSACTION_*` constants.
741 *
Ville Skyttä64127572017-06-25 13:20:41 +0300742 * Callers who don't need such fine-grained control over committing
Michael Haggerty30173b82017-05-22 16:17:44 +0200743 * reference transactions should just call `ref_transaction_commit()`.
744 */
745int ref_transaction_prepare(struct ref_transaction *transaction,
746 struct strbuf *err);
747
748/*
749 * Commit all of the changes that have been queued in transaction, as
750 * atomically as possible. On success, return 0 and leave the
751 * transaction in "closed" state. On failure, roll back the
752 * transaction, write an error message to `err`, and return one of the
753 * `TRANSACTION_*` constants
754 */
Michael Haggertycaa40462014-04-07 15:48:10 +0200755int ref_transaction_commit(struct ref_transaction *transaction,
Ronnie Sahlbergdb7516a2014-04-30 12:22:42 -0700756 struct strbuf *err);
Michael Haggertycaa40462014-04-07 15:48:10 +0200757
Ronnie Sahlberg026bd1d2014-06-20 07:42:42 -0700758/*
Michael Haggerty30173b82017-05-22 16:17:44 +0200759 * Abort `transaction`, which has been begun and possibly prepared,
760 * but not yet committed.
761 */
762int ref_transaction_abort(struct ref_transaction *transaction,
763 struct strbuf *err);
764
765/*
Michael Haggerty58f233c2015-06-22 16:03:01 +0200766 * Like ref_transaction_commit(), but optimized for creating
767 * references when originally initializing a repository (e.g., by "git
768 * clone"). It writes the new references directly to packed-refs
769 * without locking the individual references.
770 *
771 * It is a bug to call this function when there might be other
772 * processes accessing the repository or if there are existing
773 * references that might conflict with the ones being created. All
Michael Haggerty78fb4572017-11-05 09:42:09 +0100774 * old_oid values must either be absent or null_oid.
Michael Haggerty58f233c2015-06-22 16:03:01 +0200775 */
776int initial_ref_transaction_commit(struct ref_transaction *transaction,
777 struct strbuf *err);
778
779/*
Patrick Steinhardt4f2ba2d2022-02-17 14:04:32 +0100780 * Execute the given callback function for each of the reference updates which
781 * have been queued in the given transaction. `old_oid` and `new_oid` may be
782 * `NULL` pointers depending on whether the update has these object IDs set or
783 * not.
784 */
785typedef void ref_transaction_for_each_queued_update_fn(const char *refname,
786 const struct object_id *old_oid,
787 const struct object_id *new_oid,
788 void *cb_data);
789void ref_transaction_for_each_queued_update(struct ref_transaction *transaction,
790 ref_transaction_for_each_queued_update_fn cb,
791 void *cb_data);
792
793/*
Michael Haggerty30173b82017-05-22 16:17:44 +0200794 * Free `*transaction` and all associated data.
Ronnie Sahlberg026bd1d2014-06-20 07:42:42 -0700795 */
796void ref_transaction_free(struct ref_transaction *transaction);
797
Michael Haggerty4b7b5202015-02-17 18:00:22 +0100798/**
799 * Lock, update, and unlock a single reference. This function
800 * basically does a transaction containing a single call to
801 * ref_transaction_update(). The parameters to this function have the
802 * same meaning as the corresponding parameters to
803 * ref_transaction_update(). Handle errors as requested by the `onerr`
804 * argument.
805 */
Nguyễn Thái Ngọc Duyc0fe4e82017-03-26 09:42:35 +0700806int refs_update_ref(struct ref_store *refs, const char *msg, const char *refname,
brian m. carlsonae077772017-10-15 22:06:51 +0000807 const struct object_id *new_oid, const struct object_id *old_oid,
Nguyễn Thái Ngọc Duyc0fe4e82017-03-26 09:42:35 +0700808 unsigned int flags, enum action_on_err onerr);
Michael Haggerty4b7b5202015-02-17 18:00:22 +0100809int update_ref(const char *msg, const char *refname,
brian m. carlson8f6dc7e2016-09-05 20:08:08 +0000810 const struct object_id *new_oid, const struct object_id *old_oid,
811 unsigned int flags, enum action_on_err onerr);
Carlos Rica3d9f0372007-09-05 03:38:24 +0200812
Patrick Steinhardt9b67eb62022-11-17 06:46:43 +0100813int parse_hide_refs_config(const char *var, const char *value, const char *,
814 struct string_list *);
Michael Haggertyfb58c8d2015-06-22 16:03:05 +0200815
Lukas Fleischer78a766a2015-11-03 08:58:16 +0100816/*
817 * Check whether a ref is hidden. If no namespace is set, both the first and
818 * the second parameter point to the full ref name. If a namespace is set and
819 * the ref is inside that namespace, the first parameter is a pointer to the
820 * name of the ref with the namespace prefix removed. If a namespace is set and
821 * the ref is outside that namespace, the first parameter is NULL. The second
822 * parameter always points to the full ref name.
823 */
Patrick Steinhardt9b67eb62022-11-17 06:46:43 +0100824int ref_is_hidden(const char *, const char *, const struct string_list *);
Junio C Hamanodaebaa72013-01-18 16:08:30 -0800825
Han-Wen Nienhuys71e54732022-09-19 16:34:50 +0000826/* Is this a per-worktree ref living in the refs/ namespace? */
827int is_per_worktree_ref(const char *refname);
828
829/* Describes how a refname relates to worktrees */
830enum ref_worktree_type {
831 REF_WORKTREE_CURRENT, /* implicitly per worktree, eg. HEAD or
832 refs/bisect/SOMETHING */
833 REF_WORKTREE_MAIN, /* explicitly in main worktree, eg.
834 main-worktree/HEAD */
835 REF_WORKTREE_OTHER, /* explicitly in named worktree, eg.
836 worktrees/bla/HEAD */
837 REF_WORKTREE_SHARED, /* the default, eg. refs/heads/main */
David Turner266b1822015-07-31 02:06:18 -0400838};
839
Han-Wen Nienhuys71e54732022-09-19 16:34:50 +0000840/*
841 * Parse a `maybe_worktree_ref` as a ref that possibly refers to a worktree ref
842 * (ie. either REFNAME, main-worktree/REFNAME or worktree/WORKTREE/REFNAME). It
843 * returns what kind of ref was found, and in case of REF_WORKTREE_OTHER, the
844 * worktree name is returned in `worktree_name` (pointing into
845 * `maybe_worktree_ref`) and `worktree_name_length`. The bare refname (the
846 * refname stripped of prefixes) is returned in `bare_refname`. The
847 * `worktree_name`, `worktree_name_length` and `bare_refname` arguments may be
848 * NULL.
849 */
850enum ref_worktree_type parse_worktree_ref(const char *maybe_worktree_ref,
851 const char **worktree_name,
852 int *worktree_name_length,
853 const char **bare_refname);
David Turner266b1822015-07-31 02:06:18 -0400854
Michael Haggertyfa5b1832014-12-12 09:56:59 +0100855enum expire_reflog_flags {
856 EXPIRE_REFLOGS_DRY_RUN = 1 << 0,
857 EXPIRE_REFLOGS_UPDATE_REF = 1 << 1,
Ævar Arnfjörð Bjarmasonfcd2c3d2021-12-22 05:06:48 +0100858 EXPIRE_REFLOGS_REWRITE = 1 << 2,
Michael Haggertyfa5b1832014-12-12 09:56:59 +0100859};
860
861/*
862 * The following interface is used for reflog expiration. The caller
863 * calls reflog_expire(), supplying it with three callback functions,
864 * of the following types. The callback functions define the
865 * expiration policy that is desired.
866 *
867 * reflog_expiry_prepare_fn -- Called once after the reference is
Ævar Arnfjörð Bjarmasonae35e162021-08-23 13:36:10 +0200868 * locked. Called with the OID of the locked reference.
Michael Haggertyfa5b1832014-12-12 09:56:59 +0100869 *
870 * reflog_expiry_should_prune_fn -- Called once for each entry in the
871 * existing reflog. It should return true iff that entry should be
872 * pruned.
873 *
874 * reflog_expiry_cleanup_fn -- Called once before the reference is
875 * unlocked again.
876 */
877typedef void reflog_expiry_prepare_fn(const char *refname,
brian m. carlson43224782017-05-06 22:10:00 +0000878 const struct object_id *oid,
Michael Haggertyfa5b1832014-12-12 09:56:59 +0100879 void *cb_data);
brian m. carlson43224782017-05-06 22:10:00 +0000880typedef int reflog_expiry_should_prune_fn(struct object_id *ooid,
881 struct object_id *noid,
Michael Haggertyfa5b1832014-12-12 09:56:59 +0100882 const char *email,
Johannes Schindelindddbad72017-04-26 21:29:31 +0200883 timestamp_t timestamp, int tz,
Michael Haggertyfa5b1832014-12-12 09:56:59 +0100884 const char *message, void *cb_data);
885typedef void reflog_expiry_cleanup_fn(void *cb_data);
886
887/*
Ævar Arnfjörð Bjarmasoncc40b5c2021-08-23 13:36:11 +0200888 * Expire reflog entries for the specified reference.
889 * flags is a combination of the constants in
Michael Haggertyfa5b1832014-12-12 09:56:59 +0100890 * enum expire_reflog_flags. The three function pointers are described
891 * above. On success, return zero.
892 */
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +0700893int refs_reflog_expire(struct ref_store *refs,
894 const char *refname,
Nguyễn Thái Ngọc Duy7d2df052017-03-26 09:42:34 +0700895 unsigned int flags,
896 reflog_expiry_prepare_fn prepare_fn,
897 reflog_expiry_should_prune_fn should_prune_fn,
898 reflog_expiry_cleanup_fn cleanup_fn,
899 void *policy_cb_data);
Ævar Arnfjörð Bjarmasoncc40b5c2021-08-23 13:36:11 +0200900int reflog_expire(const char *refname,
Michael Haggerty1354c9b2016-03-31 06:19:22 +0200901 unsigned int flags,
902 reflog_expiry_prepare_fn prepare_fn,
903 reflog_expiry_should_prune_fn should_prune_fn,
904 reflog_expiry_cleanup_fn cleanup_fn,
905 void *policy_cb_data);
Michael Haggertyfa5b1832014-12-12 09:56:59 +0100906
Stefan Beller64a74162018-04-11 17:21:14 -0700907struct ref_store *get_main_ref_store(struct repository *r);
Heba Waly126c1cc2019-11-17 21:04:46 +0000908
909/**
910 * Submodules
911 * ----------
912 *
913 * If you want to iterate the refs of a submodule you first need to add the
914 * submodules object database. You can do this by a code-snippet like
915 * this:
916 *
917 * const char *path = "path/to/submodule"
918 * if (add_submodule_odb(path))
919 * die("Error submodule '%s' not populated.", path);
920 *
921 * `add_submodule_odb()` will return zero on success. If you
922 * do not do this you will get an error for each ref that it does not point
923 * to a valid object.
924 *
925 * Note: As a side-effect of this you cannot safely assume that all
926 * objects you lookup are available in superproject. All submodule objects
927 * will be available the same way as the superprojects objects.
928 *
929 * Example:
930 * --------
931 *
932 * ----
933 * static int handle_remote_ref(const char *refname,
934 * const unsigned char *sha1, int flags, void *cb_data)
935 * {
936 * struct strbuf *output = cb_data;
937 * strbuf_addf(output, "%s\n", refname);
938 * return 0;
939 * }
940 *
941 */
942
Nguyễn Thái Ngọc Duy18d00022017-03-26 09:42:33 +0700943/*
944 * Return the ref_store instance for the specified submodule. For the
945 * main repository, use submodule==NULL; such a call cannot fail. For
946 * a submodule, the submodule must exist and be a nonbare repository,
947 * otherwise return NULL. If the requested reference store has not yet
948 * been initialized, initialize it first.
949 *
950 * For backwards compatibility, submodule=="" is treated the same as
951 * submodule==NULL.
952 */
953struct ref_store *get_submodule_ref_store(const char *submodule);
Nguyễn Thái Ngọc Duy17eff962017-04-24 17:01:22 +0700954struct ref_store *get_worktree_ref_store(const struct worktree *wt);
Nguyễn Thái Ngọc Duy077be782017-03-26 09:42:29 +0700955
Derrick Stoleeb9342b32022-08-05 17:58:36 +0000956/*
957 * Some of the names specified by refs have special meaning to Git.
958 * Organize these namespaces in a comon 'ref_namespace' array for
959 * reference from multiple places in the codebase.
960 */
961
962struct ref_namespace_info {
963 char *ref;
964 enum decoration_type decoration;
965
966 /*
967 * If 'exact' is true, then we must match the 'ref' exactly.
968 * Otherwise, use a prefix match.
969 *
970 * 'ref_updated' is for internal use. It represents whether the
971 * 'ref' value was replaced from its original literal version.
972 */
973 unsigned exact:1,
974 ref_updated:1;
975};
976
977enum ref_namespace {
978 NAMESPACE_HEAD,
979 NAMESPACE_BRANCHES,
980 NAMESPACE_TAGS,
981 NAMESPACE_REMOTE_REFS,
982 NAMESPACE_STASH,
983 NAMESPACE_REPLACE,
984 NAMESPACE_NOTES,
985 NAMESPACE_PREFETCH,
986 NAMESPACE_REWRITTEN,
987
988 /* Must be last */
989 NAMESPACE__COUNT
990};
991
992/* See refs.c for the contents of this array. */
993extern struct ref_namespace_info ref_namespace[NAMESPACE__COUNT];
994
995/*
996 * Some ref namespaces can be modified by config values or environment
997 * variables. Modify a namespace as specified by its ref_namespace key.
998 */
999void update_ref_namespace(enum ref_namespace namespace, char *ref);
1000
Daniel Barkalow95fc7512005-06-06 16:31:29 -04001001#endif /* REFS_H */