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(): 145 */ 146 147/* Reference is a symbolic reference. */ 148#define REF_ISSYMREF 0x01 149 150/* Reference is a packed reference. */ 151#define REF_ISPACKED 0x02 152 153/* 154 * Reference cannot be resolved to an object name: dangling symbolic 155 * reference (directly or indirectly), corrupt reference file, 156 * reference exists but name is bad, or symbolic reference refers to 157 * ill-formatted reference name. 158 */ 159#define REF_ISBROKEN 0x04 160 161/* 162 * Reference name is not well formed. 163 * 164 * See git-check-ref-format(1) for the definition of well formed ref names. 165 */ 166#define REF_BAD_NAME 0x08 167 168/* 169 * The signature for the callback function for the for_each_*() 170 * functions below. The memory pointed to by the refname and sha1 171 * arguments is only guaranteed to be valid for the duration of a 172 * single callback invocation. 173 */ 174typedefinteach_ref_fn(const char*refname, 175const struct object_id *oid,int flags,void*cb_data); 176 177/* 178 * The following functions invoke the specified callback function for 179 * each reference indicated. If the function ever returns a nonzero 180 * value, stop the iteration and return that value. Please note that 181 * it is not safe to modify references while an iteration is in 182 * progress, unless the same callback function invocation that 183 * modifies the reference also returns a nonzero value to immediately 184 * stop the iteration. 185 */ 186inthead_ref(each_ref_fn fn,void*cb_data); 187intfor_each_ref(each_ref_fn fn,void*cb_data); 188intfor_each_ref_in(const char*prefix, each_ref_fn fn,void*cb_data); 189intfor_each_fullref_in(const char*prefix, each_ref_fn fn,void*cb_data, 190unsigned int broken); 191intfor_each_tag_ref(each_ref_fn fn,void*cb_data); 192intfor_each_branch_ref(each_ref_fn fn,void*cb_data); 193intfor_each_remote_ref(each_ref_fn fn,void*cb_data); 194intfor_each_replace_ref(each_ref_fn fn,void*cb_data); 195intfor_each_glob_ref(each_ref_fn fn,const char*pattern,void*cb_data); 196intfor_each_glob_ref_in(each_ref_fn fn,const char*pattern, 197const char*prefix,void*cb_data); 198 199inthead_ref_submodule(const char*submodule, each_ref_fn fn,void*cb_data); 200intfor_each_ref_submodule(const char*submodule, 201 each_ref_fn fn,void*cb_data); 202intfor_each_ref_in_submodule(const char*submodule,const char*prefix, 203 each_ref_fn fn,void*cb_data); 204intfor_each_tag_ref_submodule(const char*submodule, 205 each_ref_fn fn,void*cb_data); 206intfor_each_branch_ref_submodule(const char*submodule, 207 each_ref_fn fn,void*cb_data); 208intfor_each_remote_ref_submodule(const char*submodule, 209 each_ref_fn fn,void*cb_data); 210 211inthead_ref_namespaced(each_ref_fn fn,void*cb_data); 212intfor_each_namespaced_ref(each_ref_fn fn,void*cb_data); 213 214/* can be used to learn about broken ref and symref */ 215intfor_each_rawref(each_ref_fn fn,void*cb_data); 216 217staticinlineconst char*has_glob_specials(const char*pattern) 218{ 219returnstrpbrk(pattern,"?*["); 220} 221 222voidwarn_dangling_symref(FILE*fp,const char*msg_fmt,const char*refname); 223voidwarn_dangling_symrefs(FILE*fp,const char*msg_fmt, 224const struct string_list *refnames); 225 226/* 227 * Flags for controlling behaviour of pack_refs() 228 * PACK_REFS_PRUNE: Prune loose refs after packing 229 * PACK_REFS_ALL: Pack _all_ refs, not just tags and already packed refs 230 */ 231#define PACK_REFS_PRUNE 0x0001 232#define PACK_REFS_ALL 0x0002 233 234/* 235 * Write a packed-refs file for the current repository. 236 * flags: Combination of the above PACK_REFS_* flags. 237 */ 238intpack_refs(unsigned int flags); 239 240/* 241 * Flags controlling ref_transaction_update(), ref_transaction_create(), etc. 242 * REF_NODEREF: act on the ref directly, instead of dereferencing 243 * symbolic references. 244 * 245 * Other flags are reserved for internal use. 246 */ 247#define REF_NODEREF 0x01 248#define REF_FORCE_CREATE_REFLOG 0x40 249 250/* 251 * Setup reflog before using. Fill in err and return -1 on failure. 252 */ 253intsafe_create_reflog(const char*refname,int force_create,struct strbuf *err); 254 255/** Reads log for the value of ref during at_time. **/ 256intread_ref_at(const char*refname,unsigned int flags, 257unsigned long at_time,int cnt, 258unsigned char*sha1,char**msg, 259unsigned long*cutoff_time,int*cutoff_tz,int*cutoff_cnt); 260 261/** Check if a particular reflog exists */ 262intreflog_exists(const char*refname); 263 264/* 265 * Delete the specified reference. If old_sha1 is non-NULL, then 266 * verify that the current value of the reference is old_sha1 before 267 * deleting it. If old_sha1 is NULL, delete the reference if it 268 * exists, regardless of its old value. It is an error for old_sha1 to 269 * be NULL_SHA1. flags is passed through to ref_transaction_delete(). 270 */ 271intdelete_ref(const char*refname,const unsigned char*old_sha1, 272unsigned int flags); 273 274/* 275 * Delete the specified references. If there are any problems, emit 276 * errors but attempt to keep going (i.e., the deletes are not done in 277 * an all-or-nothing transaction). flags is passed through to 278 * ref_transaction_delete(). 279 */ 280intdelete_refs(struct string_list *refnames,unsigned int flags); 281 282/** Delete a reflog */ 283intdelete_reflog(const char*refname); 284 285/* iterate over reflog entries */ 286typedefinteach_reflog_ent_fn( 287unsigned char*old_sha1,unsigned char*new_sha1, 288const char*committer,unsigned long timestamp, 289int tz,const char*msg,void*cb_data); 290 291intfor_each_reflog_ent(const char*refname, each_reflog_ent_fn fn,void*cb_data); 292intfor_each_reflog_ent_reverse(const char*refname, each_reflog_ent_fn fn,void*cb_data); 293 294/* 295 * Calls the specified function for each reflog file until it returns nonzero, 296 * and returns the value 297 */ 298intfor_each_reflog(each_ref_fn fn,void*cb_data); 299 300#define REFNAME_ALLOW_ONELEVEL 1 301#define REFNAME_REFSPEC_PATTERN 2 302 303/* 304 * Return 0 iff refname has the correct format for a refname according 305 * to the rules described in Documentation/git-check-ref-format.txt. 306 * If REFNAME_ALLOW_ONELEVEL is set in flags, then accept one-level 307 * reference names. If REFNAME_REFSPEC_PATTERN is set in flags, then 308 * allow a single "*" wildcard character in the refspec. No leading or 309 * repeated slashes are accepted. 310 */ 311intcheck_refname_format(const char*refname,int flags); 312 313const char*prettify_refname(const char*refname); 314 315char*shorten_unambiguous_ref(const char*refname,int strict); 316 317/** rename ref, return 0 on success **/ 318intrename_ref(const char*oldref,const char*newref,const char*logmsg); 319 320intcreate_symref(const char*refname,const char*target,const char*logmsg); 321 322/* 323 * Update HEAD of the specified gitdir. 324 * Similar to create_symref("relative-git-dir/HEAD", target, NULL), but 325 * this can update the main working tree's HEAD regardless of where 326 * $GIT_DIR points to. 327 * Return 0 if successful, non-zero otherwise. 328 * */ 329intset_worktree_head_symref(const char*gitdir,const char*target); 330 331enum action_on_err { 332 UPDATE_REFS_MSG_ON_ERR, 333 UPDATE_REFS_DIE_ON_ERR, 334 UPDATE_REFS_QUIET_ON_ERR 335}; 336 337/* 338 * Begin a reference transaction. The reference transaction must 339 * be freed by calling ref_transaction_free(). 340 */ 341struct ref_transaction *ref_transaction_begin(struct strbuf *err); 342 343/* 344 * Reference transaction updates 345 * 346 * The following four functions add a reference check or update to a 347 * ref_transaction. They have some common similar parameters: 348 * 349 * transaction -- a pointer to an open ref_transaction, obtained 350 * from ref_transaction_begin(). 351 * 352 * refname -- the name of the reference to be affected. 353 * 354 * flags -- flags affecting the update, passed to 355 * update_ref_lock(). Can be REF_NODEREF, which means that 356 * symbolic references should not be followed. 357 * 358 * msg -- a message describing the change (for the reflog). 359 * 360 * err -- a strbuf for receiving a description of any error that 361 * might have occured. 362 * 363 * The functions make internal copies of refname and msg, so the 364 * caller retains ownership of these parameters. 365 * 366 * The functions return 0 on success and non-zero on failure. A 367 * failure means that the transaction as a whole has failed and needs 368 * to be rolled back. 369 */ 370 371/* 372 * Add a reference update to transaction. new_sha1 is the value that 373 * the reference should have after the update, or null_sha1 if it 374 * should be deleted. If new_sha1 is NULL, then the reference is not 375 * changed at all. old_sha1 is the value that the reference must have 376 * before the update, or null_sha1 if it must not have existed 377 * beforehand. The old value is checked after the lock is taken to 378 * prevent races. If the old value doesn't agree with old_sha1, the 379 * whole transaction fails. If old_sha1 is NULL, then the previous 380 * value is not checked. 381 * 382 * See the above comment "Reference transaction updates" for more 383 * information. 384 */ 385intref_transaction_update(struct ref_transaction *transaction, 386const char*refname, 387const unsigned char*new_sha1, 388const unsigned char*old_sha1, 389unsigned int flags,const char*msg, 390struct strbuf *err); 391 392/* 393 * Add a reference creation to transaction. new_sha1 is the value that 394 * the reference should have after the update; it must not be 395 * null_sha1. It is verified that the reference does not exist 396 * already. 397 * 398 * See the above comment "Reference transaction updates" for more 399 * information. 400 */ 401intref_transaction_create(struct ref_transaction *transaction, 402const char*refname, 403const unsigned char*new_sha1, 404unsigned int flags,const char*msg, 405struct strbuf *err); 406 407/* 408 * Add a reference deletion to transaction. If old_sha1 is non-NULL, 409 * then it holds the value that the reference should have had before 410 * the update (which must not be null_sha1). 411 * 412 * See the above comment "Reference transaction updates" for more 413 * information. 414 */ 415intref_transaction_delete(struct ref_transaction *transaction, 416const char*refname, 417const unsigned char*old_sha1, 418unsigned int flags,const char*msg, 419struct strbuf *err); 420 421/* 422 * Verify, within a transaction, that refname has the value old_sha1, 423 * or, if old_sha1 is null_sha1, then verify that the reference 424 * doesn't exist. old_sha1 must be non-NULL. 425 * 426 * See the above comment "Reference transaction updates" for more 427 * information. 428 */ 429intref_transaction_verify(struct ref_transaction *transaction, 430const char*refname, 431const unsigned char*old_sha1, 432unsigned int flags, 433struct strbuf *err); 434 435/* 436 * Commit all of the changes that have been queued in transaction, as 437 * atomically as possible. 438 * 439 * Returns 0 for success, or one of the below error codes for errors. 440 */ 441/* Naming conflict (for example, the ref names A and A/B conflict). */ 442#define TRANSACTION_NAME_CONFLICT -1 443/* All other errors. */ 444#define TRANSACTION_GENERIC_ERROR -2 445intref_transaction_commit(struct ref_transaction *transaction, 446struct strbuf *err); 447 448/* 449 * Like ref_transaction_commit(), but optimized for creating 450 * references when originally initializing a repository (e.g., by "git 451 * clone"). It writes the new references directly to packed-refs 452 * without locking the individual references. 453 * 454 * It is a bug to call this function when there might be other 455 * processes accessing the repository or if there are existing 456 * references that might conflict with the ones being created. All 457 * old_sha1 values must either be absent or NULL_SHA1. 458 */ 459intinitial_ref_transaction_commit(struct ref_transaction *transaction, 460struct strbuf *err); 461 462/* 463 * Free an existing transaction and all associated data. 464 */ 465voidref_transaction_free(struct ref_transaction *transaction); 466 467/** 468 * Lock, update, and unlock a single reference. This function 469 * basically does a transaction containing a single call to 470 * ref_transaction_update(). The parameters to this function have the 471 * same meaning as the corresponding parameters to 472 * ref_transaction_update(). Handle errors as requested by the `onerr` 473 * argument. 474 */ 475intupdate_ref(const char*msg,const char*refname, 476const unsigned char*new_sha1,const unsigned char*old_sha1, 477unsigned int flags,enum action_on_err onerr); 478 479intparse_hide_refs_config(const char*var,const char*value,const char*); 480 481/* 482 * Check whether a ref is hidden. If no namespace is set, both the first and 483 * the second parameter point to the full ref name. If a namespace is set and 484 * the ref is inside that namespace, the first parameter is a pointer to the 485 * name of the ref with the namespace prefix removed. If a namespace is set and 486 * the ref is outside that namespace, the first parameter is NULL. The second 487 * parameter always points to the full ref name. 488 */ 489intref_is_hidden(const char*,const char*); 490 491enum ref_type { 492 REF_TYPE_PER_WORKTREE, 493 REF_TYPE_PSEUDOREF, 494 REF_TYPE_NORMAL, 495}; 496 497enum ref_type ref_type(const char*refname); 498 499enum expire_reflog_flags { 500 EXPIRE_REFLOGS_DRY_RUN =1<<0, 501 EXPIRE_REFLOGS_UPDATE_REF =1<<1, 502 EXPIRE_REFLOGS_VERBOSE =1<<2, 503 EXPIRE_REFLOGS_REWRITE =1<<3 504}; 505 506/* 507 * The following interface is used for reflog expiration. The caller 508 * calls reflog_expire(), supplying it with three callback functions, 509 * of the following types. The callback functions define the 510 * expiration policy that is desired. 511 * 512 * reflog_expiry_prepare_fn -- Called once after the reference is 513 * locked. 514 * 515 * reflog_expiry_should_prune_fn -- Called once for each entry in the 516 * existing reflog. It should return true iff that entry should be 517 * pruned. 518 * 519 * reflog_expiry_cleanup_fn -- Called once before the reference is 520 * unlocked again. 521 */ 522typedefvoidreflog_expiry_prepare_fn(const char*refname, 523const unsigned char*sha1, 524void*cb_data); 525typedefintreflog_expiry_should_prune_fn(unsigned char*osha1, 526unsigned char*nsha1, 527const char*email, 528unsigned long timestamp,int tz, 529const char*message,void*cb_data); 530typedefvoidreflog_expiry_cleanup_fn(void*cb_data); 531 532/* 533 * Expire reflog entries for the specified reference. sha1 is the old 534 * value of the reference. flags is a combination of the constants in 535 * enum expire_reflog_flags. The three function pointers are described 536 * above. On success, return zero. 537 */ 538intreflog_expire(const char*refname,const unsigned char*sha1, 539unsigned int flags, 540 reflog_expiry_prepare_fn prepare_fn, 541 reflog_expiry_should_prune_fn should_prune_fn, 542 reflog_expiry_cleanup_fn cleanup_fn, 543void*policy_cb_data); 544 545#endif/* REFS_H */