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