1#ifndef REFS_H 2#define REFS_H 3 4/* 5 * Resolve a reference, recursively following symbolic refererences. 6 * 7 * Store the referred-to object's name in sha1 and return the name of 8 * the non-symbolic reference that ultimately pointed at it. The 9 * return value, if not NULL, is a pointer into either a static buffer 10 * or the input ref. 11 * 12 * If the reference cannot be resolved to an object, the behavior 13 * depends on the RESOLVE_REF_READING flag: 14 * 15 * - If RESOLVE_REF_READING is set, return NULL. 16 * 17 * - If RESOLVE_REF_READING is not set, clear sha1 and return the name of 18 * the last reference name in the chain, which will either be a non-symbolic 19 * reference or an undefined reference. If this is a prelude to 20 * "writing" to the ref, the return value is the name of the ref 21 * that will actually be created or changed. 22 * 23 * If the RESOLVE_REF_NO_RECURSE flag is passed, only resolves one 24 * level of symbolic reference. The value stored in sha1 for a symbolic 25 * reference will always be null_sha1 in this case, and the return 26 * value is the reference that the symref refers to directly. 27 * 28 * If flags is non-NULL, set the value that it points to the 29 * combination of REF_ISPACKED (if the reference was found among the 30 * packed references), REF_ISSYMREF (if the initial reference was a 31 * symbolic reference), REF_BAD_NAME (if the reference name is ill 32 * formed --- see RESOLVE_REF_ALLOW_BAD_NAME below), and REF_ISBROKEN 33 * (if the ref is malformed or has a bad name). See refs.h for more detail 34 * on each flag. 35 * 36 * If ref is not a properly-formatted, normalized reference, return 37 * NULL. If more than MAXDEPTH recursive symbolic lookups are needed, 38 * give up and return NULL. 39 * 40 * RESOLVE_REF_ALLOW_BAD_NAME allows resolving refs even when their 41 * name is invalid according to git-check-ref-format(1). If the name 42 * is bad then the value stored in sha1 will be null_sha1 and the two 43 * flags REF_ISBROKEN and REF_BAD_NAME will be set. 44 * 45 * Even with RESOLVE_REF_ALLOW_BAD_NAME, names that escape the refs/ 46 * directory and do not consist of all caps and underscores cannot be 47 * resolved. The function returns NULL for such ref names. 48 * Caps and underscores refers to the special refs, such as HEAD, 49 * FETCH_HEAD and friends, that all live outside of the refs/ directory. 50 */ 51#define RESOLVE_REF_READING 0x01 52#define RESOLVE_REF_NO_RECURSE 0x02 53#define RESOLVE_REF_ALLOW_BAD_NAME 0x04 54 55const char*resolve_ref_unsafe(const char*refname,int resolve_flags, 56unsigned char*sha1,int*flags); 57 58char*resolve_refdup(const char*refname,int resolve_flags, 59unsigned char*sha1,int*flags); 60 61intread_ref_full(const char*refname,int resolve_flags, 62unsigned char*sha1,int*flags); 63intread_ref(const char*refname,unsigned char*sha1); 64 65intref_exists(const char*refname); 66 67intis_branch(const char*refname); 68 69/* 70 * If refname is a non-symbolic reference that refers to a tag object, 71 * and the tag can be (recursively) dereferenced to a non-tag object, 72 * store the SHA1 of the referred-to object to sha1 and return 0. If 73 * any of these conditions are not met, return a non-zero value. 74 * Symbolic references are considered unpeelable, even if they 75 * ultimately resolve to a peelable tag. 76 */ 77intpeel_ref(const char*refname,unsigned char*sha1); 78 79/** 80 * Resolve refname in the nested "gitlink" repository that is located 81 * at path. If the resolution is successful, return 0 and set sha1 to 82 * the name of the object; otherwise, return a non-zero value. 83 */ 84intresolve_gitlink_ref(const char*path,const char*refname, 85unsigned char*sha1); 86 87/* 88 * Return true iff abbrev_name is a possible abbreviation for 89 * full_name according to the rules defined by ref_rev_parse_rules in 90 * refs.c. 91 */ 92intrefname_match(const char*abbrev_name,const char*full_name); 93 94intdwim_ref(const char*str,int len,unsigned char*sha1,char**ref); 95intdwim_log(const char*str,int len,unsigned char*sha1,char**ref); 96 97/* 98 * A ref_transaction represents a collection of ref updates 99 * that should succeed or fail together. 100 * 101 * Calling sequence 102 * ---------------- 103 * - Allocate and initialize a `struct ref_transaction` by calling 104 * `ref_transaction_begin()`. 105 * 106 * - List intended ref updates by calling functions like 107 * `ref_transaction_update()` and `ref_transaction_create()`. 108 * 109 * - Call `ref_transaction_commit()` to execute the transaction. 110 * If this succeeds, the ref updates will have taken place and 111 * the transaction cannot be rolled back. 112 * 113 * - Instead of `ref_transaction_commit`, use 114 * `initial_ref_transaction_commit()` if the ref database is known 115 * to be empty (e.g. during clone). This is likely to be much 116 * faster. 117 * 118 * - At any time call `ref_transaction_free()` to discard the 119 * transaction and free associated resources. In particular, 120 * this rolls back the transaction if it has not been 121 * successfully committed. 122 * 123 * Error handling 124 * -------------- 125 * 126 * On error, transaction functions append a message about what 127 * went wrong to the 'err' argument. The message mentions what 128 * ref was being updated (if any) when the error occurred so it 129 * can be passed to 'die' or 'error' as-is. 130 * 131 * The message is appended to err without first clearing err. 132 * err will not be '\n' terminated. 133 * 134 * Caveats 135 * ------- 136 * 137 * Note that no locks are taken, and no refs are read, until 138 * `ref_transaction_commit` is called. So `ref_transaction_verify` 139 * won't report a verification failure until the commit is attempted. 140 */ 141struct ref_transaction; 142 143/* 144 * Bit values set in the flags argument passed to each_ref_fn() and 145 * stored in ref_iterator::flags. Other bits are for internal use 146 * only: 147 */ 148 149/* Reference is a symbolic reference. */ 150#define REF_ISSYMREF 0x01 151 152/* Reference is a packed reference. */ 153#define REF_ISPACKED 0x02 154 155/* 156 * Reference cannot be resolved to an object name: dangling symbolic 157 * reference (directly or indirectly), corrupt reference file, 158 * reference exists but name is bad, or symbolic reference refers to 159 * ill-formatted reference name. 160 */ 161#define REF_ISBROKEN 0x04 162 163/* 164 * Reference name is not well formed. 165 * 166 * See git-check-ref-format(1) for the definition of well formed ref names. 167 */ 168#define REF_BAD_NAME 0x08 169 170/* 171 * The signature for the callback function for the for_each_*() 172 * functions below. The memory pointed to by the refname and sha1 173 * arguments is only guaranteed to be valid for the duration of a 174 * single callback invocation. 175 */ 176typedefinteach_ref_fn(const char*refname, 177const struct object_id *oid,int flags,void*cb_data); 178 179/* 180 * The following functions invoke the specified callback function for 181 * each reference indicated. If the function ever returns a nonzero 182 * value, stop the iteration and return that value. Please note that 183 * it is not safe to modify references while an iteration is in 184 * progress, unless the same callback function invocation that 185 * modifies the reference also returns a nonzero value to immediately 186 * stop the iteration. 187 */ 188inthead_ref(each_ref_fn fn,void*cb_data); 189intfor_each_ref(each_ref_fn fn,void*cb_data); 190intfor_each_ref_in(const char*prefix, each_ref_fn fn,void*cb_data); 191intfor_each_fullref_in(const char*prefix, each_ref_fn fn,void*cb_data, 192unsigned int broken); 193intfor_each_tag_ref(each_ref_fn fn,void*cb_data); 194intfor_each_branch_ref(each_ref_fn fn,void*cb_data); 195intfor_each_remote_ref(each_ref_fn fn,void*cb_data); 196intfor_each_replace_ref(each_ref_fn fn,void*cb_data); 197intfor_each_glob_ref(each_ref_fn fn,const char*pattern,void*cb_data); 198intfor_each_glob_ref_in(each_ref_fn fn,const char*pattern, 199const char*prefix,void*cb_data); 200 201inthead_ref_submodule(const char*submodule, each_ref_fn fn,void*cb_data); 202intfor_each_ref_submodule(const char*submodule, 203 each_ref_fn fn,void*cb_data); 204intfor_each_ref_in_submodule(const char*submodule,const char*prefix, 205 each_ref_fn fn,void*cb_data); 206intfor_each_tag_ref_submodule(const char*submodule, 207 each_ref_fn fn,void*cb_data); 208intfor_each_branch_ref_submodule(const char*submodule, 209 each_ref_fn fn,void*cb_data); 210intfor_each_remote_ref_submodule(const char*submodule, 211 each_ref_fn fn,void*cb_data); 212 213inthead_ref_namespaced(each_ref_fn fn,void*cb_data); 214intfor_each_namespaced_ref(each_ref_fn fn,void*cb_data); 215 216/* can be used to learn about broken ref and symref */ 217intfor_each_rawref(each_ref_fn fn,void*cb_data); 218 219staticinlineconst char*has_glob_specials(const char*pattern) 220{ 221returnstrpbrk(pattern,"?*["); 222} 223 224voidwarn_dangling_symref(FILE*fp,const char*msg_fmt,const char*refname); 225voidwarn_dangling_symrefs(FILE*fp,const char*msg_fmt, 226const struct string_list *refnames); 227 228/* 229 * Flags for controlling behaviour of pack_refs() 230 * PACK_REFS_PRUNE: Prune loose refs after packing 231 * PACK_REFS_ALL: Pack _all_ refs, not just tags and already packed refs 232 */ 233#define PACK_REFS_PRUNE 0x0001 234#define PACK_REFS_ALL 0x0002 235 236/* 237 * Write a packed-refs file for the current repository. 238 * flags: Combination of the above PACK_REFS_* flags. 239 */ 240intpack_refs(unsigned int flags); 241 242/* 243 * Flags controlling ref_transaction_update(), ref_transaction_create(), etc. 244 * REF_NODEREF: act on the ref directly, instead of dereferencing 245 * symbolic references. 246 * 247 * Other flags are reserved for internal use. 248 */ 249#define REF_NODEREF 0x01 250#define REF_FORCE_CREATE_REFLOG 0x40 251 252/* 253 * Setup reflog before using. Fill in err and return -1 on failure. 254 */ 255intsafe_create_reflog(const char*refname,int force_create,struct strbuf *err); 256 257/** Reads log for the value of ref during at_time. **/ 258intread_ref_at(const char*refname,unsigned int flags, 259unsigned long at_time,int cnt, 260unsigned char*sha1,char**msg, 261unsigned long*cutoff_time,int*cutoff_tz,int*cutoff_cnt); 262 263/** Check if a particular reflog exists */ 264intreflog_exists(const char*refname); 265 266/* 267 * Delete the specified reference. If old_sha1 is non-NULL, then 268 * verify that the current value of the reference is old_sha1 before 269 * deleting it. If old_sha1 is NULL, delete the reference if it 270 * exists, regardless of its old value. It is an error for old_sha1 to 271 * be NULL_SHA1. flags is passed through to ref_transaction_delete(). 272 */ 273intdelete_ref(const char*refname,const unsigned char*old_sha1, 274unsigned int flags); 275 276/* 277 * Delete the specified references. If there are any problems, emit 278 * errors but attempt to keep going (i.e., the deletes are not done in 279 * an all-or-nothing transaction). flags is passed through to 280 * ref_transaction_delete(). 281 */ 282intdelete_refs(struct string_list *refnames,unsigned int flags); 283 284/** Delete a reflog */ 285intdelete_reflog(const char*refname); 286 287/* iterate over reflog entries */ 288typedefinteach_reflog_ent_fn( 289unsigned char*old_sha1,unsigned char*new_sha1, 290const char*committer,unsigned long timestamp, 291int tz,const char*msg,void*cb_data); 292 293intfor_each_reflog_ent(const char*refname, each_reflog_ent_fn fn,void*cb_data); 294intfor_each_reflog_ent_reverse(const char*refname, each_reflog_ent_fn fn,void*cb_data); 295 296/* 297 * Calls the specified function for each reflog file until it returns nonzero, 298 * and returns the value 299 */ 300intfor_each_reflog(each_ref_fn fn,void*cb_data); 301 302#define REFNAME_ALLOW_ONELEVEL 1 303#define REFNAME_REFSPEC_PATTERN 2 304 305/* 306 * Return 0 iff refname has the correct format for a refname according 307 * to the rules described in Documentation/git-check-ref-format.txt. 308 * If REFNAME_ALLOW_ONELEVEL is set in flags, then accept one-level 309 * reference names. If REFNAME_REFSPEC_PATTERN is set in flags, then 310 * allow a single "*" wildcard character in the refspec. No leading or 311 * repeated slashes are accepted. 312 */ 313intcheck_refname_format(const char*refname,int flags); 314 315const char*prettify_refname(const char*refname); 316 317char*shorten_unambiguous_ref(const char*refname,int strict); 318 319/** rename ref, return 0 on success **/ 320intrename_ref(const char*oldref,const char*newref,const char*logmsg); 321 322intcreate_symref(const char*refname,const char*target,const char*logmsg); 323 324/* 325 * Update HEAD of the specified gitdir. 326 * Similar to create_symref("relative-git-dir/HEAD", target, NULL), but 327 * this can update the main working tree's HEAD regardless of where 328 * $GIT_DIR points to. 329 * Return 0 if successful, non-zero otherwise. 330 * */ 331intset_worktree_head_symref(const char*gitdir,const char*target); 332 333enum action_on_err { 334 UPDATE_REFS_MSG_ON_ERR, 335 UPDATE_REFS_DIE_ON_ERR, 336 UPDATE_REFS_QUIET_ON_ERR 337}; 338 339/* 340 * Begin a reference transaction. The reference transaction must 341 * be freed by calling ref_transaction_free(). 342 */ 343struct ref_transaction *ref_transaction_begin(struct strbuf *err); 344 345/* 346 * Reference transaction updates 347 * 348 * The following four functions add a reference check or update to a 349 * ref_transaction. They have some common similar parameters: 350 * 351 * transaction -- a pointer to an open ref_transaction, obtained 352 * from ref_transaction_begin(). 353 * 354 * refname -- the name of the reference to be affected. 355 * 356 * flags -- flags affecting the update, passed to 357 * update_ref_lock(). Can be REF_NODEREF, which means that 358 * symbolic references should not be followed. 359 * 360 * msg -- a message describing the change (for the reflog). 361 * 362 * err -- a strbuf for receiving a description of any error that 363 * might have occured. 364 * 365 * The functions make internal copies of refname and msg, so the 366 * caller retains ownership of these parameters. 367 * 368 * The functions return 0 on success and non-zero on failure. A 369 * failure means that the transaction as a whole has failed and needs 370 * to be rolled back. 371 */ 372 373/* 374 * Add a reference update to transaction. new_sha1 is the value that 375 * the reference should have after the update, or null_sha1 if it 376 * should be deleted. If new_sha1 is NULL, then the reference is not 377 * changed at all. old_sha1 is the value that the reference must have 378 * before the update, or null_sha1 if it must not have existed 379 * beforehand. The old value is checked after the lock is taken to 380 * prevent races. If the old value doesn't agree with old_sha1, the 381 * whole transaction fails. If old_sha1 is NULL, then the previous 382 * value is not checked. 383 * 384 * See the above comment "Reference transaction updates" for more 385 * information. 386 */ 387intref_transaction_update(struct ref_transaction *transaction, 388const char*refname, 389const unsigned char*new_sha1, 390const unsigned char*old_sha1, 391unsigned int flags,const char*msg, 392struct strbuf *err); 393 394/* 395 * Add a reference creation to transaction. new_sha1 is the value that 396 * the reference should have after the update; it must not be 397 * null_sha1. It is verified that the reference does not exist 398 * already. 399 * 400 * See the above comment "Reference transaction updates" for more 401 * information. 402 */ 403intref_transaction_create(struct ref_transaction *transaction, 404const char*refname, 405const unsigned char*new_sha1, 406unsigned int flags,const char*msg, 407struct strbuf *err); 408 409/* 410 * Add a reference deletion to transaction. If old_sha1 is non-NULL, 411 * then it holds the value that the reference should have had before 412 * the update (which must not be null_sha1). 413 * 414 * See the above comment "Reference transaction updates" for more 415 * information. 416 */ 417intref_transaction_delete(struct ref_transaction *transaction, 418const char*refname, 419const unsigned char*old_sha1, 420unsigned int flags,const char*msg, 421struct strbuf *err); 422 423/* 424 * Verify, within a transaction, that refname has the value old_sha1, 425 * or, if old_sha1 is null_sha1, then verify that the reference 426 * doesn't exist. old_sha1 must be non-NULL. 427 * 428 * See the above comment "Reference transaction updates" for more 429 * information. 430 */ 431intref_transaction_verify(struct ref_transaction *transaction, 432const char*refname, 433const unsigned char*old_sha1, 434unsigned int flags, 435struct strbuf *err); 436 437/* 438 * Commit all of the changes that have been queued in transaction, as 439 * atomically as possible. 440 * 441 * Returns 0 for success, or one of the below error codes for errors. 442 */ 443/* Naming conflict (for example, the ref names A and A/B conflict). */ 444#define TRANSACTION_NAME_CONFLICT -1 445/* All other errors. */ 446#define TRANSACTION_GENERIC_ERROR -2 447intref_transaction_commit(struct ref_transaction *transaction, 448struct strbuf *err); 449 450/* 451 * Like ref_transaction_commit(), but optimized for creating 452 * references when originally initializing a repository (e.g., by "git 453 * clone"). It writes the new references directly to packed-refs 454 * without locking the individual references. 455 * 456 * It is a bug to call this function when there might be other 457 * processes accessing the repository or if there are existing 458 * references that might conflict with the ones being created. All 459 * old_sha1 values must either be absent or NULL_SHA1. 460 */ 461intinitial_ref_transaction_commit(struct ref_transaction *transaction, 462struct strbuf *err); 463 464/* 465 * Free an existing transaction and all associated data. 466 */ 467voidref_transaction_free(struct ref_transaction *transaction); 468 469/** 470 * Lock, update, and unlock a single reference. This function 471 * basically does a transaction containing a single call to 472 * ref_transaction_update(). The parameters to this function have the 473 * same meaning as the corresponding parameters to 474 * ref_transaction_update(). Handle errors as requested by the `onerr` 475 * argument. 476 */ 477intupdate_ref(const char*msg,const char*refname, 478const unsigned char*new_sha1,const unsigned char*old_sha1, 479unsigned int flags,enum action_on_err onerr); 480 481intparse_hide_refs_config(const char*var,const char*value,const char*); 482 483/* 484 * Check whether a ref is hidden. If no namespace is set, both the first and 485 * the second parameter point to the full ref name. If a namespace is set and 486 * the ref is inside that namespace, the first parameter is a pointer to the 487 * name of the ref with the namespace prefix removed. If a namespace is set and 488 * the ref is outside that namespace, the first parameter is NULL. The second 489 * parameter always points to the full ref name. 490 */ 491intref_is_hidden(const char*,const char*); 492 493enum ref_type { 494 REF_TYPE_PER_WORKTREE, 495 REF_TYPE_PSEUDOREF, 496 REF_TYPE_NORMAL, 497}; 498 499enum ref_type ref_type(const char*refname); 500 501enum expire_reflog_flags { 502 EXPIRE_REFLOGS_DRY_RUN =1<<0, 503 EXPIRE_REFLOGS_UPDATE_REF =1<<1, 504 EXPIRE_REFLOGS_VERBOSE =1<<2, 505 EXPIRE_REFLOGS_REWRITE =1<<3 506}; 507 508/* 509 * The following interface is used for reflog expiration. The caller 510 * calls reflog_expire(), supplying it with three callback functions, 511 * of the following types. The callback functions define the 512 * expiration policy that is desired. 513 * 514 * reflog_expiry_prepare_fn -- Called once after the reference is 515 * locked. 516 * 517 * reflog_expiry_should_prune_fn -- Called once for each entry in the 518 * existing reflog. It should return true iff that entry should be 519 * pruned. 520 * 521 * reflog_expiry_cleanup_fn -- Called once before the reference is 522 * unlocked again. 523 */ 524typedefvoidreflog_expiry_prepare_fn(const char*refname, 525const unsigned char*sha1, 526void*cb_data); 527typedefintreflog_expiry_should_prune_fn(unsigned char*osha1, 528unsigned char*nsha1, 529const char*email, 530unsigned long timestamp,int tz, 531const char*message,void*cb_data); 532typedefvoidreflog_expiry_cleanup_fn(void*cb_data); 533 534/* 535 * Expire reflog entries for the specified reference. sha1 is the old 536 * value of the reference. flags is a combination of the constants in 537 * enum expire_reflog_flags. The three function pointers are described 538 * above. On success, return zero. 539 */ 540intreflog_expire(const char*refname,const unsigned char*sha1, 541unsigned int flags, 542 reflog_expiry_prepare_fn prepare_fn, 543 reflog_expiry_should_prune_fn should_prune_fn, 544 reflog_expiry_cleanup_fn cleanup_fn, 545void*policy_cb_data); 546 547intref_storage_backend_exists(const char*name); 548 549#endif/* REFS_H */