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