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