1#ifndef REFS_REFS_INTERNAL_H 2#define REFS_REFS_INTERNAL_H 3 4/* 5 * Data structures and functions for the internal use of the refs 6 * module. Code outside of the refs module should use only the public 7 * functions defined in "refs.h", and should *not* include this file. 8 */ 9 10/* 11 * Flag passed to lock_ref_sha1_basic() telling it to tolerate broken 12 * refs (i.e., because the reference is about to be deleted anyway). 13 */ 14#define REF_DELETING 0x02 15 16/* 17 * Used as a flag in ref_update::flags when a loose ref is being 18 * pruned. This flag must only be used when REF_NODEREF is set. 19 */ 20#define REF_ISPRUNING 0x04 21 22/* 23 * Used as a flag in ref_update::flags when the reference should be 24 * updated to new_sha1. 25 */ 26#define REF_HAVE_NEW 0x08 27 28/* 29 * Used as a flag in ref_update::flags when old_sha1 should be 30 * checked. 31 */ 32#define REF_HAVE_OLD 0x10 33 34/* 35 * Used as a flag in ref_update::flags when the lockfile needs to be 36 * committed. 37 */ 38#define REF_NEEDS_COMMIT 0x20 39 40/* 41 * 0x40 is REF_FORCE_CREATE_REFLOG, so skip it if you're adding a 42 * value to ref_update::flags 43 */ 44 45/* 46 * Used as a flag in ref_update::flags when we want to log a ref 47 * update but not actually perform it. This is used when a symbolic 48 * ref update is split up. 49 */ 50#define REF_LOG_ONLY 0x80 51 52/* 53 * Internal flag, meaning that the containing ref_update was via an 54 * update to HEAD. 55 */ 56#define REF_UPDATE_VIA_HEAD 0x100 57 58/* 59 * Used as a flag in ref_update::flags when the loose reference has 60 * been deleted. 61 */ 62#define REF_DELETED_LOOSE 0x200 63 64/* 65 * Return true iff refname is minimally safe. "Safe" here means that 66 * deleting a loose reference by this name will not do any damage, for 67 * example by causing a file that is not a reference to be deleted. 68 * This function does not check that the reference name is legal; for 69 * that, use check_refname_format(). 70 * 71 * A refname that starts with "refs/" is considered safe iff it 72 * doesn't contain any "." or ".." components or consecutive '/' 73 * characters, end with '/', or (on Windows) contain any '\' 74 * characters. Names that do not start with "refs/" are considered 75 * safe iff they consist entirely of upper case characters and '_' 76 * (like "HEAD" and "MERGE_HEAD" but not "config" or "FOO/BAR"). 77 */ 78intrefname_is_safe(const char*refname); 79 80enum peel_status { 81/* object was peeled successfully: */ 82 PEEL_PEELED =0, 83 84/* 85 * object cannot be peeled because the named object (or an 86 * object referred to by a tag in the peel chain), does not 87 * exist. 88 */ 89 PEEL_INVALID = -1, 90 91/* object cannot be peeled because it is not a tag: */ 92 PEEL_NON_TAG = -2, 93 94/* ref_entry contains no peeled value because it is a symref: */ 95 PEEL_IS_SYMREF = -3, 96 97/* 98 * ref_entry cannot be peeled because it is broken (i.e., the 99 * symbolic reference cannot even be resolved to an object 100 * name): 101 */ 102 PEEL_BROKEN = -4 103}; 104 105/* 106 * Peel the named object; i.e., if the object is a tag, resolve the 107 * tag recursively until a non-tag is found. If successful, store the 108 * result to sha1 and return PEEL_PEELED. If the object is not a tag 109 * or is not valid, return PEEL_NON_TAG or PEEL_INVALID, respectively, 110 * and leave sha1 unchanged. 111 */ 112enum peel_status peel_object(const unsigned char*name,unsigned char*sha1); 113 114/* 115 * Return 0 if a reference named refname could be created without 116 * conflicting with the name of an existing reference. Otherwise, 117 * return a negative value and write an explanation to err. If extras 118 * is non-NULL, it is a list of additional refnames with which refname 119 * is not allowed to conflict. If skip is non-NULL, ignore potential 120 * conflicts with refs in skip (e.g., because they are scheduled for 121 * deletion in the same operation). Behavior is undefined if the same 122 * name is listed in both extras and skip. 123 * 124 * Two reference names conflict if one of them exactly matches the 125 * leading components of the other; e.g., "foo/bar" conflicts with 126 * both "foo" and with "foo/bar/baz" but not with "foo/bar" or 127 * "foo/barbados". 128 * 129 * extras and skip must be sorted. 130 */ 131intverify_refname_available(const char*newname, 132const struct string_list *extras, 133const struct string_list *skip, 134struct strbuf *err); 135 136/* 137 * Copy the reflog message msg to buf, which has been allocated sufficiently 138 * large, while cleaning up the whitespaces. Especially, convert LF to space, 139 * because reflog file is one line per entry. 140 */ 141intcopy_reflog_msg(char*buf,const char*msg); 142 143/** 144 * Information needed for a single ref update. Set new_sha1 to the new 145 * value or to null_sha1 to delete the ref. To check the old value 146 * while the ref is locked, set (flags & REF_HAVE_OLD) and set 147 * old_sha1 to the old value, or to null_sha1 to ensure the ref does 148 * not exist before update. 149 */ 150struct ref_update { 151 152/* 153 * If (flags & REF_HAVE_NEW), set the reference to this value: 154 */ 155unsigned char new_sha1[20]; 156 157/* 158 * If (flags & REF_HAVE_OLD), check that the reference 159 * previously had this value: 160 */ 161unsigned char old_sha1[20]; 162 163/* 164 * One or more of REF_HAVE_NEW, REF_HAVE_OLD, REF_NODEREF, 165 * REF_DELETING, REF_ISPRUNING, REF_LOG_ONLY, 166 * REF_UPDATE_VIA_HEAD, REF_NEEDS_COMMIT, and 167 * REF_DELETED_LOOSE: 168 */ 169unsigned int flags; 170 171void*backend_data; 172unsigned int type; 173char*msg; 174 175/* 176 * If this ref_update was split off of a symref update via 177 * split_symref_update(), then this member points at that 178 * update. This is used for two purposes: 179 * 1. When reporting errors, we report the refname under which 180 * the update was originally requested. 181 * 2. When we read the old value of this reference, we 182 * propagate it back to its parent update for recording in 183 * the latter's reflog. 184 */ 185struct ref_update *parent_update; 186 187const char refname[FLEX_ARRAY]; 188}; 189 190/* 191 * Add a ref_update with the specified properties to transaction, and 192 * return a pointer to the new object. This function does not verify 193 * that refname is well-formed. new_sha1 and old_sha1 are only 194 * dereferenced if the REF_HAVE_NEW and REF_HAVE_OLD bits, 195 * respectively, are set in flags. 196 */ 197struct ref_update *ref_transaction_add_update( 198struct ref_transaction *transaction, 199const char*refname,unsigned int flags, 200const unsigned char*new_sha1, 201const unsigned char*old_sha1, 202const char*msg); 203 204/* 205 * Transaction states. 206 * OPEN: The transaction is in a valid state and can accept new updates. 207 * An OPEN transaction can be committed. 208 * CLOSED: A closed transaction is no longer active and no other operations 209 * than free can be used on it in this state. 210 * A transaction can either become closed by successfully committing 211 * an active transaction or if there is a failure while building 212 * the transaction thus rendering it failed/inactive. 213 */ 214enum ref_transaction_state { 215 REF_TRANSACTION_OPEN =0, 216 REF_TRANSACTION_CLOSED =1 217}; 218 219/* 220 * Data structure for holding a reference transaction, which can 221 * consist of checks and updates to multiple references, carried out 222 * as atomically as possible. This structure is opaque to callers. 223 */ 224struct ref_transaction { 225struct ref_update **updates; 226size_t alloc; 227size_t nr; 228enum ref_transaction_state state; 229}; 230 231/* 232 * Check for entries in extras that are within the specified 233 * directory, where dirname is a reference directory name including 234 * the trailing slash (e.g., "refs/heads/foo/"). Ignore any 235 * conflicting references that are found in skip. If there is a 236 * conflicting reference, return its name. 237 * 238 * extras and skip must be sorted lists of reference names. Either one 239 * can be NULL, signifying the empty list. 240 */ 241const char*find_descendant_ref(const char*dirname, 242const struct string_list *extras, 243const struct string_list *skip); 244 245/* 246 * Check whether an attempt to rename old_refname to new_refname would 247 * cause a D/F conflict with any existing reference (other than 248 * possibly old_refname). If there would be a conflict, emit an error 249 * message and return false; otherwise, return true. 250 * 251 * Note that this function is not safe against all races with other 252 * processes (though rename_ref() catches some races that might get by 253 * this check). 254 */ 255intrename_ref_available(const char*old_refname,const char*new_refname); 256 257/* We allow "recursive" symbolic refs. Only within reason, though */ 258#define SYMREF_MAXDEPTH 5 259 260/* Include broken references in a do_for_each_ref*() iteration: */ 261#define DO_FOR_EACH_INCLUDE_BROKEN 0x01 262 263/* 264 * Reference iterators 265 * 266 * A reference iterator encapsulates the state of an in-progress 267 * iteration over references. Create an instance of `struct 268 * ref_iterator` via one of the functions in this module. 269 * 270 * A freshly-created ref_iterator doesn't yet point at a reference. To 271 * advance the iterator, call ref_iterator_advance(). If successful, 272 * this sets the iterator's refname, oid, and flags fields to describe 273 * the next reference and returns ITER_OK. The data pointed at by 274 * refname and oid belong to the iterator; if you want to retain them 275 * after calling ref_iterator_advance() again or calling 276 * ref_iterator_abort(), you must make a copy. When the iteration has 277 * been exhausted, ref_iterator_advance() releases any resources 278 * assocated with the iteration, frees the ref_iterator object, and 279 * returns ITER_DONE. If you want to abort the iteration early, call 280 * ref_iterator_abort(), which also frees the ref_iterator object and 281 * any associated resources. If there was an internal error advancing 282 * to the next entry, ref_iterator_advance() aborts the iteration, 283 * frees the ref_iterator, and returns ITER_ERROR. 284 * 285 * The reference currently being looked at can be peeled by calling 286 * ref_iterator_peel(). This function is often faster than peel_ref(), 287 * so it should be preferred when iterating over references. 288 * 289 * Putting it all together, a typical iteration looks like this: 290 * 291 * int ok; 292 * struct ref_iterator *iter = ...; 293 * 294 * while ((ok = ref_iterator_advance(iter)) == ITER_OK) { 295 * if (want_to_stop_iteration()) { 296 * ok = ref_iterator_abort(iter); 297 * break; 298 * } 299 * 300 * // Access information about the current reference: 301 * if (!(iter->flags & REF_ISSYMREF)) 302 * printf("%s is %s\n", iter->refname, oid_to_hex(&iter->oid)); 303 * 304 * // If you need to peel the reference: 305 * ref_iterator_peel(iter, &oid); 306 * } 307 * 308 * if (ok != ITER_DONE) 309 * handle_error(); 310 */ 311struct ref_iterator { 312struct ref_iterator_vtable *vtable; 313const char*refname; 314const struct object_id *oid; 315unsigned int flags; 316}; 317 318/* 319 * Advance the iterator to the first or next item and return ITER_OK. 320 * If the iteration is exhausted, free the resources associated with 321 * the ref_iterator and return ITER_DONE. On errors, free the iterator 322 * resources and return ITER_ERROR. It is a bug to use ref_iterator or 323 * call this function again after it has returned ITER_DONE or 324 * ITER_ERROR. 325 */ 326intref_iterator_advance(struct ref_iterator *ref_iterator); 327 328/* 329 * If possible, peel the reference currently being viewed by the 330 * iterator. Return 0 on success. 331 */ 332intref_iterator_peel(struct ref_iterator *ref_iterator, 333struct object_id *peeled); 334 335/* 336 * End the iteration before it has been exhausted, freeing the 337 * reference iterator and any associated resources and returning 338 * ITER_DONE. If the abort itself failed, return ITER_ERROR. 339 */ 340intref_iterator_abort(struct ref_iterator *ref_iterator); 341 342/* 343 * An iterator over nothing (its first ref_iterator_advance() call 344 * returns ITER_DONE). 345 */ 346struct ref_iterator *empty_ref_iterator_begin(void); 347 348/* 349 * Return true iff ref_iterator is an empty_ref_iterator. 350 */ 351intis_empty_ref_iterator(struct ref_iterator *ref_iterator); 352 353/* 354 * A callback function used to instruct merge_ref_iterator how to 355 * interleave the entries from iter0 and iter1. The function should 356 * return one of the constants defined in enum iterator_selection. It 357 * must not advance either of the iterators itself. 358 * 359 * The function must be prepared to handle the case that iter0 and/or 360 * iter1 is NULL, which indicates that the corresponding sub-iterator 361 * has been exhausted. Its return value must be consistent with the 362 * current states of the iterators; e.g., it must not return 363 * ITER_SKIP_1 if iter1 has already been exhausted. 364 */ 365typedefenum iterator_selection ref_iterator_select_fn( 366struct ref_iterator *iter0,struct ref_iterator *iter1, 367void*cb_data); 368 369/* 370 * Iterate over the entries from iter0 and iter1, with the values 371 * interleaved as directed by the select function. The iterator takes 372 * ownership of iter0 and iter1 and frees them when the iteration is 373 * over. 374 */ 375struct ref_iterator *merge_ref_iterator_begin( 376struct ref_iterator *iter0,struct ref_iterator *iter1, 377 ref_iterator_select_fn *select,void*cb_data); 378 379/* 380 * An iterator consisting of the union of the entries from front and 381 * back. If there are entries common to the two sub-iterators, use the 382 * one from front. Each iterator must iterate over its entries in 383 * strcmp() order by refname for this to work. 384 * 385 * The new iterator takes ownership of its arguments and frees them 386 * when the iteration is over. As a convenience to callers, if front 387 * or back is an empty_ref_iterator, then abort that one immediately 388 * and return the other iterator directly, without wrapping it. 389 */ 390struct ref_iterator *overlay_ref_iterator_begin( 391struct ref_iterator *front,struct ref_iterator *back); 392 393/* 394 * Wrap iter0, only letting through the references whose names start 395 * with prefix. If trim is set, set iter->refname to the name of the 396 * reference with that many characters trimmed off the front; 397 * otherwise set it to the full refname. The new iterator takes over 398 * ownership of iter0 and frees it when iteration is over. It makes 399 * its own copy of prefix. 400 * 401 * As an convenience to callers, if prefix is the empty string and 402 * trim is zero, this function returns iter0 directly, without 403 * wrapping it. 404 */ 405struct ref_iterator *prefix_ref_iterator_begin(struct ref_iterator *iter0, 406const char*prefix, 407int trim); 408 409/* Internal implementation of reference iteration: */ 410 411/* 412 * Base class constructor for ref_iterators. Initialize the 413 * ref_iterator part of iter, setting its vtable pointer as specified. 414 * This is meant to be called only by the initializers of derived 415 * classes. 416 */ 417voidbase_ref_iterator_init(struct ref_iterator *iter, 418struct ref_iterator_vtable *vtable); 419 420/* 421 * Base class destructor for ref_iterators. Destroy the ref_iterator 422 * part of iter and shallow-free the object. This is meant to be 423 * called only by the destructors of derived classes. 424 */ 425voidbase_ref_iterator_free(struct ref_iterator *iter); 426 427/* Virtual function declarations for ref_iterators: */ 428 429typedefintref_iterator_advance_fn(struct ref_iterator *ref_iterator); 430 431typedefintref_iterator_peel_fn(struct ref_iterator *ref_iterator, 432struct object_id *peeled); 433 434/* 435 * Implementations of this function should free any resources specific 436 * to the derived class, then call base_ref_iterator_free() to clean 437 * up and free the ref_iterator object. 438 */ 439typedefintref_iterator_abort_fn(struct ref_iterator *ref_iterator); 440 441struct ref_iterator_vtable { 442 ref_iterator_advance_fn *advance; 443 ref_iterator_peel_fn *peel; 444 ref_iterator_abort_fn *abort; 445}; 446 447/* 448 * current_ref_iter is a performance hack: when iterating over 449 * references using the for_each_ref*() functions, current_ref_iter is 450 * set to the reference iterator before calling the callback function. 451 * If the callback function calls peel_ref(), then peel_ref() first 452 * checks whether the reference to be peeled is the one referred to by 453 * the iterator (it usually is) and if so, asks the iterator for the 454 * peeled version of the reference if it is available. This avoids a 455 * refname lookup in a common case. current_ref_iter is set to NULL 456 * when the iteration is over. 457 */ 458externstruct ref_iterator *current_ref_iter; 459 460/* 461 * The common backend for the for_each_*ref* functions. Call fn for 462 * each reference in iter. If the iterator itself ever returns 463 * ITER_ERROR, return -1. If fn ever returns a non-zero value, stop 464 * the iteration and return that value. Otherwise, return 0. In any 465 * case, free the iterator when done. This function is basically an 466 * adapter between the callback style of reference iteration and the 467 * iterator style. 468 */ 469intdo_for_each_ref_iterator(struct ref_iterator *iter, 470 each_ref_fn fn,void*cb_data); 471 472/* 473 * Only include per-worktree refs in a do_for_each_ref*() iteration. 474 * Normally this will be used with a files ref_store, since that's 475 * where all reference backends will presumably store their 476 * per-worktree refs. 477 */ 478#define DO_FOR_EACH_PER_WORKTREE_ONLY 0x02 479 480struct ref_store; 481 482/* refs backends */ 483 484/* 485 * Initialize the ref_store for the specified submodule, or for the 486 * main repository if submodule == NULL. These functions should call 487 * base_ref_store_init() to initialize the shared part of the 488 * ref_store and to record the ref_store for later lookup. 489 */ 490typedefstruct ref_store *ref_store_init_fn(const char*submodule); 491 492typedefintref_init_db_fn(struct ref_store *refs,struct strbuf *err); 493 494typedefintref_transaction_commit_fn(struct ref_store *refs, 495struct ref_transaction *transaction, 496struct strbuf *err); 497 498typedefintpack_refs_fn(struct ref_store *ref_store,unsigned int flags); 499typedefintpeel_ref_fn(struct ref_store *ref_store, 500const char*refname,unsigned char*sha1); 501typedefintcreate_symref_fn(struct ref_store *ref_store, 502const char*ref_target, 503const char*refs_heads_master, 504const char*logmsg); 505typedefintdelete_refs_fn(struct ref_store *ref_store, 506struct string_list *refnames,unsigned int flags); 507typedefintrename_ref_fn(struct ref_store *ref_store, 508const char*oldref,const char*newref, 509const char*logmsg); 510 511/* 512 * Iterate over the references in the specified ref_store that are 513 * within find_containing_dir(prefix). If prefix is NULL or the empty 514 * string, iterate over all references in the submodule. 515 */ 516typedefstruct ref_iterator *ref_iterator_begin_fn( 517struct ref_store *ref_store, 518const char*prefix,unsigned int flags); 519 520/* reflog functions */ 521 522/* 523 * Iterate over the references in the specified ref_store that have a 524 * reflog. The refs are iterated over in arbitrary order. 525 */ 526typedefstruct ref_iterator *reflog_iterator_begin_fn( 527struct ref_store *ref_store); 528 529typedefintfor_each_reflog_ent_fn(struct ref_store *ref_store, 530const char*refname, 531 each_reflog_ent_fn fn, 532void*cb_data); 533typedefintfor_each_reflog_ent_reverse_fn(struct ref_store *ref_store, 534const char*refname, 535 each_reflog_ent_fn fn, 536void*cb_data); 537typedefintreflog_exists_fn(struct ref_store *ref_store,const char*refname); 538typedefintcreate_reflog_fn(struct ref_store *ref_store,const char*refname, 539int force_create,struct strbuf *err); 540typedefintdelete_reflog_fn(struct ref_store *ref_store,const char*refname); 541typedefintreflog_expire_fn(struct ref_store *ref_store, 542const char*refname,const unsigned char*sha1, 543unsigned int flags, 544 reflog_expiry_prepare_fn prepare_fn, 545 reflog_expiry_should_prune_fn should_prune_fn, 546 reflog_expiry_cleanup_fn cleanup_fn, 547void*policy_cb_data); 548 549/* 550 * Read a reference from the specified reference store, non-recursively. 551 * Set type to describe the reference, and: 552 * 553 * - If refname is the name of a normal reference, fill in sha1 554 * (leaving referent unchanged). 555 * 556 * - If refname is the name of a symbolic reference, write the full 557 * name of the reference to which it refers (e.g. 558 * "refs/heads/master") to referent and set the REF_ISSYMREF bit in 559 * type (leaving sha1 unchanged). The caller is responsible for 560 * validating that referent is a valid reference name. 561 * 562 * WARNING: refname might be used as part of a filename, so it is 563 * important from a security standpoint that it be safe in the sense 564 * of refname_is_safe(). Moreover, for symrefs this function sets 565 * referent to whatever the repository says, which might not be a 566 * properly-formatted or even safe reference name. NEITHER INPUT NOR 567 * OUTPUT REFERENCE NAMES ARE VALIDATED WITHIN THIS FUNCTION. 568 * 569 * Return 0 on success. If the ref doesn't exist, set errno to ENOENT 570 * and return -1. If the ref exists but is neither a symbolic ref nor 571 * a sha1, it is broken; set REF_ISBROKEN in type, set errno to 572 * EINVAL, and return -1. If there is another error reading the ref, 573 * set errno appropriately and return -1. 574 * 575 * Backend-specific flags might be set in type as well, regardless of 576 * outcome. 577 * 578 * It is OK for refname to point into referent. If so: 579 * 580 * - if the function succeeds with REF_ISSYMREF, referent will be 581 * overwritten and the memory formerly pointed to by it might be 582 * changed or even freed. 583 * 584 * - in all other cases, referent will be untouched, and therefore 585 * refname will still be valid and unchanged. 586 */ 587typedefintread_raw_ref_fn(struct ref_store *ref_store, 588const char*refname,unsigned char*sha1, 589struct strbuf *referent,unsigned int*type); 590 591typedefintverify_refname_available_fn(struct ref_store *ref_store, 592const char*newname, 593const struct string_list *extras, 594const struct string_list *skip, 595struct strbuf *err); 596 597struct ref_storage_be { 598struct ref_storage_be *next; 599const char*name; 600 ref_store_init_fn *init; 601 ref_init_db_fn *init_db; 602 ref_transaction_commit_fn *transaction_commit; 603 ref_transaction_commit_fn *initial_transaction_commit; 604 605 pack_refs_fn *pack_refs; 606 peel_ref_fn *peel_ref; 607 create_symref_fn *create_symref; 608 delete_refs_fn *delete_refs; 609 rename_ref_fn *rename_ref; 610 611 ref_iterator_begin_fn *iterator_begin; 612 read_raw_ref_fn *read_raw_ref; 613 verify_refname_available_fn *verify_refname_available; 614 615 reflog_iterator_begin_fn *reflog_iterator_begin; 616 for_each_reflog_ent_fn *for_each_reflog_ent; 617 for_each_reflog_ent_reverse_fn *for_each_reflog_ent_reverse; 618 reflog_exists_fn *reflog_exists; 619 create_reflog_fn *create_reflog; 620 delete_reflog_fn *delete_reflog; 621 reflog_expire_fn *reflog_expire; 622}; 623 624externstruct ref_storage_be refs_be_files; 625 626/* 627 * A representation of the reference store for the main repository or 628 * a submodule. The ref_store instances for submodules are kept in a 629 * linked list. 630 */ 631struct ref_store { 632/* The backend describing this ref_store's storage scheme: */ 633const struct ref_storage_be *be; 634}; 635 636/* 637 * Fill in the generic part of refs and add it to our collection of 638 * reference stores. 639 */ 640voidbase_ref_store_init(struct ref_store *refs, 641const struct ref_storage_be *be); 642 643/* 644 * Return the ref_store instance for the specified submodule. For the 645 * main repository, use submodule==NULL; such a call cannot fail. For 646 * a submodule, the submodule must exist and be a nonbare repository, 647 * otherwise return NULL. If the requested reference store has not yet 648 * been initialized, initialize it first. 649 * 650 * For backwards compatibility, submodule=="" is treated the same as 651 * submodule==NULL. 652 */ 653struct ref_store *get_ref_store(const char*submodule); 654 655const char*resolve_ref_recursively(struct ref_store *refs, 656const char*refname, 657int resolve_flags, 658unsigned char*sha1,int*flags); 659 660#endif/* REFS_REFS_INTERNAL_H */