refs.h

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