Daniel Barkalow | 95fc751 | 2005-06-06 16:31:29 -0400 | [diff] [blame] | 1 | #ifndef REFS_H |
| 2 | #define REFS_H |
| 3 | |
Nguyễn Thái Ngọc Duy | 504c4d4 | 2017-03-18 09:03:11 +0700 | [diff] [blame] | 4 | struct object_id; |
Nguyễn Thái Ngọc Duy | 077be78 | 2017-03-26 09:42:29 +0700 | [diff] [blame] | 5 | struct ref_store; |
Elijah Newren | ef3ca95 | 2018-08-15 10:54:05 -0700 | [diff] [blame] | 6 | struct repository; |
Nguyễn Thái Ngọc Duy | 504c4d4 | 2017-03-18 09:03:11 +0700 | [diff] [blame] | 7 | struct strbuf; |
| 8 | struct string_list; |
Elijah Newren | ef3ca95 | 2018-08-15 10:54:05 -0700 | [diff] [blame] | 9 | struct string_list_item; |
Nguyễn Thái Ngọc Duy | 17eff96 | 2017-04-24 17:01:22 +0700 | [diff] [blame] | 10 | struct worktree; |
Nguyễn Thái Ngọc Duy | 504c4d4 | 2017-03-18 09:03:11 +0700 | [diff] [blame] | 11 | |
Ronnie Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 12 | /* |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 13 | * Resolve a reference, recursively following symbolic refererences. |
| 14 | * |
René Scharfe | 54fad66 | 2017-09-23 11:41:45 +0200 | [diff] [blame] | 15 | * Return the name of the non-symbolic reference that ultimately pointed |
| 16 | * at the resolved object name. The return value, if not NULL, is a |
| 17 | * pointer into either a static buffer or the input ref. |
| 18 | * |
brian m. carlson | 49e6147 | 2017-10-15 22:07:09 +0000 | [diff] [blame] | 19 | * 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] | 20 | * |
| 21 | * If the reference cannot be resolved to an object, the behavior |
| 22 | * depends on the RESOLVE_REF_READING flag: |
| 23 | * |
| 24 | * - If RESOLVE_REF_READING is set, return NULL. |
| 25 | * |
brian m. carlson | 49e6147 | 2017-10-15 22:07:09 +0000 | [diff] [blame] | 26 | * - 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] | 27 | * the last reference name in the chain, which will either be a non-symbolic |
| 28 | * reference or an undefined reference. If this is a prelude to |
| 29 | * "writing" to the ref, the return value is the name of the ref |
| 30 | * that will actually be created or changed. |
| 31 | * |
| 32 | * 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] | 33 | * level of symbolic reference. The value stored in oid for a symbolic |
| 34 | * reference will always be null_oid in this case, and the return |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 35 | * value is the reference that the symref refers to directly. |
| 36 | * |
| 37 | * If flags is non-NULL, set the value that it points to the |
| 38 | * combination of REF_ISPACKED (if the reference was found among the |
| 39 | * packed references), REF_ISSYMREF (if the initial reference was a |
| 40 | * symbolic reference), REF_BAD_NAME (if the reference name is ill |
| 41 | * formed --- see RESOLVE_REF_ALLOW_BAD_NAME below), and REF_ISBROKEN |
| 42 | * (if the ref is malformed or has a bad name). See refs.h for more detail |
| 43 | * on each flag. |
| 44 | * |
| 45 | * If ref is not a properly-formatted, normalized reference, return |
| 46 | * NULL. If more than MAXDEPTH recursive symbolic lookups are needed, |
| 47 | * give up and return NULL. |
| 48 | * |
| 49 | * RESOLVE_REF_ALLOW_BAD_NAME allows resolving refs even when their |
| 50 | * 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] | 51 | * 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] | 52 | * flags REF_ISBROKEN and REF_BAD_NAME will be set. |
| 53 | * |
| 54 | * Even with RESOLVE_REF_ALLOW_BAD_NAME, names that escape the refs/ |
| 55 | * directory and do not consist of all caps and underscores cannot be |
| 56 | * resolved. The function returns NULL for such ref names. |
| 57 | * Caps and underscores refers to the special refs, such as HEAD, |
| 58 | * FETCH_HEAD and friends, that all live outside of the refs/ directory. |
| 59 | */ |
| 60 | #define RESOLVE_REF_READING 0x01 |
| 61 | #define RESOLVE_REF_NO_RECURSE 0x02 |
| 62 | #define RESOLVE_REF_ALLOW_BAD_NAME 0x04 |
| 63 | |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 64 | const char *refs_resolve_ref_unsafe(struct ref_store *refs, |
| 65 | const char *refname, |
| 66 | int resolve_flags, |
brian m. carlson | 49e6147 | 2017-10-15 22:07:09 +0000 | [diff] [blame] | 67 | struct object_id *oid, |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 68 | int *flags); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 69 | const char *resolve_ref_unsafe(const char *refname, int resolve_flags, |
brian m. carlson | 49e6147 | 2017-10-15 22:07:09 +0000 | [diff] [blame] | 70 | struct object_id *oid, int *flags); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 71 | |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 72 | char *refs_resolve_refdup(struct ref_store *refs, |
| 73 | const char *refname, int resolve_flags, |
brian m. carlson | 0f2dc72 | 2017-10-15 22:06:55 +0000 | [diff] [blame] | 74 | struct object_id *oid, int *flags); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 75 | char *resolve_refdup(const char *refname, int resolve_flags, |
brian m. carlson | 0f2dc72 | 2017-10-15 22:06:55 +0000 | [diff] [blame] | 76 | struct object_id *oid, int *flags); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 77 | |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 78 | int refs_read_ref_full(struct ref_store *refs, const char *refname, |
brian m. carlson | 34c290a | 2017-10-15 22:06:56 +0000 | [diff] [blame] | 79 | int resolve_flags, struct object_id *oid, int *flags); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 80 | int read_ref_full(const char *refname, int resolve_flags, |
brian m. carlson | 34c290a | 2017-10-15 22:06:56 +0000 | [diff] [blame] | 81 | struct object_id *oid, int *flags); |
| 82 | int read_ref(const char *refname, struct object_id *oid); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 83 | |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 84 | /* |
| 85 | * Return 0 if a reference named refname could be created without |
| 86 | * conflicting with the name of an existing reference. Otherwise, |
| 87 | * return a negative value and write an explanation to err. If extras |
| 88 | * is non-NULL, it is a list of additional refnames with which refname |
| 89 | * is not allowed to conflict. If skip is non-NULL, ignore potential |
| 90 | * conflicts with refs in skip (e.g., because they are scheduled for |
| 91 | * deletion in the same operation). Behavior is undefined if the same |
| 92 | * name is listed in both extras and skip. |
| 93 | * |
| 94 | * Two reference names conflict if one of them exactly matches the |
| 95 | * leading components of the other; e.g., "foo/bar" conflicts with |
| 96 | * both "foo" and with "foo/bar/baz" but not with "foo/bar" or |
| 97 | * "foo/barbados". |
| 98 | * |
| 99 | * extras and skip must be sorted. |
| 100 | */ |
| 101 | |
| 102 | int refs_verify_refname_available(struct ref_store *refs, |
| 103 | const char *refname, |
Michael Haggerty | b05855b | 2017-04-16 08:41:26 +0200 | [diff] [blame] | 104 | const struct string_list *extras, |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 105 | const struct string_list *skip, |
| 106 | struct strbuf *err); |
| 107 | |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 108 | int ref_exists(const char *refname); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 109 | |
Cornelius Weig | 341fb28 | 2017-01-27 11:09:47 +0100 | [diff] [blame] | 110 | int should_autocreate_reflog(const char *refname); |
| 111 | |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 112 | int is_branch(const char *refname); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 113 | |
Denton Liu | 5545442 | 2019-04-29 04:28:14 -0400 | [diff] [blame] | 114 | int refs_init_db(struct strbuf *err); |
David Turner | 6fb5acf | 2016-09-04 18:08:41 +0200 | [diff] [blame] | 115 | |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 116 | /* |
| 117 | * If refname is a non-symbolic reference that refers to a tag object, |
| 118 | * and the tag can be (recursively) dereferenced to a non-tag object, |
brian m. carlson | b420d90 | 2017-10-15 22:07:02 +0000 | [diff] [blame] | 119 | * store the object ID of the referred-to object to oid and return 0. |
| 120 | * If any of these conditions are not met, return a non-zero value. |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 121 | * Symbolic references are considered unpeelable, even if they |
| 122 | * ultimately resolve to a peelable tag. |
| 123 | */ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 124 | int refs_peel_ref(struct ref_store *refs, const char *refname, |
brian m. carlson | b420d90 | 2017-10-15 22:07:02 +0000 | [diff] [blame] | 125 | struct object_id *oid); |
| 126 | int peel_ref(const char *refname, struct object_id *oid); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 127 | |
| 128 | /** |
Michael Haggerty | a8355bb | 2016-09-04 18:08:24 +0200 | [diff] [blame] | 129 | * Resolve refname in the nested "gitlink" repository in the specified |
| 130 | * submodule (which must be non-NULL). If the resolution is |
Michael Haggerty | 78fb457 | 2017-11-05 09:42:09 +0100 | [diff] [blame] | 131 | * successful, return 0 and set oid to the name of the object; |
Michael Haggerty | a8355bb | 2016-09-04 18:08:24 +0200 | [diff] [blame] | 132 | * otherwise, return a non-zero value. |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 133 | */ |
Michael Haggerty | a8355bb | 2016-09-04 18:08:24 +0200 | [diff] [blame] | 134 | int resolve_gitlink_ref(const char *submodule, const char *refname, |
brian m. carlson | a98e610 | 2017-10-15 22:07:07 +0000 | [diff] [blame] | 135 | struct object_id *oid); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 136 | |
| 137 | /* |
| 138 | * Return true iff abbrev_name is a possible abbreviation for |
| 139 | * full_name according to the rules defined by ref_rev_parse_rules in |
| 140 | * refs.c. |
| 141 | */ |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 142 | int refname_match(const char *abbrev_name, const char *full_name); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 143 | |
Brandon Williams | b4be741 | 2018-03-15 10:31:24 -0700 | [diff] [blame] | 144 | /* |
| 145 | * Given a 'prefix' expand it by the rules in 'ref_rev_parse_rules' and add |
| 146 | * the results to 'prefixes' |
| 147 | */ |
| 148 | struct argv_array; |
| 149 | void expand_ref_prefix(struct argv_array *prefixes, const char *prefix); |
| 150 | |
Nguyễn Thái Ngọc Duy | 0b1dbf5 | 2019-04-06 18:34:27 +0700 | [diff] [blame] | 151 | int expand_ref(struct repository *r, const char *str, int len, struct object_id *oid, char **ref); |
Nguyễn Thái Ngọc Duy | d8984c5 | 2019-04-06 18:34:28 +0700 | [diff] [blame] | 152 | int repo_dwim_ref(struct repository *r, const char *str, int len, struct object_id *oid, char **ref); |
Nguyễn Thái Ngọc Duy | 5670090 | 2019-04-06 18:34:29 +0700 | [diff] [blame] | 153 | int repo_dwim_log(struct repository *r, const char *str, int len, struct object_id *oid, char **ref); |
brian m. carlson | cca5fa6 | 2017-10-15 22:06:57 +0000 | [diff] [blame] | 154 | int dwim_ref(const char *str, int len, struct object_id *oid, char **ref); |
brian m. carlson | 334dc52 | 2017-10-15 22:06:59 +0000 | [diff] [blame] | 155 | 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] | 156 | |
| 157 | /* |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 158 | * A ref_transaction represents a collection of reference updates that |
| 159 | * should succeed or fail together. |
Ronnie Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 160 | * |
| 161 | * Calling sequence |
| 162 | * ---------------- |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 163 | * |
Ronnie Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 164 | * - Allocate and initialize a `struct ref_transaction` by calling |
| 165 | * `ref_transaction_begin()`. |
| 166 | * |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 167 | * - Specify the intended ref updates by calling one or more of the |
| 168 | * following functions: |
| 169 | * - `ref_transaction_update()` |
| 170 | * - `ref_transaction_create()` |
| 171 | * - `ref_transaction_delete()` |
| 172 | * - `ref_transaction_verify()` |
Ronnie Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 173 | * |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 174 | * - Then either: |
Ronnie Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 175 | * |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 176 | * - Optionally call `ref_transaction_prepare()` to prepare the |
| 177 | * transaction. This locks all references, checks preconditions, |
| 178 | * etc. but doesn't finalize anything. If this step fails, the |
| 179 | * transaction has been closed and can only be freed. If this step |
| 180 | * succeeds, then `ref_transaction_commit()` is almost certain to |
| 181 | * succeed. However, you can still call `ref_transaction_abort()` |
| 182 | * if you decide not to commit the transaction after all. |
David Turner | 4938686 | 2016-02-25 15:05:46 -0500 | [diff] [blame] | 183 | * |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 184 | * - Call `ref_transaction_commit()` to execute the transaction, |
| 185 | * make the changes permanent, and release all locks. If you |
| 186 | * haven't already called `ref_transaction_prepare()`, then |
| 187 | * `ref_transaction_commit()` calls it for you. |
| 188 | * |
| 189 | * Or |
| 190 | * |
| 191 | * - Call `initial_ref_transaction_commit()` if the ref database is |
| 192 | * known to be empty and have no other writers (e.g. during |
| 193 | * clone). This is likely to be much faster than |
| 194 | * `ref_transaction_commit()`. `ref_transaction_prepare()` should |
| 195 | * *not* be called before `initial_ref_transaction_commit()`. |
| 196 | * |
| 197 | * - Then finally, call `ref_transaction_free()` to free the |
| 198 | * `ref_transaction` data structure. |
| 199 | * |
| 200 | * At any time before calling `ref_transaction_commit()`, you can call |
| 201 | * `ref_transaction_abort()` to abort the transaction, rollback any |
| 202 | * locks, and free any associated resources (including the |
| 203 | * `ref_transaction` data structure). |
| 204 | * |
| 205 | * Putting it all together, a complete reference update looks like |
| 206 | * |
| 207 | * struct ref_transaction *transaction; |
| 208 | * struct strbuf err = STRBUF_INIT; |
| 209 | * int ret = 0; |
| 210 | * |
| 211 | * transaction = ref_store_transaction_begin(refs, &err); |
| 212 | * if (!transaction || |
| 213 | * ref_transaction_update(...) || |
| 214 | * ref_transaction_create(...) || |
| 215 | * ...etc... || |
| 216 | * ref_transaction_commit(transaction, &err)) { |
| 217 | * error("%s", err.buf); |
| 218 | * ret = -1; |
| 219 | * } |
| 220 | * ref_transaction_free(transaction); |
| 221 | * strbuf_release(&err); |
| 222 | * return ret; |
Ronnie Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 223 | * |
| 224 | * Error handling |
| 225 | * -------------- |
| 226 | * |
| 227 | * On error, transaction functions append a message about what |
| 228 | * went wrong to the 'err' argument. The message mentions what |
| 229 | * ref was being updated (if any) when the error occurred so it |
| 230 | * can be passed to 'die' or 'error' as-is. |
| 231 | * |
| 232 | * The message is appended to err without first clearing err. |
| 233 | * err will not be '\n' terminated. |
David Turner | 4938686 | 2016-02-25 15:05:46 -0500 | [diff] [blame] | 234 | * |
| 235 | * Caveats |
| 236 | * ------- |
| 237 | * |
| 238 | * Note that no locks are taken, and no refs are read, until |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 239 | * `ref_transaction_prepare()` or `ref_transaction_commit()` is |
| 240 | * called. So, for example, `ref_transaction_verify()` won't report a |
| 241 | * verification failure until the commit is attempted. |
Ronnie Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 242 | */ |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 243 | struct ref_transaction; |
| 244 | |
Michael Haggerty | 89df9c8 | 2013-04-14 14:54:16 +0200 | [diff] [blame] | 245 | /* |
Michael Haggerty | 3bc581b | 2016-06-18 06:15:15 +0200 | [diff] [blame] | 246 | * Bit values set in the flags argument passed to each_ref_fn() and |
| 247 | * stored in ref_iterator::flags. Other bits are for internal use |
| 248 | * only: |
Michael Haggerty | 89df9c8 | 2013-04-14 14:54:16 +0200 | [diff] [blame] | 249 | */ |
| 250 | |
| 251 | /* Reference is a symbolic reference. */ |
Junio C Hamano | 98ac34b | 2011-10-19 13:45:50 -0700 | [diff] [blame] | 252 | #define REF_ISSYMREF 0x01 |
Michael Haggerty | 89df9c8 | 2013-04-14 14:54:16 +0200 | [diff] [blame] | 253 | |
| 254 | /* Reference is a packed reference. */ |
Junio C Hamano | 98ac34b | 2011-10-19 13:45:50 -0700 | [diff] [blame] | 255 | #define REF_ISPACKED 0x02 |
Michael Haggerty | 89df9c8 | 2013-04-14 14:54:16 +0200 | [diff] [blame] | 256 | |
| 257 | /* |
| 258 | * Reference cannot be resolved to an object name: dangling symbolic |
Ronnie Sahlberg | d0f810f | 2014-09-03 11:45:43 -0700 | [diff] [blame] | 259 | * reference (directly or indirectly), corrupt reference file, |
| 260 | * reference exists but name is bad, or symbolic reference refers to |
| 261 | * ill-formatted reference name. |
Michael Haggerty | 89df9c8 | 2013-04-14 14:54:16 +0200 | [diff] [blame] | 262 | */ |
Junio C Hamano | 98ac34b | 2011-10-19 13:45:50 -0700 | [diff] [blame] | 263 | #define REF_ISBROKEN 0x04 |
Junio C Hamano | f4204ab | 2006-11-21 23:36:35 -0800 | [diff] [blame] | 264 | |
Linus Torvalds | 8a65ff7 | 2005-07-02 20:23:36 -0700 | [diff] [blame] | 265 | /* |
Ronnie Sahlberg | d0f810f | 2014-09-03 11:45:43 -0700 | [diff] [blame] | 266 | * Reference name is not well formed. |
| 267 | * |
| 268 | * See git-check-ref-format(1) for the definition of well formed ref names. |
| 269 | */ |
| 270 | #define REF_BAD_NAME 0x08 |
| 271 | |
| 272 | /* |
Michael Haggerty | 4f78c24 | 2013-05-25 11:08:24 +0200 | [diff] [blame] | 273 | * The signature for the callback function for the for_each_*() |
Michael Haggerty | 78fb457 | 2017-11-05 09:42:09 +0100 | [diff] [blame] | 274 | * functions below. The memory pointed to by the refname and oid |
Michael Haggerty | 4f78c24 | 2013-05-25 11:08:24 +0200 | [diff] [blame] | 275 | * arguments is only guaranteed to be valid for the duration of a |
| 276 | * single callback invocation. |
Linus Torvalds | 8a65ff7 | 2005-07-02 20:23:36 -0700 | [diff] [blame] | 277 | */ |
Michael Haggerty | 4f78c24 | 2013-05-25 11:08:24 +0200 | [diff] [blame] | 278 | typedef int each_ref_fn(const char *refname, |
Michael Haggerty | 2b2a5be | 2015-05-25 18:38:28 +0000 | [diff] [blame] | 279 | const struct object_id *oid, int flags, void *cb_data); |
| 280 | |
Michael Haggerty | 4f78c24 | 2013-05-25 11:08:24 +0200 | [diff] [blame] | 281 | /* |
Stefan Beller | 4a6067c | 2018-08-20 18:24:16 +0000 | [diff] [blame] | 282 | * The same as each_ref_fn, but also with a repository argument that |
| 283 | * contains the repository associated with the callback. |
| 284 | */ |
| 285 | typedef int each_repo_ref_fn(struct repository *r, |
| 286 | const char *refname, |
| 287 | const struct object_id *oid, |
| 288 | int flags, |
| 289 | void *cb_data); |
| 290 | |
| 291 | /* |
Michael Haggerty | 4f78c24 | 2013-05-25 11:08:24 +0200 | [diff] [blame] | 292 | * The following functions invoke the specified callback function for |
| 293 | * each reference indicated. If the function ever returns a nonzero |
| 294 | * value, stop the iteration and return that value. Please note that |
| 295 | * it is not safe to modify references while an iteration is in |
| 296 | * progress, unless the same callback function invocation that |
| 297 | * 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] | 298 | * stop the iteration. Returned references are sorted. |
Michael Haggerty | 4f78c24 | 2013-05-25 11:08:24 +0200 | [diff] [blame] | 299 | */ |
Nguyễn Thái Ngọc Duy | 62f0b39 | 2017-08-23 19:36:55 +0700 | [diff] [blame] | 300 | int refs_head_ref(struct ref_store *refs, |
| 301 | each_ref_fn fn, void *cb_data); |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 302 | int refs_for_each_ref(struct ref_store *refs, |
| 303 | each_ref_fn fn, void *cb_data); |
| 304 | int refs_for_each_ref_in(struct ref_store *refs, const char *prefix, |
| 305 | each_ref_fn fn, void *cb_data); |
| 306 | int refs_for_each_tag_ref(struct ref_store *refs, |
| 307 | each_ref_fn fn, void *cb_data); |
| 308 | int refs_for_each_branch_ref(struct ref_store *refs, |
| 309 | each_ref_fn fn, void *cb_data); |
| 310 | int refs_for_each_remote_ref(struct ref_store *refs, |
| 311 | each_ref_fn fn, void *cb_data); |
| 312 | |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 313 | int head_ref(each_ref_fn fn, void *cb_data); |
| 314 | int for_each_ref(each_ref_fn fn, void *cb_data); |
| 315 | int for_each_ref_in(const char *prefix, each_ref_fn fn, void *cb_data); |
Nguyễn Thái Ngọc Duy | 073cf63 | 2017-08-23 19:36:56 +0700 | [diff] [blame] | 316 | int refs_for_each_fullref_in(struct ref_store *refs, const char *prefix, |
| 317 | each_ref_fn fn, void *cb_data, |
| 318 | unsigned int broken); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 319 | int for_each_fullref_in(const char *prefix, each_ref_fn fn, void *cb_data, |
| 320 | unsigned int broken); |
| 321 | int for_each_tag_ref(each_ref_fn fn, void *cb_data); |
| 322 | int for_each_branch_ref(each_ref_fn fn, void *cb_data); |
| 323 | int for_each_remote_ref(each_ref_fn fn, void *cb_data); |
Stefan Beller | 212e0f7 | 2018-08-20 18:24:19 +0000 | [diff] [blame] | 324 | int for_each_replace_ref(struct repository *r, each_repo_ref_fn fn, void *cb_data); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 325 | int for_each_glob_ref(each_ref_fn fn, const char *pattern, void *cb_data); |
| 326 | int for_each_glob_ref_in(each_ref_fn fn, const char *pattern, |
| 327 | const char *prefix, void *cb_data); |
Linus Torvalds | 8a65ff7 | 2005-07-02 20:23:36 -0700 | [diff] [blame] | 328 | |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 329 | int head_ref_namespaced(each_ref_fn fn, void *cb_data); |
| 330 | int for_each_namespaced_ref(each_ref_fn fn, void *cb_data); |
Josh Triplett | a1bea2c | 2011-07-05 10:54:44 -0700 | [diff] [blame] | 331 | |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 332 | /* 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] | 333 | 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] | 334 | int for_each_rawref(each_ref_fn fn, void *cb_data); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 335 | |
Rafael Ascensão | 65516f5 | 2017-11-21 21:33:41 +0000 | [diff] [blame] | 336 | /* |
| 337 | * Normalizes partial refs to their fully qualified form. |
| 338 | * Will prepend <prefix> to the <pattern> if it doesn't start with 'refs/'. |
| 339 | * <prefix> will default to 'refs/' if NULL. |
| 340 | * |
| 341 | * item.string will be set to the result. |
| 342 | * item.util will be set to NULL if <pattern> contains glob characters, or |
| 343 | * non-NULL if it doesn't. |
| 344 | */ |
| 345 | void normalize_glob_ref(struct string_list_item *item, const char *prefix, |
| 346 | const char *pattern); |
| 347 | |
| 348 | /* |
| 349 | * Returns 0 if refname matches any of the exclude_patterns, or if it doesn't |
| 350 | * match any of the include_patterns. Returns 1 otherwise. |
| 351 | * |
| 352 | * If pattern list is NULL or empty, matching against that list is skipped. |
| 353 | * This has the effect of matching everything by default, unless the user |
| 354 | * specifies rules otherwise. |
| 355 | */ |
| 356 | int ref_filter_match(const char *refname, |
| 357 | const struct string_list *include_patterns, |
| 358 | const struct string_list *exclude_patterns); |
| 359 | |
Thomas Rast | 894a9d3 | 2010-03-12 18:04:26 +0100 | [diff] [blame] | 360 | static inline const char *has_glob_specials(const char *pattern) |
| 361 | { |
| 362 | return strpbrk(pattern, "?*["); |
| 363 | } |
| 364 | |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 365 | void warn_dangling_symref(FILE *fp, const char *msg_fmt, const char *refname); |
| 366 | void warn_dangling_symrefs(FILE *fp, const char *msg_fmt, |
| 367 | const struct string_list *refnames); |
Junio C Hamano | f8948e2 | 2009-02-08 23:27:10 -0800 | [diff] [blame] | 368 | |
Daniel Barkalow | e142a3c | 2008-04-27 13:39:24 -0400 | [diff] [blame] | 369 | /* |
Michael Haggerty | 32d462c | 2013-04-22 21:52:32 +0200 | [diff] [blame] | 370 | * Flags for controlling behaviour of pack_refs() |
| 371 | * PACK_REFS_PRUNE: Prune loose refs after packing |
| 372 | * PACK_REFS_ALL: Pack _all_ refs, not just tags and already packed refs |
| 373 | */ |
| 374 | #define PACK_REFS_PRUNE 0x0001 |
| 375 | #define PACK_REFS_ALL 0x0002 |
| 376 | |
| 377 | /* |
| 378 | * Write a packed-refs file for the current repository. |
| 379 | * flags: Combination of the above PACK_REFS_* flags. |
| 380 | */ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 381 | int refs_pack_refs(struct ref_store *refs, unsigned int flags); |
Michael Haggerty | 32d462c | 2013-04-22 21:52:32 +0200 | [diff] [blame] | 382 | |
Ronnie Sahlberg | 835e3c9 | 2014-06-20 07:42:51 -0700 | [diff] [blame] | 383 | /* |
David Turner | a4c653d | 2015-07-21 17:04:50 -0400 | [diff] [blame] | 384 | * Setup reflog before using. Fill in err and return -1 on failure. |
Ronnie Sahlberg | bd3b02d | 2014-06-20 07:42:50 -0700 | [diff] [blame] | 385 | */ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 386 | int refs_create_reflog(struct ref_store *refs, const char *refname, |
| 387 | int force_create, struct strbuf *err); |
David Turner | abd0cd3 | 2015-07-21 17:04:52 -0400 | [diff] [blame] | 388 | int safe_create_reflog(const char *refname, int force_create, struct strbuf *err); |
Erick Mattos | 859c301 | 2010-05-21 21:28:36 -0300 | [diff] [blame] | 389 | |
Shawn Pearce | d556fae | 2006-05-17 05:56:09 -0400 | [diff] [blame] | 390 | /** 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] | 391 | int read_ref_at(struct ref_store *refs, |
| 392 | const char *refname, unsigned int flags, |
Johannes Schindelin | dddbad7 | 2017-04-26 21:29:31 +0200 | [diff] [blame] | 393 | timestamp_t at_time, int cnt, |
brian m. carlson | 8eb36d9 | 2017-10-15 22:07:03 +0000 | [diff] [blame] | 394 | struct object_id *oid, char **msg, |
Johannes Schindelin | dddbad7 | 2017-04-26 21:29:31 +0200 | [diff] [blame] | 395 | timestamp_t *cutoff_time, int *cutoff_tz, int *cutoff_cnt); |
Shawn Pearce | d556fae | 2006-05-17 05:56:09 -0400 | [diff] [blame] | 396 | |
Ronnie Sahlberg | 4da5883 | 2014-05-06 15:45:52 -0700 | [diff] [blame] | 397 | /** Check if a particular reflog exists */ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 398 | int refs_reflog_exists(struct ref_store *refs, const char *refname); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 399 | int reflog_exists(const char *refname); |
Ronnie Sahlberg | 4da5883 | 2014-05-06 15:45:52 -0700 | [diff] [blame] | 400 | |
Michael Haggerty | fc1c216 | 2015-06-22 16:02:52 +0200 | [diff] [blame] | 401 | /* |
brian m. carlson | 2616a5e | 2017-10-15 22:06:50 +0000 | [diff] [blame] | 402 | * Delete the specified reference. If old_oid is non-NULL, then |
Michael Haggerty | 78fb457 | 2017-11-05 09:42:09 +0100 | [diff] [blame] | 403 | * 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] | 404 | * deleting it. If old_oid is NULL, delete the reference if it |
| 405 | * exists, regardless of its old value. It is an error for old_oid to |
| 406 | * be null_oid. msg and flags are passed through to |
Michael Haggerty | 64da419 | 2017-05-22 16:17:38 +0200 | [diff] [blame] | 407 | * ref_transaction_delete(). |
Michael Haggerty | fc1c216 | 2015-06-22 16:02:52 +0200 | [diff] [blame] | 408 | */ |
Nguyễn Thái Ngọc Duy | c0fe4e8 | 2017-03-26 09:42:35 +0700 | [diff] [blame] | 409 | int refs_delete_ref(struct ref_store *refs, const char *msg, |
| 410 | const char *refname, |
brian m. carlson | 2616a5e | 2017-10-15 22:06:50 +0000 | [diff] [blame] | 411 | const struct object_id *old_oid, |
Nguyễn Thái Ngọc Duy | c0fe4e8 | 2017-03-26 09:42:35 +0700 | [diff] [blame] | 412 | unsigned int flags); |
Kyle Meyer | 755b49a | 2017-02-20 20:10:32 -0500 | [diff] [blame] | 413 | int delete_ref(const char *msg, const char *refname, |
brian m. carlson | 2616a5e | 2017-10-15 22:06:50 +0000 | [diff] [blame] | 414 | const struct object_id *old_oid, unsigned int flags); |
Michael Haggerty | fc1c216 | 2015-06-22 16:02:52 +0200 | [diff] [blame] | 415 | |
Michael Haggerty | 98ffd5f | 2015-06-22 16:02:55 +0200 | [diff] [blame] | 416 | /* |
| 417 | * Delete the specified references. If there are any problems, emit |
| 418 | * 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] | 419 | * an all-or-nothing transaction). msg and flags are passed through to |
Michael Haggerty | c5f04dd | 2016-06-18 06:15:10 +0200 | [diff] [blame] | 420 | * ref_transaction_delete(). |
Michael Haggerty | 98ffd5f | 2015-06-22 16:02:55 +0200 | [diff] [blame] | 421 | */ |
Michael Haggerty | 64da419 | 2017-05-22 16:17:38 +0200 | [diff] [blame] | 422 | int refs_delete_refs(struct ref_store *refs, const char *msg, |
| 423 | struct string_list *refnames, unsigned int flags); |
| 424 | int delete_refs(const char *msg, struct string_list *refnames, |
| 425 | unsigned int flags); |
Michael Haggerty | 98ffd5f | 2015-06-22 16:02:55 +0200 | [diff] [blame] | 426 | |
Ronnie Sahlberg | 4da5883 | 2014-05-06 15:45:52 -0700 | [diff] [blame] | 427 | /** Delete a reflog */ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 428 | int refs_delete_reflog(struct ref_store *refs, const char *refname); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 429 | int delete_reflog(const char *refname); |
Ronnie Sahlberg | 4da5883 | 2014-05-06 15:45:52 -0700 | [diff] [blame] | 430 | |
Junio C Hamano | 2ff8166 | 2006-12-18 01:18:16 -0800 | [diff] [blame] | 431 | /* iterate over reflog entries */ |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 432 | typedef int each_reflog_ent_fn( |
brian m. carlson | 9461d27 | 2017-02-21 23:47:32 +0000 | [diff] [blame] | 433 | struct object_id *old_oid, struct object_id *new_oid, |
Johannes Schindelin | dddbad7 | 2017-04-26 21:29:31 +0200 | [diff] [blame] | 434 | const char *committer, timestamp_t timestamp, |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 435 | int tz, const char *msg, void *cb_data); |
| 436 | |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 437 | int refs_for_each_reflog_ent(struct ref_store *refs, const char *refname, |
| 438 | each_reflog_ent_fn fn, void *cb_data); |
| 439 | int refs_for_each_reflog_ent_reverse(struct ref_store *refs, |
| 440 | const char *refname, |
| 441 | each_reflog_ent_fn fn, |
| 442 | void *cb_data); |
Michael Haggerty | dfefa93 | 2011-12-12 06:38:09 +0100 | [diff] [blame] | 443 | int for_each_reflog_ent(const char *refname, each_reflog_ent_fn fn, void *cb_data); |
Junio C Hamano | 98f85ff | 2013-03-08 13:27:37 -0800 | [diff] [blame] | 444 | 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] | 445 | |
Nicolas Pitre | eb8381c | 2007-02-03 13:25:43 -0500 | [diff] [blame] | 446 | /* |
| 447 | * 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] | 448 | * and returns the value. Reflog file order is unspecified. |
Nicolas Pitre | eb8381c | 2007-02-03 13:25:43 -0500 | [diff] [blame] | 449 | */ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 450 | 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] | 451 | int for_each_reflog(each_ref_fn fn, void *cb_data); |
Nicolas Pitre | eb8381c | 2007-02-03 13:25:43 -0500 | [diff] [blame] | 452 | |
Michael Haggerty | 8d9c501 | 2011-09-15 23:10:25 +0200 | [diff] [blame] | 453 | #define REFNAME_ALLOW_ONELEVEL 1 |
| 454 | #define REFNAME_REFSPEC_PATTERN 2 |
| 455 | |
| 456 | /* |
Michael Haggerty | dfefa93 | 2011-12-12 06:38:09 +0100 | [diff] [blame] | 457 | * Return 0 iff refname has the correct format for a refname according |
| 458 | * to the rules described in Documentation/git-check-ref-format.txt. |
| 459 | * If REFNAME_ALLOW_ONELEVEL is set in flags, then accept one-level |
Michael Haggerty | 8d9c501 | 2011-09-15 23:10:25 +0200 | [diff] [blame] | 460 | * reference names. If REFNAME_REFSPEC_PATTERN is set in flags, then |
Jacob Keller | cd377f4 | 2015-07-22 14:05:33 -0700 | [diff] [blame] | 461 | * allow a single "*" wildcard character in the refspec. No leading or |
| 462 | * repeated slashes are accepted. |
Michael Haggerty | 8d9c501 | 2011-09-15 23:10:25 +0200 | [diff] [blame] | 463 | */ |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 464 | int check_refname_format(const char *refname, int flags); |
Daniel Barkalow | 95fc751 | 2005-06-06 16:31:29 -0400 | [diff] [blame] | 465 | |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 466 | const char *prettify_refname(const char *refname); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 467 | |
Nguyễn Thái Ngọc Duy | 546edf3 | 2019-04-06 18:34:25 +0700 | [diff] [blame] | 468 | char *refs_shorten_unambiguous_ref(struct ref_store *refs, |
| 469 | const char *refname, int strict); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 470 | char *shorten_unambiguous_ref(const char *refname, int strict); |
Daniel Barkalow | a9c37a7 | 2009-03-08 21:06:05 -0400 | [diff] [blame] | 471 | |
Lars Hjemli | c976d41 | 2006-11-28 15:47:40 +0100 | [diff] [blame] | 472 | /** rename ref, return 0 on success **/ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 473 | int refs_rename_ref(struct ref_store *refs, const char *oldref, |
| 474 | const char *newref, const char *logmsg); |
Sahil Dua | 52d59cc | 2017-06-18 23:19:16 +0200 | [diff] [blame] | 475 | int rename_ref(const char *oldref, const char *newref, |
| 476 | const char *logmsg); |
| 477 | |
| 478 | /** copy ref, return 0 on success **/ |
| 479 | int refs_copy_existing_ref(struct ref_store *refs, const char *oldref, |
| 480 | const char *newref, const char *logmsg); |
| 481 | int copy_existing_ref(const char *oldref, const char *newref, |
| 482 | const char *logmsg); |
Lars Hjemli | c976d41 | 2006-11-28 15:47:40 +0100 | [diff] [blame] | 483 | |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 484 | int refs_create_symref(struct ref_store *refs, const char *refname, |
| 485 | const char *target, const char *logmsg); |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 486 | int create_symref(const char *refname, const char *target, const char *logmsg); |
Linus Torvalds | 0ebde32 | 2007-04-09 21:14:26 -0700 | [diff] [blame] | 487 | |
Michael Haggerty | f412411 | 2014-04-07 15:47:56 +0200 | [diff] [blame] | 488 | enum action_on_err { |
| 489 | UPDATE_REFS_MSG_ON_ERR, |
| 490 | UPDATE_REFS_DIE_ON_ERR, |
| 491 | UPDATE_REFS_QUIET_ON_ERR |
| 492 | }; |
| 493 | |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 494 | /* |
| 495 | * Begin a reference transaction. The reference transaction must |
Ronnie Sahlberg | 33f9fc5 | 2014-06-20 07:42:43 -0700 | [diff] [blame] | 496 | * be freed by calling ref_transaction_free(). |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 497 | */ |
Nguyễn Thái Ngọc Duy | c0fe4e8 | 2017-03-26 09:42:35 +0700 | [diff] [blame] | 498 | struct ref_transaction *ref_store_transaction_begin(struct ref_store *refs, |
| 499 | struct strbuf *err); |
Ronnie Sahlberg | 93a644e | 2014-05-19 10:42:34 -0700 | [diff] [blame] | 500 | struct ref_transaction *ref_transaction_begin(struct strbuf *err); |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 501 | |
| 502 | /* |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 503 | * Reference transaction updates |
| 504 | * |
| 505 | * The following four functions add a reference check or update to a |
| 506 | * ref_transaction. They have some common similar parameters: |
| 507 | * |
| 508 | * transaction -- a pointer to an open ref_transaction, obtained |
| 509 | * from ref_transaction_begin(). |
| 510 | * |
| 511 | * refname -- the name of the reference to be affected. |
| 512 | * |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 513 | * new_oid -- the object ID that should be set to be the new value |
| 514 | * of the reference. Some functions allow this parameter to be |
Michael Haggerty | fd2ce9c | 2017-05-22 16:17:32 +0200 | [diff] [blame] | 515 | * NULL, meaning that the reference is not changed, or |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 516 | * null_oid, meaning that the reference should be deleted. A |
Michael Haggerty | fd2ce9c | 2017-05-22 16:17:32 +0200 | [diff] [blame] | 517 | * copy of this value is made in the transaction. |
| 518 | * |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 519 | * old_oid -- the object ID that the reference must have before |
Michael Haggerty | fd2ce9c | 2017-05-22 16:17:32 +0200 | [diff] [blame] | 520 | * the update. Some functions allow this parameter to be NULL, |
| 521 | * meaning that the old value of the reference is not checked, |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 522 | * or null_oid, meaning that the reference must not exist |
Michael Haggerty | fd2ce9c | 2017-05-22 16:17:32 +0200 | [diff] [blame] | 523 | * before the update. A copy of this value is made in the |
| 524 | * transaction. |
| 525 | * |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 526 | * flags -- flags affecting the update, passed to |
Michael Haggerty | 91774af | 2017-11-05 09:42:06 +0100 | [diff] [blame] | 527 | * update_ref_lock(). Possible flags: REF_NO_DEREF, |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 528 | * REF_FORCE_CREATE_REFLOG. See those constants for more |
| 529 | * information. |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 530 | * |
| 531 | * msg -- a message describing the change (for the reflog). |
| 532 | * |
| 533 | * err -- a strbuf for receiving a description of any error that |
Peter Colberg | dc72b50 | 2016-06-10 15:05:26 -0400 | [diff] [blame] | 534 | * might have occurred. |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 535 | * |
| 536 | * The functions make internal copies of refname and msg, so the |
| 537 | * caller retains ownership of these parameters. |
| 538 | * |
| 539 | * The functions return 0 on success and non-zero on failure. A |
| 540 | * failure means that the transaction as a whole has failed and needs |
| 541 | * to be rolled back. |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 542 | */ |
| 543 | |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 544 | /* |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 545 | * The following flags can be passed to ref_transaction_update() etc. |
| 546 | * Internally, they are stored in `ref_update::flags`, along with some |
| 547 | * internal flags. |
| 548 | */ |
| 549 | |
| 550 | /* |
| 551 | * Act on the ref directly; i.e., without dereferencing symbolic refs. |
| 552 | * If this flag is not specified, then symbolic references are |
| 553 | * dereferenced and the update is applied to the referent. |
| 554 | */ |
Michael Haggerty | 91774af | 2017-11-05 09:42:06 +0100 | [diff] [blame] | 555 | #define REF_NO_DEREF (1 << 0) |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 556 | |
| 557 | /* |
| 558 | * Force the creation of a reflog for this reference, even if it |
| 559 | * didn't previously have a reflog. |
| 560 | */ |
| 561 | #define REF_FORCE_CREATE_REFLOG (1 << 1) |
| 562 | |
| 563 | /* |
| 564 | * Bitmask of all of the flags that are allowed to be passed in to |
| 565 | * ref_transaction_update() and friends: |
| 566 | */ |
| 567 | #define REF_TRANSACTION_UPDATE_ALLOWED_FLAGS \ |
Michael Haggerty | 91774af | 2017-11-05 09:42:06 +0100 | [diff] [blame] | 568 | (REF_NO_DEREF | REF_FORCE_CREATE_REFLOG) |
Michael Haggerty | 5ac95fe | 2017-11-05 09:42:05 +0100 | [diff] [blame] | 569 | |
| 570 | /* |
| 571 | * Add a reference update to transaction. `new_oid` is the value that |
| 572 | * the reference should have after the update, or `null_oid` if it |
| 573 | * should be deleted. If `new_oid` is NULL, then the reference is not |
| 574 | * changed at all. `old_oid` is the value that the reference must have |
| 575 | * before the update, or `null_oid` if it must not have existed |
Michael Haggerty | 1618033 | 2015-02-17 18:00:21 +0100 | [diff] [blame] | 576 | * 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] | 577 | * prevent races. If the old value doesn't agree with old_oid, the |
| 578 | * whole transaction fails. If old_oid is NULL, then the previous |
Michael Haggerty | 1618033 | 2015-02-17 18:00:21 +0100 | [diff] [blame] | 579 | * value is not checked. |
| 580 | * |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 581 | * See the above comment "Reference transaction updates" for more |
| 582 | * information. |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 583 | */ |
Ronnie Sahlberg | 8e34800 | 2014-06-20 07:43:00 -0700 | [diff] [blame] | 584 | int ref_transaction_update(struct ref_transaction *transaction, |
| 585 | const char *refname, |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 586 | const struct object_id *new_oid, |
| 587 | const struct object_id *old_oid, |
Michael Haggerty | 1d147bd | 2015-02-17 18:00:15 +0100 | [diff] [blame] | 588 | unsigned int flags, const char *msg, |
Ronnie Sahlberg | 8e34800 | 2014-06-20 07:43:00 -0700 | [diff] [blame] | 589 | struct strbuf *err); |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 590 | |
| 591 | /* |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 592 | * Add a reference creation to transaction. new_oid is the value that |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 593 | * the reference should have after the update; it must not be |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 594 | * null_oid. It is verified that the reference does not exist |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 595 | * already. |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 596 | * |
| 597 | * See the above comment "Reference transaction updates" for more |
| 598 | * information. |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 599 | */ |
Ronnie Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 600 | int ref_transaction_create(struct ref_transaction *transaction, |
| 601 | const char *refname, |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 602 | const struct object_id *new_oid, |
Michael Haggerty | fec14ec | 2015-02-17 18:00:13 +0100 | [diff] [blame] | 603 | unsigned int flags, const char *msg, |
Ronnie Sahlberg | b416af5 | 2014-04-16 15:26:44 -0700 | [diff] [blame] | 604 | struct strbuf *err); |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 605 | |
| 606 | /* |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 607 | * Add a reference deletion to transaction. If old_oid is non-NULL, |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 608 | * 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] | 609 | * the update (which must not be null_oid). |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 610 | * |
| 611 | * See the above comment "Reference transaction updates" for more |
| 612 | * information. |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 613 | */ |
Ronnie Sahlberg | 8c8bdc0 | 2014-04-16 15:27:45 -0700 | [diff] [blame] | 614 | int ref_transaction_delete(struct ref_transaction *transaction, |
| 615 | const char *refname, |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 616 | const struct object_id *old_oid, |
Michael Haggerty | fb5a6bb | 2015-02-17 18:00:16 +0100 | [diff] [blame] | 617 | unsigned int flags, const char *msg, |
Ronnie Sahlberg | 8c8bdc0 | 2014-04-16 15:27:45 -0700 | [diff] [blame] | 618 | struct strbuf *err); |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 619 | |
| 620 | /* |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 621 | * Verify, within a transaction, that refname has the value old_oid, |
| 622 | * or, if old_oid is null_oid, then verify that the reference |
| 623 | * doesn't exist. old_oid must be non-NULL. |
Michael Haggerty | d1dd721 | 2015-02-17 18:00:23 +0100 | [diff] [blame] | 624 | * |
| 625 | * See the above comment "Reference transaction updates" for more |
| 626 | * information. |
Michael Haggerty | 1618033 | 2015-02-17 18:00:21 +0100 | [diff] [blame] | 627 | */ |
| 628 | int ref_transaction_verify(struct ref_transaction *transaction, |
| 629 | const char *refname, |
brian m. carlson | 89f3bbd | 2017-10-15 22:06:53 +0000 | [diff] [blame] | 630 | const struct object_id *old_oid, |
Michael Haggerty | 1618033 | 2015-02-17 18:00:21 +0100 | [diff] [blame] | 631 | unsigned int flags, |
| 632 | struct strbuf *err); |
| 633 | |
Ronnie Sahlberg | 28e6a97 | 2014-05-16 14:14:38 -0700 | [diff] [blame] | 634 | /* Naming conflict (for example, the ref names A and A/B conflict). */ |
| 635 | #define TRANSACTION_NAME_CONFLICT -1 |
| 636 | /* All other errors. */ |
| 637 | #define TRANSACTION_GENERIC_ERROR -2 |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 638 | |
| 639 | /* |
Ville Skyttä | 6412757 | 2017-06-25 13:20:41 +0300 | [diff] [blame] | 640 | * Perform the preparatory stages of committing `transaction`. Acquire |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 641 | * any needed locks, check preconditions, etc.; basically, do as much |
| 642 | * as possible to ensure that the transaction will be able to go |
| 643 | * through, stopping just short of making any irrevocable or |
| 644 | * user-visible changes. The updates that this function prepares can |
| 645 | * be finished up by calling `ref_transaction_commit()` or rolled back |
| 646 | * by calling `ref_transaction_abort()`. |
| 647 | * |
| 648 | * On success, return 0 and leave the transaction in "prepared" state. |
| 649 | * On failure, abort the transaction, write an error message to `err`, |
| 650 | * and return one of the `TRANSACTION_*` constants. |
| 651 | * |
Ville Skyttä | 6412757 | 2017-06-25 13:20:41 +0300 | [diff] [blame] | 652 | * Callers who don't need such fine-grained control over committing |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 653 | * reference transactions should just call `ref_transaction_commit()`. |
| 654 | */ |
| 655 | int ref_transaction_prepare(struct ref_transaction *transaction, |
| 656 | struct strbuf *err); |
| 657 | |
| 658 | /* |
| 659 | * Commit all of the changes that have been queued in transaction, as |
| 660 | * atomically as possible. On success, return 0 and leave the |
| 661 | * transaction in "closed" state. On failure, roll back the |
| 662 | * transaction, write an error message to `err`, and return one of the |
| 663 | * `TRANSACTION_*` constants |
| 664 | */ |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 665 | int ref_transaction_commit(struct ref_transaction *transaction, |
Ronnie Sahlberg | db7516a | 2014-04-30 12:22:42 -0700 | [diff] [blame] | 666 | struct strbuf *err); |
Michael Haggerty | caa4046 | 2014-04-07 15:48:10 +0200 | [diff] [blame] | 667 | |
Ronnie Sahlberg | 026bd1d | 2014-06-20 07:42:42 -0700 | [diff] [blame] | 668 | /* |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 669 | * Abort `transaction`, which has been begun and possibly prepared, |
| 670 | * but not yet committed. |
| 671 | */ |
| 672 | int ref_transaction_abort(struct ref_transaction *transaction, |
| 673 | struct strbuf *err); |
| 674 | |
| 675 | /* |
Michael Haggerty | 58f233c | 2015-06-22 16:03:01 +0200 | [diff] [blame] | 676 | * Like ref_transaction_commit(), but optimized for creating |
| 677 | * references when originally initializing a repository (e.g., by "git |
| 678 | * clone"). It writes the new references directly to packed-refs |
| 679 | * without locking the individual references. |
| 680 | * |
| 681 | * It is a bug to call this function when there might be other |
| 682 | * processes accessing the repository or if there are existing |
| 683 | * references that might conflict with the ones being created. All |
Michael Haggerty | 78fb457 | 2017-11-05 09:42:09 +0100 | [diff] [blame] | 684 | * old_oid values must either be absent or null_oid. |
Michael Haggerty | 58f233c | 2015-06-22 16:03:01 +0200 | [diff] [blame] | 685 | */ |
| 686 | int initial_ref_transaction_commit(struct ref_transaction *transaction, |
| 687 | struct strbuf *err); |
| 688 | |
| 689 | /* |
Michael Haggerty | 30173b8 | 2017-05-22 16:17:44 +0200 | [diff] [blame] | 690 | * Free `*transaction` and all associated data. |
Ronnie Sahlberg | 026bd1d | 2014-06-20 07:42:42 -0700 | [diff] [blame] | 691 | */ |
| 692 | void ref_transaction_free(struct ref_transaction *transaction); |
| 693 | |
Michael Haggerty | 4b7b520 | 2015-02-17 18:00:22 +0100 | [diff] [blame] | 694 | /** |
| 695 | * Lock, update, and unlock a single reference. This function |
| 696 | * basically does a transaction containing a single call to |
| 697 | * ref_transaction_update(). The parameters to this function have the |
| 698 | * same meaning as the corresponding parameters to |
| 699 | * ref_transaction_update(). Handle errors as requested by the `onerr` |
| 700 | * argument. |
| 701 | */ |
Nguyễn Thái Ngọc Duy | c0fe4e8 | 2017-03-26 09:42:35 +0700 | [diff] [blame] | 702 | 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] | 703 | 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] | 704 | unsigned int flags, enum action_on_err onerr); |
Michael Haggerty | 4b7b520 | 2015-02-17 18:00:22 +0100 | [diff] [blame] | 705 | int update_ref(const char *msg, const char *refname, |
brian m. carlson | 8f6dc7e | 2016-09-05 20:08:08 +0000 | [diff] [blame] | 706 | const struct object_id *new_oid, const struct object_id *old_oid, |
| 707 | unsigned int flags, enum action_on_err onerr); |
Carlos Rica | 3d9f037 | 2007-09-05 03:38:24 +0200 | [diff] [blame] | 708 | |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 709 | int parse_hide_refs_config(const char *var, const char *value, const char *); |
Michael Haggerty | fb58c8d | 2015-06-22 16:03:05 +0200 | [diff] [blame] | 710 | |
Lukas Fleischer | 78a766a | 2015-11-03 08:58:16 +0100 | [diff] [blame] | 711 | /* |
| 712 | * Check whether a ref is hidden. If no namespace is set, both the first and |
| 713 | * the second parameter point to the full ref name. If a namespace is set and |
| 714 | * the ref is inside that namespace, the first parameter is a pointer to the |
| 715 | * name of the ref with the namespace prefix removed. If a namespace is set and |
| 716 | * the ref is outside that namespace, the first parameter is NULL. The second |
| 717 | * parameter always points to the full ref name. |
| 718 | */ |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 719 | int ref_is_hidden(const char *, const char *); |
Junio C Hamano | daebaa7 | 2013-01-18 16:08:30 -0800 | [diff] [blame] | 720 | |
David Turner | 266b182 | 2015-07-31 02:06:18 -0400 | [diff] [blame] | 721 | enum ref_type { |
Nguyễn Thái Ngọc Duy | 3a3b9d8 | 2018-10-21 10:08:54 +0200 | [diff] [blame] | 722 | REF_TYPE_PER_WORKTREE, /* refs inside refs/ but not shared */ |
| 723 | REF_TYPE_PSEUDOREF, /* refs outside refs/ in current worktree */ |
| 724 | REF_TYPE_MAIN_PSEUDOREF, /* pseudo refs from the main worktree */ |
| 725 | REF_TYPE_OTHER_PSEUDOREF, /* pseudo refs from other worktrees */ |
| 726 | REF_TYPE_NORMAL, /* normal/shared refs inside refs/ */ |
David Turner | 266b182 | 2015-07-31 02:06:18 -0400 | [diff] [blame] | 727 | }; |
| 728 | |
| 729 | enum ref_type ref_type(const char *refname); |
| 730 | |
Michael Haggerty | fa5b183 | 2014-12-12 09:56:59 +0100 | [diff] [blame] | 731 | enum expire_reflog_flags { |
| 732 | EXPIRE_REFLOGS_DRY_RUN = 1 << 0, |
| 733 | EXPIRE_REFLOGS_UPDATE_REF = 1 << 1, |
| 734 | EXPIRE_REFLOGS_VERBOSE = 1 << 2, |
| 735 | EXPIRE_REFLOGS_REWRITE = 1 << 3 |
| 736 | }; |
| 737 | |
| 738 | /* |
| 739 | * The following interface is used for reflog expiration. The caller |
| 740 | * calls reflog_expire(), supplying it with three callback functions, |
| 741 | * of the following types. The callback functions define the |
| 742 | * expiration policy that is desired. |
| 743 | * |
| 744 | * reflog_expiry_prepare_fn -- Called once after the reference is |
| 745 | * locked. |
| 746 | * |
| 747 | * reflog_expiry_should_prune_fn -- Called once for each entry in the |
| 748 | * existing reflog. It should return true iff that entry should be |
| 749 | * pruned. |
| 750 | * |
| 751 | * reflog_expiry_cleanup_fn -- Called once before the reference is |
| 752 | * unlocked again. |
| 753 | */ |
| 754 | typedef void reflog_expiry_prepare_fn(const char *refname, |
brian m. carlson | 4322478 | 2017-05-06 22:10:00 +0000 | [diff] [blame] | 755 | const struct object_id *oid, |
Michael Haggerty | fa5b183 | 2014-12-12 09:56:59 +0100 | [diff] [blame] | 756 | void *cb_data); |
brian m. carlson | 4322478 | 2017-05-06 22:10:00 +0000 | [diff] [blame] | 757 | typedef int reflog_expiry_should_prune_fn(struct object_id *ooid, |
| 758 | struct object_id *noid, |
Michael Haggerty | fa5b183 | 2014-12-12 09:56:59 +0100 | [diff] [blame] | 759 | const char *email, |
Johannes Schindelin | dddbad7 | 2017-04-26 21:29:31 +0200 | [diff] [blame] | 760 | timestamp_t timestamp, int tz, |
Michael Haggerty | fa5b183 | 2014-12-12 09:56:59 +0100 | [diff] [blame] | 761 | const char *message, void *cb_data); |
| 762 | typedef void reflog_expiry_cleanup_fn(void *cb_data); |
| 763 | |
| 764 | /* |
brian m. carlson | 0155f71 | 2017-10-15 22:07:04 +0000 | [diff] [blame] | 765 | * Expire reflog entries for the specified reference. oid is the old |
Michael Haggerty | fa5b183 | 2014-12-12 09:56:59 +0100 | [diff] [blame] | 766 | * value of the reference. flags is a combination of the constants in |
| 767 | * enum expire_reflog_flags. The three function pointers are described |
| 768 | * above. On success, return zero. |
| 769 | */ |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 770 | int refs_reflog_expire(struct ref_store *refs, |
| 771 | const char *refname, |
brian m. carlson | 0155f71 | 2017-10-15 22:07:04 +0000 | [diff] [blame] | 772 | const struct object_id *oid, |
Nguyễn Thái Ngọc Duy | 7d2df05 | 2017-03-26 09:42:34 +0700 | [diff] [blame] | 773 | unsigned int flags, |
| 774 | reflog_expiry_prepare_fn prepare_fn, |
| 775 | reflog_expiry_should_prune_fn should_prune_fn, |
| 776 | reflog_expiry_cleanup_fn cleanup_fn, |
| 777 | void *policy_cb_data); |
brian m. carlson | 0155f71 | 2017-10-15 22:07:04 +0000 | [diff] [blame] | 778 | int reflog_expire(const char *refname, const struct object_id *oid, |
Michael Haggerty | 1354c9b | 2016-03-31 06:19:22 +0200 | [diff] [blame] | 779 | unsigned int flags, |
| 780 | reflog_expiry_prepare_fn prepare_fn, |
| 781 | reflog_expiry_should_prune_fn should_prune_fn, |
| 782 | reflog_expiry_cleanup_fn cleanup_fn, |
| 783 | void *policy_cb_data); |
Michael Haggerty | fa5b183 | 2014-12-12 09:56:59 +0100 | [diff] [blame] | 784 | |
Ronnie Sahlberg | 3dce444 | 2016-09-04 18:08:10 +0200 | [diff] [blame] | 785 | int ref_storage_backend_exists(const char *name); |
| 786 | |
Stefan Beller | 64a7416 | 2018-04-11 17:21:14 -0700 | [diff] [blame] | 787 | struct ref_store *get_main_ref_store(struct repository *r); |
Nguyễn Thái Ngọc Duy | 18d0002 | 2017-03-26 09:42:33 +0700 | [diff] [blame] | 788 | /* |
| 789 | * Return the ref_store instance for the specified submodule. For the |
| 790 | * main repository, use submodule==NULL; such a call cannot fail. For |
| 791 | * a submodule, the submodule must exist and be a nonbare repository, |
| 792 | * otherwise return NULL. If the requested reference store has not yet |
| 793 | * been initialized, initialize it first. |
| 794 | * |
| 795 | * For backwards compatibility, submodule=="" is treated the same as |
| 796 | * submodule==NULL. |
| 797 | */ |
| 798 | 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] | 799 | 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] | 800 | |
Daniel Barkalow | 95fc751 | 2005-06-06 16:31:29 -0400 | [diff] [blame] | 801 | #endif /* REFS_H */ |