Daniel Barkalow | 95fc751 | 2005-06-06 16:31:29 -0400 | [diff] [blame] | 1 | #ifndef REFS_H |
| 2 | #define REFS_H |
| 3 | |
Jonathan Tan | ec06b05 | 2020-09-01 15:28:08 -0700 | [diff] [blame] | 4 | #include "cache.h" |
Derrick Stolee | b9342b3 | 2022-08-05 17:58:36 +0000 | [diff] [blame] | 5 | #include "commit.h" |
Jonathan Tan | ec06b05 | 2020-09-01 15:28:08 -0700 | [diff] [blame] | 6 | |
Nguyễn Thái Ngọc Duy | 504c4d4 | 2017-03-18 09:03:11 +0700 | [diff] [blame] | 7 | struct object_id; |
Nguyễn Thái Ngọc Duy | 077be78 | 2017-03-26 09:42:29 +0700 | [diff] [blame] | 8 | struct ref_store; |
Elijah Newren | ef3ca95 | 2018-08-15 10:54:05 -0700 | [diff] [blame] | 9 | struct repository; |
Nguyễn Thái Ngọc Duy | 504c4d4 | 2017-03-18 09:03:11 +0700 | [diff] [blame] | 10 | struct strbuf; |
| 11 | struct string_list; |
Elijah Newren | ef3ca95 | 2018-08-15 10:54:05 -0700 | [diff] [blame] | 12 | struct string_list_item; |
Nguyễn Thái Ngọc Duy | 17eff96 | 2017-04-24 17:01:22 +0700 | [diff] [blame] | 13 | struct worktree; |
Nguyễn Thái Ngọc Duy | 504c4d4 | 2017-03-18 09:03:11 +0700 | [diff] [blame] | 14 | |
Ronnie Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 15 | /* |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 16 | * Resolve a reference, recursively following symbolic refererences. |
| 17 | * |
René Scharfe | 54fad66 | 2017-09-23 11:41:45 +0200 | [diff] [blame] | 18 | * 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. carlson | 49e6147 | 2017-10-15 22:07:09 +0000 | [diff] [blame] | 22 | * If oid is non-NULL, store the referred-to object's name in it. |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 23 | * |
| 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. carlson | 49e6147 | 2017-10-15 22:07:09 +0000 | [diff] [blame] | 29 | * - If RESOLVE_REF_READING is not set, clear oid and return the name of |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 30 | * 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. carlson | 49e6147 | 2017-10-15 22:07:09 +0000 | [diff] [blame] | 36 | * 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 Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 38 | * 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. carlson | 49e6147 | 2017-10-15 22:07:09 +0000 | [diff] [blame] | 54 | * is bad then the value stored in oid will be null_oid and the two |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 55 | * 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 Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 67 | const char *refs_resolve_ref_unsafe(struct ref_store *refs, |
| 68 | const char *refname, |
| 69 | int resolve_flags, |
brian m. carlson | 49e6147 | 2017-10-15 22:07:09 +0000 | [diff] [blame] | 70 | struct object_id *oid, |
Ævar Arnfjörð Bjarmason | ce14de0 | 2022-01-26 15:37:01 +0100 | [diff] [blame] | 71 | int *flags); |
Ævar Arnfjörð Bjarmason | 25a33b3 | 2021-10-16 11:39:26 +0200 | [diff] [blame] | 72 | |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 73 | const char *resolve_ref_unsafe(const char *refname, int resolve_flags, |
brian m. carlson | 49e6147 | 2017-10-15 22:07:09 +0000 | [diff] [blame] | 74 | struct object_id *oid, int *flags); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 75 | |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 76 | char *refs_resolve_refdup(struct ref_store *refs, |
| 77 | const char *refname, int resolve_flags, |
brian m. carlson | 0f2dc72 | 2017-10-15 22:06:55 +0000 | [diff] [blame] | 78 | struct object_id *oid, int *flags); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 79 | char *resolve_refdup(const char *refname, int resolve_flags, |
brian m. carlson | 0f2dc72 | 2017-10-15 22:06:55 +0000 | [diff] [blame] | 80 | struct object_id *oid, int *flags); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 81 | |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 82 | int read_ref_full(const char *refname, int resolve_flags, |
brian m. carlson | 34c290a | 2017-10-15 22:06:56 +0000 | [diff] [blame] | 83 | struct object_id *oid, int *flags); |
| 84 | int read_ref(const char *refname, struct object_id *oid); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 85 | |
Patrick Steinhardt | cd475b3 | 2022-03-01 10:33:46 +0100 | [diff] [blame] | 86 | int refs_read_symbolic_ref(struct ref_store *ref_store, const char *refname, |
| 87 | struct strbuf *referent); |
| 88 | |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 89 | /* |
| 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 | |
| 107 | int refs_verify_refname_available(struct ref_store *refs, |
| 108 | const char *refname, |
Michael Haggerty | b05855b | 2017-04-16 08:41:26 +0200 | [diff] [blame] | 109 | const struct string_list *extras, |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 110 | const struct string_list *skip, |
| 111 | struct strbuf *err); |
| 112 | |
Han-Wen Nienhuys | 3f9f1ac | 2020-08-21 16:59:34 +0000 | [diff] [blame] | 113 | int refs_ref_exists(struct ref_store *refs, const char *refname); |
| 114 | |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 115 | int ref_exists(const char *refname); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 116 | |
Cornelius Weig | 341fb28 | 2017-01-27 11:09:47 +0100 | [diff] [blame] | 117 | int should_autocreate_reflog(const char *refname); |
| 118 | |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 119 | int is_branch(const char *refname); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 120 | |
Denton Liu | 5545442 | 2019-04-29 04:28:14 -0400 | [diff] [blame] | 121 | int refs_init_db(struct strbuf *err); |
David Turner | 6fb5acf | 2016-09-04 18:08:41 +0200 | [diff] [blame] | 122 | |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 123 | /* |
Jeff King | 36a3179 | 2021-01-20 14:44:43 -0500 | [diff] [blame] | 124 | * 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 Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 132 | */ |
Jeff King | 36a3179 | 2021-01-20 14:44:43 -0500 | [diff] [blame] | 133 | int peel_iterated_oid(const struct object_id *base, struct object_id *peeled); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 134 | |
| 135 | /** |
Michael Haggerty | a8355bb | 2016-09-04 18:08:24 +0200 | [diff] [blame] | 136 | * Resolve refname in the nested "gitlink" repository in the specified |
| 137 | * submodule (which must be non-NULL). If the resolution is |
Michael Haggerty | 78fb457 | 2017-11-05 09:42:09 +0100 | [diff] [blame] | 138 | * successful, return 0 and set oid to the name of the object; |
Michael Haggerty | a8355bb | 2016-09-04 18:08:24 +0200 | [diff] [blame] | 139 | * otherwise, return a non-zero value. |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 140 | */ |
Michael Haggerty | a8355bb | 2016-09-04 18:08:24 +0200 | [diff] [blame] | 141 | int resolve_gitlink_ref(const char *submodule, const char *refname, |
brian m. carlson | a98e610 | 2017-10-15 22:07:07 +0000 | [diff] [blame] | 142 | struct object_id *oid); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 143 | |
| 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 Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 149 | int refname_match(const char *abbrev_name, const char *full_name); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 150 | |
Brandon Williams | b4be741 | 2018-03-15 10:31:24 -0700 | [diff] [blame] | 151 | /* |
| 152 | * Given a 'prefix' expand it by the rules in 'ref_rev_parse_rules' and add |
| 153 | * the results to 'prefixes' |
| 154 | */ |
Jeff King | 873cd28 | 2020-07-28 16:23:25 -0400 | [diff] [blame] | 155 | struct strvec; |
| 156 | void expand_ref_prefix(struct strvec *prefixes, const char *prefix); |
Brandon Williams | b4be741 | 2018-03-15 10:31:24 -0700 | [diff] [blame] | 157 | |
Nguyễn Thái Ngọc Duy | 0b1dbf5 | 2019-04-06 18:34:27 +0700 | [diff] [blame] | 158 | int expand_ref(struct repository *r, const char *str, int len, struct object_id *oid, char **ref); |
Jonathan Tan | f24c30e | 2020-09-01 15:28:09 -0700 | [diff] [blame] | 159 | int 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 Duy | 5670090 | 2019-04-06 18:34:29 +0700 | [diff] [blame] | 161 | int repo_dwim_log(struct repository *r, const char *str, int len, struct object_id *oid, char **ref); |
Jonathan Tan | ec06b05 | 2020-09-01 15:28:08 -0700 | [diff] [blame] | 162 | static inline int dwim_ref(const char *str, int len, struct object_id *oid, |
Jonathan Tan | f24c30e | 2020-09-01 15:28:09 -0700 | [diff] [blame] | 163 | char **ref, int nonfatal_dangling_mark) |
Jonathan Tan | ec06b05 | 2020-09-01 15:28:08 -0700 | [diff] [blame] | 164 | { |
Jonathan Tan | f24c30e | 2020-09-01 15:28:09 -0700 | [diff] [blame] | 165 | return repo_dwim_ref(the_repository, str, len, oid, ref, |
| 166 | nonfatal_dangling_mark); |
Jonathan Tan | ec06b05 | 2020-09-01 15:28:08 -0700 | [diff] [blame] | 167 | } |
brian m. carlson | 334dc52 | 2017-10-15 22:06:59 +0000 | [diff] [blame] | 168 | int dwim_log(const char *str, int len, struct object_id *oid, char **ref); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 169 | |
| 170 | /* |
Don Goodman-Wilson | 8747ebb | 2020-06-24 14:46:33 +0000 | [diff] [blame] | 171 | * 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 Schindelin | cc0f13c | 2020-12-11 11:36:56 +0000 | [diff] [blame] | 176 | const char *git_default_branch_name(int quiet); |
| 177 | char *repo_default_branch_name(struct repository *r, int quiet); |
Don Goodman-Wilson | 8747ebb | 2020-06-24 14:46:33 +0000 | [diff] [blame] | 178 | |
| 179 | /* |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 180 | * A ref_transaction represents a collection of reference updates that |
| 181 | * should succeed or fail together. |
Ronnie Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 182 | * |
| 183 | * Calling sequence |
| 184 | * ---------------- |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 185 | * |
Ronnie Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 186 | * - Allocate and initialize a `struct ref_transaction` by calling |
| 187 | * `ref_transaction_begin()`. |
| 188 | * |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 189 | * - 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 Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 195 | * |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 196 | * - Then either: |
Ronnie Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 197 | * |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 198 | * - 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 Turner | 4938686 | 2016-02-25 15:05:46 -0500 | [diff] [blame] | 205 | * |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 206 | * - 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 Hamano | c6da34a | 2022-04-13 15:51:33 -0700 | [diff] [blame] | 233 | * transaction = ref_store_transaction_begin(refs, &err); |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 234 | * 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 Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 245 | * |
| 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 Turner | 4938686 | 2016-02-25 15:05:46 -0500 | [diff] [blame] | 256 | * |
| 257 | * Caveats |
| 258 | * ------- |
| 259 | * |
| 260 | * Note that no locks are taken, and no refs are read, until |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 261 | * `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 Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 264 | */ |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 265 | struct ref_transaction; |
| 266 | |
Michael Haggerty | 89df9c8 | 2013-04-14 14:54:16 +0200 | [diff] [blame] | 267 | /* |
Michael Haggerty | 3bc581b | 2016-06-18 06:15:15 +0200 | [diff] [blame] | 268 | * 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 Haggerty | 89df9c8 | 2013-04-14 14:54:16 +0200 | [diff] [blame] | 271 | */ |
| 272 | |
| 273 | /* Reference is a symbolic reference. */ |
Junio C Hamano | 98ac34b | 2011-10-19 13:45:50 -0700 | [diff] [blame] | 274 | #define REF_ISSYMREF 0x01 |
Michael Haggerty | 89df9c8 | 2013-04-14 14:54:16 +0200 | [diff] [blame] | 275 | |
| 276 | /* Reference is a packed reference. */ |
Junio C Hamano | 98ac34b | 2011-10-19 13:45:50 -0700 | [diff] [blame] | 277 | #define REF_ISPACKED 0x02 |
Michael Haggerty | 89df9c8 | 2013-04-14 14:54:16 +0200 | [diff] [blame] | 278 | |
| 279 | /* |
| 280 | * Reference cannot be resolved to an object name: dangling symbolic |
Ronnie Sahlberg | d0f810f | 2014-09-03 11:45:43 -0700 | [diff] [blame] | 281 | * 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 Haggerty | 89df9c8 | 2013-04-14 14:54:16 +0200 | [diff] [blame] | 284 | */ |
Junio C Hamano | 98ac34b | 2011-10-19 13:45:50 -0700 | [diff] [blame] | 285 | #define REF_ISBROKEN 0x04 |
Junio C Hamano | f4204ab | 2006-11-21 23:36:35 -0800 | [diff] [blame] | 286 | |
Linus Torvalds | 8a65ff7 | 2005-07-02 20:23:36 -0700 | [diff] [blame] | 287 | /* |
Ronnie Sahlberg | d0f810f | 2014-09-03 11:45:43 -0700 | [diff] [blame] | 288 | * 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 Haggerty | 4f78c24 | 2013-05-25 11:08:24 +0200 | [diff] [blame] | 295 | * The signature for the callback function for the for_each_*() |
Michael Haggerty | 78fb457 | 2017-11-05 09:42:09 +0100 | [diff] [blame] | 296 | * functions below. The memory pointed to by the refname and oid |
Michael Haggerty | 4f78c24 | 2013-05-25 11:08:24 +0200 | [diff] [blame] | 297 | * arguments is only guaranteed to be valid for the duration of a |
| 298 | * single callback invocation. |
Linus Torvalds | 8a65ff7 | 2005-07-02 20:23:36 -0700 | [diff] [blame] | 299 | */ |
Michael Haggerty | 4f78c24 | 2013-05-25 11:08:24 +0200 | [diff] [blame] | 300 | typedef int each_ref_fn(const char *refname, |
Michael Haggerty | 2b2a5be | 2015-05-25 18:38:28 +0000 | [diff] [blame] | 301 | const struct object_id *oid, int flags, void *cb_data); |
| 302 | |
Michael Haggerty | 4f78c24 | 2013-05-25 11:08:24 +0200 | [diff] [blame] | 303 | /* |
Stefan Beller | 4a6067c | 2018-08-20 18:24:16 +0000 | [diff] [blame] | 304 | * The same as each_ref_fn, but also with a repository argument that |
| 305 | * contains the repository associated with the callback. |
| 306 | */ |
| 307 | typedef 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 Haggerty | 4f78c24 | 2013-05-25 11:08:24 +0200 | [diff] [blame] | 314 | * 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 Duy | adac811 | 2017-03-26 09:42:41 +0700 | [diff] [blame] | 320 | * stop the iteration. Returned references are sorted. |
Michael Haggerty | 4f78c24 | 2013-05-25 11:08:24 +0200 | [diff] [blame] | 321 | */ |
Nguyễn Thái Ngọc Duy | 62f0b39 | 2017-08-23 19:36:55 +0700 | [diff] [blame] | 322 | int refs_head_ref(struct ref_store *refs, |
| 323 | each_ref_fn fn, void *cb_data); |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 324 | int refs_for_each_ref(struct ref_store *refs, |
| 325 | each_ref_fn fn, void *cb_data); |
| 326 | int refs_for_each_ref_in(struct ref_store *refs, const char *prefix, |
| 327 | each_ref_fn fn, void *cb_data); |
| 328 | int refs_for_each_tag_ref(struct ref_store *refs, |
| 329 | each_ref_fn fn, void *cb_data); |
| 330 | int refs_for_each_branch_ref(struct ref_store *refs, |
| 331 | each_ref_fn fn, void *cb_data); |
| 332 | int refs_for_each_remote_ref(struct ref_store *refs, |
| 333 | each_ref_fn fn, void *cb_data); |
| 334 | |
Heba Waly | 126c1cc | 2019-11-17 21:04:46 +0000 | [diff] [blame] | 335 | /* just iterates the head ref. */ |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 336 | int head_ref(each_ref_fn fn, void *cb_data); |
Heba Waly | 126c1cc | 2019-11-17 21:04:46 +0000 | [diff] [blame] | 337 | |
| 338 | /* iterates all refs. */ |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 339 | int for_each_ref(each_ref_fn fn, void *cb_data); |
Heba Waly | 126c1cc | 2019-11-17 21:04:46 +0000 | [diff] [blame] | 340 | |
| 341 | /** |
| 342 | * iterates all refs which have a defined prefix and strips that prefix from |
| 343 | * the passed variable refname. |
| 344 | */ |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 345 | int for_each_ref_in(const char *prefix, each_ref_fn fn, void *cb_data); |
Heba Waly | 126c1cc | 2019-11-17 21:04:46 +0000 | [diff] [blame] | 346 | |
Nguyễn Thái Ngọc Duy | 073cf63 | 2017-08-23 19:36:56 +0700 | [diff] [blame] | 347 | int refs_for_each_fullref_in(struct ref_store *refs, const char *prefix, |
Jeff King | 67985e4 | 2021-09-24 14:48:48 -0400 | [diff] [blame] | 348 | each_ref_fn fn, void *cb_data); |
| 349 | int for_each_fullref_in(const char *prefix, each_ref_fn fn, void *cb_data); |
Heba Waly | 126c1cc | 2019-11-17 21:04:46 +0000 | [diff] [blame] | 350 | |
| 351 | /** |
Taylor Blau | 16b1985 | 2021-01-20 11:04:21 -0500 | [diff] [blame] | 352 | * 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 King | 91e2ab1 | 2022-12-13 06:11:10 -0500 | [diff] [blame] | 357 | int 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 Blau | 16b1985 | 2021-01-20 11:04:21 -0500 | [diff] [blame] | 361 | /** |
Heba Waly | 126c1cc | 2019-11-17 21:04:46 +0000 | [diff] [blame] | 362 | * iterate refs from the respective area. |
| 363 | */ |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 364 | int for_each_tag_ref(each_ref_fn fn, void *cb_data); |
| 365 | int for_each_branch_ref(each_ref_fn fn, void *cb_data); |
| 366 | int for_each_remote_ref(each_ref_fn fn, void *cb_data); |
Stefan Beller | 212e0f7 | 2018-08-20 18:24:19 +0000 | [diff] [blame] | 367 | int for_each_replace_ref(struct repository *r, each_repo_ref_fn fn, void *cb_data); |
Heba Waly | 126c1cc | 2019-11-17 21:04:46 +0000 | [diff] [blame] | 368 | |
| 369 | /* iterates all refs that match the specified glob pattern. */ |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 370 | int for_each_glob_ref(each_ref_fn fn, const char *pattern, void *cb_data); |
Heba Waly | 126c1cc | 2019-11-17 21:04:46 +0000 | [diff] [blame] | 371 | |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 372 | int for_each_glob_ref_in(each_ref_fn fn, const char *pattern, |
| 373 | const char *prefix, void *cb_data); |
Linus Torvalds | 8a65ff7 | 2005-07-02 20:23:36 -0700 | [diff] [blame] | 374 | |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 375 | int head_ref_namespaced(each_ref_fn fn, void *cb_data); |
| 376 | int for_each_namespaced_ref(each_ref_fn fn, void *cb_data); |
Josh Triplett | a1bea2c | 2011-07-05 10:54:44 -0700 | [diff] [blame] | 377 | |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 378 | /* can be used to learn about broken ref and symref */ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 379 | int refs_for_each_rawref(struct ref_store *refs, each_ref_fn fn, void *cb_data); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 380 | int for_each_rawref(each_ref_fn fn, void *cb_data); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 381 | |
Rafael Ascensão | 65516f5 | 2017-11-21 21:33:41 +0000 | [diff] [blame] | 382 | /* |
| 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 | */ |
| 391 | void normalize_glob_ref(struct string_list_item *item, const char *prefix, |
| 392 | const char *pattern); |
| 393 | |
Thomas Rast | 894a9d3 | 2010-03-12 18:04:26 +0100 | [diff] [blame] | 394 | static inline const char *has_glob_specials(const char *pattern) |
| 395 | { |
| 396 | return strpbrk(pattern, "?*["); |
| 397 | } |
| 398 | |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 399 | void warn_dangling_symref(FILE *fp, const char *msg_fmt, const char *refname); |
| 400 | void warn_dangling_symrefs(FILE *fp, const char *msg_fmt, |
| 401 | const struct string_list *refnames); |
Junio C Hamano | f8948e2 | 2009-02-08 23:27:10 -0800 | [diff] [blame] | 402 | |
Daniel Barkalow | e142a3c | 2008-04-27 13:39:24 -0400 | [diff] [blame] | 403 | /* |
Michael Haggerty | 32d462c | 2013-04-22 21:52:32 +0200 | [diff] [blame] | 404 | * 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 Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 415 | int refs_pack_refs(struct ref_store *refs, unsigned int flags); |
Michael Haggerty | 32d462c | 2013-04-22 21:52:32 +0200 | [diff] [blame] | 416 | |
Ronnie Sahlberg | 835e3c9 | 2014-06-20 07:42:51 -0700 | [diff] [blame] | 417 | /* |
David Turner | a4c653d | 2015-07-21 17:04:50 -0400 | [diff] [blame] | 418 | * Setup reflog before using. Fill in err and return -1 on failure. |
Ronnie Sahlberg | bd3b02d | 2014-06-20 07:42:50 -0700 | [diff] [blame] | 419 | */ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 420 | int refs_create_reflog(struct ref_store *refs, const char *refname, |
Han-Wen Nienhuys | 7b08912 | 2021-11-22 14:19:08 +0000 | [diff] [blame] | 421 | struct strbuf *err); |
| 422 | int safe_create_reflog(const char *refname, struct strbuf *err); |
Erick Mattos | 859c301 | 2010-05-21 21:28:36 -0300 | [diff] [blame] | 423 | |
Shawn Pearce | d556fae | 2006-05-17 05:56:09 -0400 | [diff] [blame] | 424 | /** Reads log for the value of ref during at_time. **/ |
Nguyễn Thái Ngọc Duy | 7fdff47 | 2019-04-06 18:34:30 +0700 | [diff] [blame] | 425 | int read_ref_at(struct ref_store *refs, |
| 426 | const char *refname, unsigned int flags, |
Johannes Schindelin | dddbad7 | 2017-04-26 21:29:31 +0200 | [diff] [blame] | 427 | timestamp_t at_time, int cnt, |
brian m. carlson | 8eb36d9 | 2017-10-15 22:07:03 +0000 | [diff] [blame] | 428 | struct object_id *oid, char **msg, |
Johannes Schindelin | dddbad7 | 2017-04-26 21:29:31 +0200 | [diff] [blame] | 429 | timestamp_t *cutoff_time, int *cutoff_tz, int *cutoff_cnt); |
Shawn Pearce | d556fae | 2006-05-17 05:56:09 -0400 | [diff] [blame] | 430 | |
Ronnie Sahlberg | 4da5883 | 2014-05-06 15:45:52 -0700 | [diff] [blame] | 431 | /** Check if a particular reflog exists */ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 432 | int refs_reflog_exists(struct ref_store *refs, const char *refname); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 433 | int reflog_exists(const char *refname); |
Ronnie Sahlberg | 4da5883 | 2014-05-06 15:45:52 -0700 | [diff] [blame] | 434 | |
Michael Haggerty | fc1c216 | 2015-06-22 16:02:52 +0200 | [diff] [blame] | 435 | /* |
brian m. carlson | 2616a5e | 2017-10-15 22:06:50 +0000 | [diff] [blame] | 436 | * Delete the specified reference. If old_oid is non-NULL, then |
Michael Haggerty | 78fb457 | 2017-11-05 09:42:09 +0100 | [diff] [blame] | 437 | * verify that the current value of the reference is old_oid before |
brian m. carlson | 2616a5e | 2017-10-15 22:06:50 +0000 | [diff] [blame] | 438 | * 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 Haggerty | 64da419 | 2017-05-22 16:17:38 +0200 | [diff] [blame] | 441 | * ref_transaction_delete(). |
Michael Haggerty | fc1c216 | 2015-06-22 16:02:52 +0200 | [diff] [blame] | 442 | */ |
Nguyễn Thái Ngọc Duy | c0fe4e8 | 2017-03-26 09:42:35 +0700 | [diff] [blame] | 443 | int refs_delete_ref(struct ref_store *refs, const char *msg, |
| 444 | const char *refname, |
brian m. carlson | 2616a5e | 2017-10-15 22:06:50 +0000 | [diff] [blame] | 445 | const struct object_id *old_oid, |
Nguyễn Thái Ngọc Duy | c0fe4e8 | 2017-03-26 09:42:35 +0700 | [diff] [blame] | 446 | unsigned int flags); |
Kyle Meyer | 755b49a | 2017-02-20 20:10:32 -0500 | [diff] [blame] | 447 | int delete_ref(const char *msg, const char *refname, |
brian m. carlson | 2616a5e | 2017-10-15 22:06:50 +0000 | [diff] [blame] | 448 | const struct object_id *old_oid, unsigned int flags); |
Michael Haggerty | fc1c216 | 2015-06-22 16:02:52 +0200 | [diff] [blame] | 449 | |
Michael Haggerty | 98ffd5f | 2015-06-22 16:02:55 +0200 | [diff] [blame] | 450 | /* |
| 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 Haggerty | 64da419 | 2017-05-22 16:17:38 +0200 | [diff] [blame] | 453 | * an all-or-nothing transaction). msg and flags are passed through to |
Michael Haggerty | c5f04dd | 2016-06-18 06:15:10 +0200 | [diff] [blame] | 454 | * ref_transaction_delete(). |
Michael Haggerty | 98ffd5f | 2015-06-22 16:02:55 +0200 | [diff] [blame] | 455 | */ |
Michael Haggerty | 64da419 | 2017-05-22 16:17:38 +0200 | [diff] [blame] | 456 | int refs_delete_refs(struct ref_store *refs, const char *msg, |
| 457 | struct string_list *refnames, unsigned int flags); |
| 458 | int delete_refs(const char *msg, struct string_list *refnames, |
| 459 | unsigned int flags); |
Michael Haggerty | 98ffd5f | 2015-06-22 16:02:55 +0200 | [diff] [blame] | 460 | |
Ronnie Sahlberg | 4da5883 | 2014-05-06 15:45:52 -0700 | [diff] [blame] | 461 | /** Delete a reflog */ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 462 | int refs_delete_reflog(struct ref_store *refs, const char *refname); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 463 | int delete_reflog(const char *refname); |
Ronnie Sahlberg | 4da5883 | 2014-05-06 15:45:52 -0700 | [diff] [blame] | 464 | |
Han-Wen Nienhuys | d1eb22d | 2020-05-20 17:36:07 +0000 | [diff] [blame] | 465 | /* |
| 466 | * Callback to process a reflog entry found by the iteration functions (see |
Junio C Hamano | e6e94f3 | 2021-11-28 11:25:35 -0800 | [diff] [blame] | 467 | * 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 Nienhuys | d1eb22d | 2020-05-20 17:36:07 +0000 | [diff] [blame] | 490 | */ |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 491 | typedef int each_reflog_ent_fn( |
brian m. carlson | 9461d27 | 2017-02-21 23:47:32 +0000 | [diff] [blame] | 492 | struct object_id *old_oid, struct object_id *new_oid, |
Johannes Schindelin | dddbad7 | 2017-04-26 21:29:31 +0200 | [diff] [blame] | 493 | const char *committer, timestamp_t timestamp, |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 494 | int tz, const char *msg, void *cb_data); |
| 495 | |
Han-Wen Nienhuys | d1eb22d | 2020-05-20 17:36:07 +0000 | [diff] [blame] | 496 | /* Iterate over reflog entries in the log for `refname`. */ |
| 497 | |
| 498 | /* oldest entry first */ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 499 | int refs_for_each_reflog_ent(struct ref_store *refs, const char *refname, |
| 500 | each_reflog_ent_fn fn, void *cb_data); |
Han-Wen Nienhuys | d1eb22d | 2020-05-20 17:36:07 +0000 | [diff] [blame] | 501 | |
| 502 | /* youngest entry first */ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 503 | int 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 Nienhuys | d1eb22d | 2020-05-20 17:36:07 +0000 | [diff] [blame] | 507 | |
| 508 | /* |
| 509 | * Iterate over reflog entries in the log for `refname` in the main ref store. |
| 510 | */ |
| 511 | |
| 512 | /* oldest entry first */ |
Michael Haggerty | dfefa93 | 2011-12-12 06:38:09 +0100 | [diff] [blame] | 513 | int for_each_reflog_ent(const char *refname, each_reflog_ent_fn fn, void *cb_data); |
Han-Wen Nienhuys | d1eb22d | 2020-05-20 17:36:07 +0000 | [diff] [blame] | 514 | |
| 515 | /* youngest entry first */ |
Junio C Hamano | 98f85ff | 2013-03-08 13:27:37 -0800 | [diff] [blame] | 516 | int for_each_reflog_ent_reverse(const char *refname, each_reflog_ent_fn fn, void *cb_data); |
Junio C Hamano | 2ff8166 | 2006-12-18 01:18:16 -0800 | [diff] [blame] | 517 | |
Nicolas Pitre | eb8381c | 2007-02-03 13:25:43 -0500 | [diff] [blame] | 518 | /* |
| 519 | * Calls the specified function for each reflog file until it returns nonzero, |
Nguyễn Thái Ngọc Duy | adac811 | 2017-03-26 09:42:41 +0700 | [diff] [blame] | 520 | * and returns the value. Reflog file order is unspecified. |
Nicolas Pitre | eb8381c | 2007-02-03 13:25:43 -0500 | [diff] [blame] | 521 | */ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 522 | int refs_for_each_reflog(struct ref_store *refs, each_ref_fn fn, void *cb_data); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 523 | int for_each_reflog(each_ref_fn fn, void *cb_data); |
Nicolas Pitre | eb8381c | 2007-02-03 13:25:43 -0500 | [diff] [blame] | 524 | |
Michael Haggerty | 8d9c501 | 2011-09-15 23:10:25 +0200 | [diff] [blame] | 525 | #define REFNAME_ALLOW_ONELEVEL 1 |
| 526 | #define REFNAME_REFSPEC_PATTERN 2 |
| 527 | |
| 528 | /* |
Michael Haggerty | dfefa93 | 2011-12-12 06:38:09 +0100 | [diff] [blame] | 529 | * 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 Haggerty | 8d9c501 | 2011-09-15 23:10:25 +0200 | [diff] [blame] | 532 | * reference names. If REFNAME_REFSPEC_PATTERN is set in flags, then |
Jacob Keller | cd377f4 | 2015-07-22 14:05:33 -0700 | [diff] [blame] | 533 | * allow a single "*" wildcard character in the refspec. No leading or |
| 534 | * repeated slashes are accepted. |
Michael Haggerty | 8d9c501 | 2011-09-15 23:10:25 +0200 | [diff] [blame] | 535 | */ |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 536 | int check_refname_format(const char *refname, int flags); |
Daniel Barkalow | 95fc751 | 2005-06-06 16:31:29 -0400 | [diff] [blame] | 537 | |
Nguyễn Thái Ngọc Duy | 1de16ae | 2019-03-08 16:28:34 +0700 | [diff] [blame] | 538 | /* |
| 539 | * Apply the rules from check_refname_format, but mutate the result until it |
| 540 | * is acceptable, and place the result in "out". |
| 541 | */ |
| 542 | void sanitize_refname_component(const char *refname, struct strbuf *out); |
| 543 | |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 544 | const char *prettify_refname(const char *refname); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 545 | |
Nguyễn Thái Ngọc Duy | 546edf3 | 2019-04-06 18:34:25 +0700 | [diff] [blame] | 546 | char *refs_shorten_unambiguous_ref(struct ref_store *refs, |
| 547 | const char *refname, int strict); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 548 | char *shorten_unambiguous_ref(const char *refname, int strict); |
Daniel Barkalow | a9c37a7 | 2009-03-08 21:06:05 -0400 | [diff] [blame] | 549 | |
Lars Hjemli | c976d41 | 2006-11-28 15:47:40 +0100 | [diff] [blame] | 550 | /** rename ref, return 0 on success **/ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 551 | int refs_rename_ref(struct ref_store *refs, const char *oldref, |
| 552 | const char *newref, const char *logmsg); |
Sahil Dua | 52d59cc | 2017-06-18 23:19:16 +0200 | [diff] [blame] | 553 | int rename_ref(const char *oldref, const char *newref, |
| 554 | const char *logmsg); |
| 555 | |
| 556 | /** copy ref, return 0 on success **/ |
| 557 | int refs_copy_existing_ref(struct ref_store *refs, const char *oldref, |
| 558 | const char *newref, const char *logmsg); |
| 559 | int copy_existing_ref(const char *oldref, const char *newref, |
| 560 | const char *logmsg); |
Lars Hjemli | c976d41 | 2006-11-28 15:47:40 +0100 | [diff] [blame] | 561 | |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 562 | int refs_create_symref(struct ref_store *refs, const char *refname, |
| 563 | const char *target, const char *logmsg); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 564 | int create_symref(const char *refname, const char *target, const char *logmsg); |
Linus Torvalds | 0ebde32 | 2007-04-09 21:14:26 -0700 | [diff] [blame] | 565 | |
Michael Haggerty | f412411 | 2014-04-07 15:47:56 +0200 | [diff] [blame] | 566 | enum action_on_err { |
| 567 | UPDATE_REFS_MSG_ON_ERR, |
| 568 | UPDATE_REFS_DIE_ON_ERR, |
| 569 | UPDATE_REFS_QUIET_ON_ERR |
| 570 | }; |
| 571 | |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 572 | /* |
| 573 | * Begin a reference transaction. The reference transaction must |
Ronnie Sahlberg | 33f9fc5 | 2014-06-20 07:42:43 -0700 | [diff] [blame] | 574 | * be freed by calling ref_transaction_free(). |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 575 | */ |
Nguyễn Thái Ngọc Duy | c0fe4e8 | 2017-03-26 09:42:35 +0700 | [diff] [blame] | 576 | struct ref_transaction *ref_store_transaction_begin(struct ref_store *refs, |
| 577 | struct strbuf *err); |
Ronnie Sahlberg | 93a644e | 2014-05-19 10:42:34 -0700 | [diff] [blame] | 578 | struct ref_transaction *ref_transaction_begin(struct strbuf *err); |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 579 | |
| 580 | /* |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 581 | * 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 Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 591 | * 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 Haggerty | fd2ce9c | 2017-05-22 16:17:32 +0200 | [diff] [blame] | 593 | * NULL, meaning that the reference is not changed, or |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 594 | * null_oid, meaning that the reference should be deleted. A |
Michael Haggerty | fd2ce9c | 2017-05-22 16:17:32 +0200 | [diff] [blame] | 595 | * copy of this value is made in the transaction. |
| 596 | * |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 597 | * old_oid -- the object ID that the reference must have before |
Michael Haggerty | fd2ce9c | 2017-05-22 16:17:32 +0200 | [diff] [blame] | 598 | * the update. Some functions allow this parameter to be NULL, |
| 599 | * meaning that the old value of the reference is not checked, |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 600 | * or null_oid, meaning that the reference must not exist |
Michael Haggerty | fd2ce9c | 2017-05-22 16:17:32 +0200 | [diff] [blame] | 601 | * before the update. A copy of this value is made in the |
| 602 | * transaction. |
| 603 | * |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 604 | * flags -- flags affecting the update, passed to |
Michael Haggerty | 91774af | 2017-11-05 09:42:06 +0100 | [diff] [blame] | 605 | * update_ref_lock(). Possible flags: REF_NO_DEREF, |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 606 | * REF_FORCE_CREATE_REFLOG. See those constants for more |
| 607 | * information. |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 608 | * |
| 609 | * msg -- a message describing the change (for the reflog). |
| 610 | * |
| 611 | * err -- a strbuf for receiving a description of any error that |
Peter Colberg | dc72b50 | 2016-06-10 15:05:26 -0400 | [diff] [blame] | 612 | * might have occurred. |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 613 | * |
| 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 Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 620 | */ |
| 621 | |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 622 | /* |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 623 | * 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 Haggerty | 91774af | 2017-11-05 09:42:06 +0100 | [diff] [blame] | 633 | #define REF_NO_DEREF (1 << 0) |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 634 | |
| 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 Nienhuys | e9706a1 | 2021-12-07 13:38:17 +0000 | [diff] [blame] | 642 | * 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 Nienhuys | 3c966c7 | 2021-12-07 13:38:18 +0000 | [diff] [blame] | 648 | * Skip verifying refname. This is useful for testing data corruption scenarios. |
| 649 | */ |
| 650 | #define REF_SKIP_REFNAME_VERIFICATION (1 << 11) |
| 651 | |
| 652 | /* |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 653 | * Bitmask of all of the flags that are allowed to be passed in to |
| 654 | * ref_transaction_update() and friends: |
| 655 | */ |
Han-Wen Nienhuys | 3c966c7 | 2021-12-07 13:38:18 +0000 | [diff] [blame] | 656 | #define REF_TRANSACTION_UPDATE_ALLOWED_FLAGS \ |
| 657 | (REF_NO_DEREF | REF_FORCE_CREATE_REFLOG | REF_SKIP_OID_VERIFICATION | \ |
| 658 | REF_SKIP_REFNAME_VERIFICATION) |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 659 | |
| 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 Haggerty | 1618033 | 2015-02-17 18:00:21 +0100 | [diff] [blame] | 666 | * beforehand. The old value is checked after the lock is taken to |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 667 | * 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 Haggerty | 1618033 | 2015-02-17 18:00:21 +0100 | [diff] [blame] | 669 | * value is not checked. |
| 670 | * |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 671 | * See the above comment "Reference transaction updates" for more |
| 672 | * information. |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 673 | */ |
Ronnie Sahlberg | 8e34800 | 2014-06-20 07:43:00 -0700 | [diff] [blame] | 674 | int ref_transaction_update(struct ref_transaction *transaction, |
| 675 | const char *refname, |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 676 | const struct object_id *new_oid, |
| 677 | const struct object_id *old_oid, |
Michael Haggerty | 1d147bd | 2015-02-17 18:00:15 +0100 | [diff] [blame] | 678 | unsigned int flags, const char *msg, |
Ronnie Sahlberg | 8e34800 | 2014-06-20 07:43:00 -0700 | [diff] [blame] | 679 | struct strbuf *err); |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 680 | |
| 681 | /* |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 682 | * Add a reference creation to transaction. new_oid is the value that |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 683 | * the reference should have after the update; it must not be |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 684 | * null_oid. It is verified that the reference does not exist |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 685 | * already. |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 686 | * |
| 687 | * See the above comment "Reference transaction updates" for more |
| 688 | * information. |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 689 | */ |
Ronnie Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 690 | int ref_transaction_create(struct ref_transaction *transaction, |
| 691 | const char *refname, |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 692 | const struct object_id *new_oid, |
Michael Haggerty | fec14ec | 2015-02-17 18:00:13 +0100 | [diff] [blame] | 693 | unsigned int flags, const char *msg, |
Ronnie Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 694 | struct strbuf *err); |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 695 | |
| 696 | /* |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 697 | * Add a reference deletion to transaction. If old_oid is non-NULL, |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 698 | * then it holds the value that the reference should have had before |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 699 | * the update (which must not be null_oid). |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 700 | * |
| 701 | * See the above comment "Reference transaction updates" for more |
| 702 | * information. |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 703 | */ |
Ronnie Sahlberg | 8c8bdc0 | 2014-04-16 15:27:45 -0700 | [diff] [blame] | 704 | int ref_transaction_delete(struct ref_transaction *transaction, |
| 705 | const char *refname, |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 706 | const struct object_id *old_oid, |
Michael Haggerty | fb5a6bb | 2015-02-17 18:00:16 +0100 | [diff] [blame] | 707 | unsigned int flags, const char *msg, |
Ronnie Sahlberg | 8c8bdc0 | 2014-04-16 15:27:45 -0700 | [diff] [blame] | 708 | struct strbuf *err); |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 709 | |
| 710 | /* |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 711 | * 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 Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 714 | * |
| 715 | * See the above comment "Reference transaction updates" for more |
| 716 | * information. |
Michael Haggerty | 1618033 | 2015-02-17 18:00:21 +0100 | [diff] [blame] | 717 | */ |
| 718 | int ref_transaction_verify(struct ref_transaction *transaction, |
| 719 | const char *refname, |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 720 | const struct object_id *old_oid, |
Michael Haggerty | 1618033 | 2015-02-17 18:00:21 +0100 | [diff] [blame] | 721 | unsigned int flags, |
| 722 | struct strbuf *err); |
| 723 | |
Ronnie Sahlberg | 28e6a97 | 2014-05-16 14:14:38 -0700 | [diff] [blame] | 724 | /* 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 Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 728 | |
| 729 | /* |
Ville Skyttä | 6412757 | 2017-06-25 13:20:41 +0300 | [diff] [blame] | 730 | * Perform the preparatory stages of committing `transaction`. Acquire |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 731 | * 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ä | 6412757 | 2017-06-25 13:20:41 +0300 | [diff] [blame] | 742 | * Callers who don't need such fine-grained control over committing |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 743 | * reference transactions should just call `ref_transaction_commit()`. |
| 744 | */ |
| 745 | int 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 Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 755 | int ref_transaction_commit(struct ref_transaction *transaction, |
Ronnie Sahlberg | db7516a | 2014-04-30 12:22:42 -0700 | [diff] [blame] | 756 | struct strbuf *err); |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 757 | |
Ronnie Sahlberg | 026bd1d | 2014-06-20 07:42:42 -0700 | [diff] [blame] | 758 | /* |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 759 | * Abort `transaction`, which has been begun and possibly prepared, |
| 760 | * but not yet committed. |
| 761 | */ |
| 762 | int ref_transaction_abort(struct ref_transaction *transaction, |
| 763 | struct strbuf *err); |
| 764 | |
| 765 | /* |
Michael Haggerty | 58f233c | 2015-06-22 16:03:01 +0200 | [diff] [blame] | 766 | * 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 Haggerty | 78fb457 | 2017-11-05 09:42:09 +0100 | [diff] [blame] | 774 | * old_oid values must either be absent or null_oid. |
Michael Haggerty | 58f233c | 2015-06-22 16:03:01 +0200 | [diff] [blame] | 775 | */ |
| 776 | int initial_ref_transaction_commit(struct ref_transaction *transaction, |
| 777 | struct strbuf *err); |
| 778 | |
| 779 | /* |
Patrick Steinhardt | 4f2ba2d | 2022-02-17 14:04:32 +0100 | [diff] [blame] | 780 | * 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 | */ |
| 785 | typedef 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); |
| 789 | void 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 Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 794 | * Free `*transaction` and all associated data. |
Ronnie Sahlberg | 026bd1d | 2014-06-20 07:42:42 -0700 | [diff] [blame] | 795 | */ |
| 796 | void ref_transaction_free(struct ref_transaction *transaction); |
| 797 | |
Michael Haggerty | 4b7b520 | 2015-02-17 18:00:22 +0100 | [diff] [blame] | 798 | /** |
| 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 Duy | c0fe4e8 | 2017-03-26 09:42:35 +0700 | [diff] [blame] | 806 | int refs_update_ref(struct ref_store *refs, const char *msg, const char *refname, |
brian m. carlson | ae07777 | 2017-10-15 22:06:51 +0000 | [diff] [blame] | 807 | const struct object_id *new_oid, const struct object_id *old_oid, |
Nguyễn Thái Ngọc Duy | c0fe4e8 | 2017-03-26 09:42:35 +0700 | [diff] [blame] | 808 | unsigned int flags, enum action_on_err onerr); |
Michael Haggerty | 4b7b520 | 2015-02-17 18:00:22 +0100 | [diff] [blame] | 809 | int update_ref(const char *msg, const char *refname, |
brian m. carlson | 8f6dc7e | 2016-09-05 20:08:08 +0000 | [diff] [blame] | 810 | const struct object_id *new_oid, const struct object_id *old_oid, |
| 811 | unsigned int flags, enum action_on_err onerr); |
Carlos Rica | 3d9f037 | 2007-09-05 03:38:24 +0200 | [diff] [blame] | 812 | |
Patrick Steinhardt | 9b67eb6 | 2022-11-17 06:46:43 +0100 | [diff] [blame] | 813 | int parse_hide_refs_config(const char *var, const char *value, const char *, |
| 814 | struct string_list *); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 815 | |
Lukas Fleischer | 78a766a | 2015-11-03 08:58:16 +0100 | [diff] [blame] | 816 | /* |
| 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 Steinhardt | 9b67eb6 | 2022-11-17 06:46:43 +0100 | [diff] [blame] | 824 | int ref_is_hidden(const char *, const char *, const struct string_list *); |
Junio C Hamano | daebaa7 | 2013-01-18 16:08:30 -0800 | [diff] [blame] | 825 | |
Han-Wen Nienhuys | 71e5473 | 2022-09-19 16:34:50 +0000 | [diff] [blame] | 826 | /* Is this a per-worktree ref living in the refs/ namespace? */ |
| 827 | int is_per_worktree_ref(const char *refname); |
| 828 | |
| 829 | /* Describes how a refname relates to worktrees */ |
| 830 | enum 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 Turner | 266b182 | 2015-07-31 02:06:18 -0400 | [diff] [blame] | 838 | }; |
| 839 | |
Han-Wen Nienhuys | 71e5473 | 2022-09-19 16:34:50 +0000 | [diff] [blame] | 840 | /* |
| 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 | */ |
| 850 | enum 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 Turner | 266b182 | 2015-07-31 02:06:18 -0400 | [diff] [blame] | 854 | |
Michael Haggerty | fa5b183 | 2014-12-12 09:56:59 +0100 | [diff] [blame] | 855 | enum expire_reflog_flags { |
| 856 | EXPIRE_REFLOGS_DRY_RUN = 1 << 0, |
| 857 | EXPIRE_REFLOGS_UPDATE_REF = 1 << 1, |
Ævar Arnfjörð Bjarmason | fcd2c3d | 2021-12-22 05:06:48 +0100 | [diff] [blame] | 858 | EXPIRE_REFLOGS_REWRITE = 1 << 2, |
Michael Haggerty | fa5b183 | 2014-12-12 09:56:59 +0100 | [diff] [blame] | 859 | }; |
| 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ð Bjarmason | ae35e16 | 2021-08-23 13:36:10 +0200 | [diff] [blame] | 868 | * locked. Called with the OID of the locked reference. |
Michael Haggerty | fa5b183 | 2014-12-12 09:56:59 +0100 | [diff] [blame] | 869 | * |
| 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 | */ |
| 877 | typedef void reflog_expiry_prepare_fn(const char *refname, |
brian m. carlson | 4322478 | 2017-05-06 22:10:00 +0000 | [diff] [blame] | 878 | const struct object_id *oid, |
Michael Haggerty | fa5b183 | 2014-12-12 09:56:59 +0100 | [diff] [blame] | 879 | void *cb_data); |
brian m. carlson | 4322478 | 2017-05-06 22:10:00 +0000 | [diff] [blame] | 880 | typedef int reflog_expiry_should_prune_fn(struct object_id *ooid, |
| 881 | struct object_id *noid, |
Michael Haggerty | fa5b183 | 2014-12-12 09:56:59 +0100 | [diff] [blame] | 882 | const char *email, |
Johannes Schindelin | dddbad7 | 2017-04-26 21:29:31 +0200 | [diff] [blame] | 883 | timestamp_t timestamp, int tz, |
Michael Haggerty | fa5b183 | 2014-12-12 09:56:59 +0100 | [diff] [blame] | 884 | const char *message, void *cb_data); |
| 885 | typedef void reflog_expiry_cleanup_fn(void *cb_data); |
| 886 | |
| 887 | /* |
Ævar Arnfjörð Bjarmason | cc40b5c | 2021-08-23 13:36:11 +0200 | [diff] [blame] | 888 | * Expire reflog entries for the specified reference. |
| 889 | * flags is a combination of the constants in |
Michael Haggerty | fa5b183 | 2014-12-12 09:56:59 +0100 | [diff] [blame] | 890 | * enum expire_reflog_flags. The three function pointers are described |
| 891 | * above. On success, return zero. |
| 892 | */ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 893 | int refs_reflog_expire(struct ref_store *refs, |
| 894 | const char *refname, |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 895 | 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ð Bjarmason | cc40b5c | 2021-08-23 13:36:11 +0200 | [diff] [blame] | 900 | int reflog_expire(const char *refname, |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 901 | 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 Haggerty | fa5b183 | 2014-12-12 09:56:59 +0100 | [diff] [blame] | 906 | |
Stefan Beller | 64a7416 | 2018-04-11 17:21:14 -0700 | [diff] [blame] | 907 | struct ref_store *get_main_ref_store(struct repository *r); |
Heba Waly | 126c1cc | 2019-11-17 21:04:46 +0000 | [diff] [blame] | 908 | |
| 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 Duy | 18d0002 | 2017-03-26 09:42:33 +0700 | [diff] [blame] | 943 | /* |
| 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 | */ |
| 953 | struct ref_store *get_submodule_ref_store(const char *submodule); |
Nguyễn Thái Ngọc Duy | 17eff96 | 2017-04-24 17:01:22 +0700 | [diff] [blame] | 954 | struct ref_store *get_worktree_ref_store(const struct worktree *wt); |
Nguyễn Thái Ngọc Duy | 077be78 | 2017-03-26 09:42:29 +0700 | [diff] [blame] | 955 | |
Derrick Stolee | b9342b3 | 2022-08-05 17:58:36 +0000 | [diff] [blame] | 956 | /* |
| 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 | |
| 962 | struct 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 | |
| 977 | enum 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. */ |
| 993 | extern 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 | */ |
| 999 | void update_ref_namespace(enum ref_namespace namespace, char *ref); |
| 1000 | |
Daniel Barkalow | 95fc751 | 2005-06-06 16:31:29 -0400 | [diff] [blame] | 1001 | #endif /* REFS_H */ |