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