refs.h 29 KB
Newer Older
Daniel Barkalow's avatar
Daniel Barkalow committed
1 2 3
#ifndef REFS_H
#define REFS_H

4
struct object_id;
5
struct ref_store;
6 7
struct strbuf;
struct string_list;
8
struct worktree;
9

10 11 12
/*
 * Resolve a reference, recursively following symbolic refererences.
 *
13 14 15 16
 * Return the name of the non-symbolic reference that ultimately pointed
 * at the resolved object name.  The return value, if not NULL, is a
 * pointer into either a static buffer or the input ref.
 *
17
 * If oid is non-NULL, store the referred-to object's name in it.
18 19 20 21 22 23
 *
 * If the reference cannot be resolved to an object, the behavior
 * depends on the RESOLVE_REF_READING flag:
 *
 * - If RESOLVE_REF_READING is set, return NULL.
 *
24
 * - If RESOLVE_REF_READING is not set, clear oid and return the name of
25 26 27 28 29 30
 *   the last reference name in the chain, which will either be a non-symbolic
 *   reference or an undefined reference.  If this is a prelude to
 *   "writing" to the ref, the return value is the name of the ref
 *   that will actually be created or changed.
 *
 * If the RESOLVE_REF_NO_RECURSE flag is passed, only resolves one
31 32
 * level of symbolic reference.  The value stored in oid for a symbolic
 * reference will always be null_oid in this case, and the return
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
 * value is the reference that the symref refers to directly.
 *
 * If flags is non-NULL, set the value that it points to the
 * combination of REF_ISPACKED (if the reference was found among the
 * packed references), REF_ISSYMREF (if the initial reference was a
 * symbolic reference), REF_BAD_NAME (if the reference name is ill
 * formed --- see RESOLVE_REF_ALLOW_BAD_NAME below), and REF_ISBROKEN
 * (if the ref is malformed or has a bad name). See refs.h for more detail
 * on each flag.
 *
 * If ref is not a properly-formatted, normalized reference, return
 * NULL.  If more than MAXDEPTH recursive symbolic lookups are needed,
 * give up and return NULL.
 *
 * RESOLVE_REF_ALLOW_BAD_NAME allows resolving refs even when their
 * 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 51 52 53 54 55 56 57 58 59 60 61
 * flags REF_ISBROKEN and REF_BAD_NAME will be set.
 *
 * Even with RESOLVE_REF_ALLOW_BAD_NAME, names that escape the refs/
 * directory and do not consist of all caps and underscores cannot be
 * resolved. The function returns NULL for such ref names.
 * Caps and underscores refers to the special refs, such as HEAD,
 * FETCH_HEAD and friends, that all live outside of the refs/ directory.
 */
#define RESOLVE_REF_READING 0x01
#define RESOLVE_REF_NO_RECURSE 0x02
#define RESOLVE_REF_ALLOW_BAD_NAME 0x04

Duy Nguyen's avatar
Duy Nguyen committed
62 63 64
const char *refs_resolve_ref_unsafe(struct ref_store *refs,
				    const char *refname,
				    int resolve_flags,
65
				    struct object_id *oid,
Duy Nguyen's avatar
Duy Nguyen committed
66
				    int *flags);
67
const char *resolve_ref_unsafe(const char *refname, int resolve_flags,
68
			       struct object_id *oid, int *flags);
69

Duy Nguyen's avatar
Duy Nguyen committed
70 71
char *refs_resolve_refdup(struct ref_store *refs,
			  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

Duy Nguyen's avatar
Duy Nguyen committed
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 80
		  struct object_id *oid, int *flags);
int read_ref(const char *refname, struct object_id *oid);
81

Duy Nguyen's avatar
Duy Nguyen committed
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101
/*
 * Return 0 if a reference named refname could be created without
 * conflicting with the name of an existing reference. Otherwise,
 * return a negative value and write an explanation to err. If extras
 * is non-NULL, it is a list of additional refnames with which refname
 * is not allowed to conflict. If skip is non-NULL, ignore potential
 * conflicts with refs in skip (e.g., because they are scheduled for
 * deletion in the same operation). Behavior is undefined if the same
 * name is listed in both extras and skip.
 *
 * Two reference names conflict if one of them exactly matches the
 * leading components of the other; e.g., "foo/bar" conflicts with
 * both "foo" and with "foo/bar/baz" but not with "foo/bar" or
 * "foo/barbados".
 *
 * extras and skip must be sorted.
 */

int refs_verify_refname_available(struct ref_store *refs,
				  const char *refname,
102
				  const struct string_list *extras,
Duy Nguyen's avatar
Duy Nguyen committed
103 104 105
				  const struct string_list *skip,
				  struct strbuf *err);

106
int ref_exists(const char *refname);
107

108 109
int should_autocreate_reflog(const char *refname);

110
int is_branch(const char *refname);
111

112 113
extern int refs_init_db(struct strbuf *err);

114 115 116
/*
 * If refname is a non-symbolic reference that refers to a tag object,
 * and the tag can be (recursively) dereferenced to a non-tag object,
117 118
 * store the object ID of the referred-to object to oid and return 0.
 * If any of these conditions are not met, return a non-zero value.
119 120 121
 * Symbolic references are considered unpeelable, even if they
 * ultimately resolve to a peelable tag.
 */
Duy Nguyen's avatar
Duy Nguyen committed
122
int refs_peel_ref(struct ref_store *refs, const char *refname,
123 124
		  struct object_id *oid);
int peel_ref(const char *refname, struct object_id *oid);
125 126

/**
127 128
 * Resolve refname in the nested "gitlink" repository in the specified
 * 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 137 138 139

/*
 * Return true iff abbrev_name is a possible abbreviation for
 * full_name according to the rules defined by ref_rev_parse_rules in
 * refs.c.
 */
140
int refname_match(const char *abbrev_name, const char *full_name);
141

142 143
int expand_ref(const char *str, int len, struct object_id *oid, char **ref);
int dwim_ref(const char *str, int len, struct object_id *oid, char **ref);
144
int dwim_log(const char *str, int len, struct object_id *oid, char **ref);
145

146
/*
147 148
 * A ref_transaction represents a collection of reference updates that
 * should succeed or fail together.
149 150 151
 *
 * Calling sequence
 * ----------------
152
 *
153 154 155
 * - Allocate and initialize a `struct ref_transaction` by calling
 *   `ref_transaction_begin()`.
 *
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211
 * - Specify the intended ref updates by calling one or more of the
 *   following functions:
 *   - `ref_transaction_update()`
 *   - `ref_transaction_create()`
 *   - `ref_transaction_delete()`
 *   - `ref_transaction_verify()`
 *
 * - Then either:
 *
 *   - Optionally call `ref_transaction_prepare()` to prepare the
 *     transaction. This locks all references, checks preconditions,
 *     etc. but doesn't finalize anything. If this step fails, the
 *     transaction has been closed and can only be freed. If this step
 *     succeeds, then `ref_transaction_commit()` is almost certain to
 *     succeed. However, you can still call `ref_transaction_abort()`
 *     if you decide not to commit the transaction after all.
 *
 *   - Call `ref_transaction_commit()` to execute the transaction,
 *     make the changes permanent, and release all locks. If you
 *     haven't already called `ref_transaction_prepare()`, then
 *     `ref_transaction_commit()` calls it for you.
 *
 *   Or
 *
 *   - Call `initial_ref_transaction_commit()` if the ref database is
 *     known to be empty and have no other writers (e.g. during
 *     clone). This is likely to be much faster than
 *     `ref_transaction_commit()`. `ref_transaction_prepare()` should
 *     *not* be called before `initial_ref_transaction_commit()`.
 *
 * - Then finally, call `ref_transaction_free()` to free the
 *   `ref_transaction` data structure.
 *
 * At any time before calling `ref_transaction_commit()`, you can call
 * `ref_transaction_abort()` to abort the transaction, rollback any
 * locks, and free any associated resources (including the
 * `ref_transaction` data structure).
 *
 * Putting it all together, a complete reference update looks like
 *
 *         struct ref_transaction *transaction;
 *         struct strbuf err = STRBUF_INIT;
 *         int ret = 0;
 *
 *         transaction = ref_store_transaction_begin(refs, &err);
 *         if (!transaction ||
 *             ref_transaction_update(...) ||
 *             ref_transaction_create(...) ||
 *             ...etc... ||
 *             ref_transaction_commit(transaction, &err)) {
 *                 error("%s", err.buf);
 *                 ret = -1;
 *         }
 *         ref_transaction_free(transaction);
 *         strbuf_release(&err);
 *         return ret;
212 213 214 215 216 217 218 219 220 221 222
 *
 * Error handling
 * --------------
 *
 * On error, transaction functions append a message about what
 * went wrong to the 'err' argument.  The message mentions what
 * ref was being updated (if any) when the error occurred so it
 * can be passed to 'die' or 'error' as-is.
 *
 * The message is appended to err without first clearing err.
 * err will not be '\n' terminated.
223 224 225 226 227
 *
 * Caveats
 * -------
 *
 * Note that no locks are taken, and no refs are read, until
228 229 230
 * `ref_transaction_prepare()` or `ref_transaction_commit()` is
 * called. So, for example, `ref_transaction_verify()` won't report a
 * verification failure until the commit is attempted.
231
 */
232 233
struct ref_transaction;

234
/*
235 236 237
 * Bit values set in the flags argument passed to each_ref_fn() and
 * stored in ref_iterator::flags. Other bits are for internal use
 * only:
238 239 240
 */

/* Reference is a symbolic reference. */
241
#define REF_ISSYMREF 0x01
242 243

/* Reference is a packed reference. */
244
#define REF_ISPACKED 0x02
245 246 247

/*
 * Reference cannot be resolved to an object name: dangling symbolic
248 249 250
 * reference (directly or indirectly), corrupt reference file,
 * reference exists but name is bad, or symbolic reference refers to
 * ill-formatted reference name.
251
 */
252
#define REF_ISBROKEN 0x04
253

254 255 256 257 258 259 260
/*
 * Reference name is not well formed.
 *
 * See git-check-ref-format(1) for the definition of well formed ref names.
 */
#define REF_BAD_NAME 0x08

261
/*
262
 * The signature for the callback function for the for_each_*()
263
 * functions below.  The memory pointed to by the refname and oid
264 265 266 267
 * arguments is only guaranteed to be valid for the duration of a
 * single callback invocation.
 */
typedef int each_ref_fn(const char *refname,
268 269
			const struct object_id *oid, int flags, void *cb_data);

270 271 272 273 274 275 276
/*
 * The following functions invoke the specified callback function for
 * each reference indicated.  If the function ever returns a nonzero
 * value, stop the iteration and return that value.  Please note that
 * it is not safe to modify references while an iteration is in
 * progress, unless the same callback function invocation that
 * modifies the reference also returns a nonzero value to immediately
277
 * stop the iteration. Returned references are sorted.
278
 */
Duy Nguyen's avatar
Duy Nguyen committed
279 280
int refs_head_ref(struct ref_store *refs,
		  each_ref_fn fn, void *cb_data);
Duy Nguyen's avatar
Duy Nguyen committed
281 282 283 284 285 286 287 288 289 290 291
int refs_for_each_ref(struct ref_store *refs,
		      each_ref_fn fn, void *cb_data);
int refs_for_each_ref_in(struct ref_store *refs, const char *prefix,
			 each_ref_fn fn, void *cb_data);
int refs_for_each_tag_ref(struct ref_store *refs,
			  each_ref_fn fn, void *cb_data);
int refs_for_each_branch_ref(struct ref_store *refs,
			     each_ref_fn fn, void *cb_data);
int refs_for_each_remote_ref(struct ref_store *refs,
			     each_ref_fn fn, void *cb_data);

292 293 294
int head_ref(each_ref_fn fn, void *cb_data);
int for_each_ref(each_ref_fn fn, void *cb_data);
int for_each_ref_in(const char *prefix, each_ref_fn fn, void *cb_data);
295 296 297
int refs_for_each_fullref_in(struct ref_store *refs, const char *prefix,
			     each_ref_fn fn, void *cb_data,
			     unsigned int broken);
298 299 300 301 302
int for_each_fullref_in(const char *prefix, each_ref_fn fn, void *cb_data,
			unsigned int broken);
int for_each_tag_ref(each_ref_fn fn, void *cb_data);
int for_each_branch_ref(each_ref_fn fn, void *cb_data);
int for_each_remote_ref(each_ref_fn fn, void *cb_data);
303
int for_each_replace_ref(struct repository *r, each_ref_fn fn, void *cb_data);
304 305 306 307 308 309
int for_each_glob_ref(each_ref_fn fn, const char *pattern, void *cb_data);
int for_each_glob_ref_in(each_ref_fn fn, const char *pattern,
			 const char *prefix, void *cb_data);

int head_ref_namespaced(each_ref_fn fn, void *cb_data);
int for_each_namespaced_ref(each_ref_fn fn, void *cb_data);
310

311
/* can be used to learn about broken ref and symref */
Duy Nguyen's avatar
Duy Nguyen committed
312
int refs_for_each_rawref(struct ref_store *refs, each_ref_fn fn, void *cb_data);
313
int for_each_rawref(each_ref_fn fn, void *cb_data);
314

315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338
/*
 * Normalizes partial refs to their fully qualified form.
 * Will prepend <prefix> to the <pattern> if it doesn't start with 'refs/'.
 * <prefix> will default to 'refs/' if NULL.
 *
 * item.string will be set to the result.
 * item.util will be set to NULL if <pattern> contains glob characters, or
 * non-NULL if it doesn't.
 */
void normalize_glob_ref(struct string_list_item *item, const char *prefix,
			const char *pattern);

/*
 * Returns 0 if refname matches any of the exclude_patterns, or if it doesn't
 * match any of the include_patterns. Returns 1 otherwise.
 *
 * If pattern list is NULL or empty, matching against that list is skipped.
 * This has the effect of matching everything by default, unless the user
 * specifies rules otherwise.
 */
int ref_filter_match(const char *refname,
		     const struct string_list *include_patterns,
		     const struct string_list *exclude_patterns);

339 340 341 342 343
static inline const char *has_glob_specials(const char *pattern)
{
	return strpbrk(pattern, "?*[");
}

344 345 346
void warn_dangling_symref(FILE *fp, const char *msg_fmt, const char *refname);
void warn_dangling_symrefs(FILE *fp, const char *msg_fmt,
			   const struct string_list *refnames);
347

348 349 350 351 352 353 354 355 356 357 358 359
/*
 * Flags for controlling behaviour of pack_refs()
 * PACK_REFS_PRUNE: Prune loose refs after packing
 * PACK_REFS_ALL:   Pack _all_ refs, not just tags and already packed refs
 */
#define PACK_REFS_PRUNE 0x0001
#define PACK_REFS_ALL   0x0002

/*
 * Write a packed-refs file for the current repository.
 * flags: Combination of the above PACK_REFS_* flags.
 */
Duy Nguyen's avatar
Duy Nguyen committed
360
int refs_pack_refs(struct ref_store *refs, unsigned int flags);
361

362
/*
363
 * Setup reflog before using. Fill in err and return -1 on failure.
364
 */
Duy Nguyen's avatar
Duy Nguyen committed
365 366
int refs_create_reflog(struct ref_store *refs, const char *refname,
		       int force_create, struct strbuf *err);
367
int safe_create_reflog(const char *refname, int force_create, struct strbuf *err);
368

369
/** Reads log for the value of ref during at_time. **/
370
int read_ref_at(const char *refname, unsigned int flags,
371
		timestamp_t at_time, int cnt,
372
		struct object_id *oid, char **msg,
373
		timestamp_t *cutoff_time, int *cutoff_tz, int *cutoff_cnt);
374

375
/** Check if a particular reflog exists */
Duy Nguyen's avatar
Duy Nguyen committed
376
int refs_reflog_exists(struct ref_store *refs, const char *refname);
377
int reflog_exists(const char *refname);
378

379
/*
380
 * Delete the specified reference. If old_oid is non-NULL, then
381
 * verify that the current value of the reference is old_oid before
382 383 384
 * deleting it. If old_oid is NULL, delete the reference if it
 * exists, regardless of its old value. It is an error for old_oid to
 * be null_oid. msg and flags are passed through to
385
 * ref_transaction_delete().
386
 */
387 388
int refs_delete_ref(struct ref_store *refs, const char *msg,
		    const char *refname,
389
		    const struct object_id *old_oid,
390
		    unsigned int flags);
391
int delete_ref(const char *msg, const char *refname,
392
	       const struct object_id *old_oid, unsigned int flags);
393

394 395 396
/*
 * Delete the specified references. If there are any problems, emit
 * errors but attempt to keep going (i.e., the deletes are not done in
397
 * an all-or-nothing transaction). msg and flags are passed through to
398
 * ref_transaction_delete().
399
 */
400 401 402 403
int refs_delete_refs(struct ref_store *refs, const char *msg,
		     struct string_list *refnames, unsigned int flags);
int delete_refs(const char *msg, struct string_list *refnames,
		unsigned int flags);
404

405
/** Delete a reflog */
Duy Nguyen's avatar
Duy Nguyen committed
406
int refs_delete_reflog(struct ref_store *refs, const char *refname);
407
int delete_reflog(const char *refname);
408

409
/* iterate over reflog entries */
410
typedef int each_reflog_ent_fn(
411
		struct object_id *old_oid, struct object_id *new_oid,
412
		const char *committer, timestamp_t timestamp,
413 414
		int tz, const char *msg, void *cb_data);

Duy Nguyen's avatar
Duy Nguyen committed
415 416 417 418 419 420
int refs_for_each_reflog_ent(struct ref_store *refs, const char *refname,
			     each_reflog_ent_fn fn, void *cb_data);
int refs_for_each_reflog_ent_reverse(struct ref_store *refs,
				     const char *refname,
				     each_reflog_ent_fn fn,
				     void *cb_data);
421
int for_each_reflog_ent(const char *refname, each_reflog_ent_fn fn, void *cb_data);
422
int for_each_reflog_ent_reverse(const char *refname, each_reflog_ent_fn fn, void *cb_data);
423

424 425
/*
 * Calls the specified function for each reflog file until it returns nonzero,
426
 * and returns the value. Reflog file order is unspecified.
427
 */
Duy Nguyen's avatar
Duy Nguyen committed
428
int refs_for_each_reflog(struct ref_store *refs, each_ref_fn fn, void *cb_data);
429
int for_each_reflog(each_ref_fn fn, void *cb_data);
430

431 432 433 434
#define REFNAME_ALLOW_ONELEVEL 1
#define REFNAME_REFSPEC_PATTERN 2

/*
435 436 437
 * Return 0 iff refname has the correct format for a refname according
 * to the rules described in Documentation/git-check-ref-format.txt.
 * If REFNAME_ALLOW_ONELEVEL is set in flags, then accept one-level
438
 * reference names.  If REFNAME_REFSPEC_PATTERN is set in flags, then
439 440
 * allow a single "*" wildcard character in the refspec. No leading or
 * repeated slashes are accepted.
441
 */
442
int check_refname_format(const char *refname, int flags);
Daniel Barkalow's avatar
Daniel Barkalow committed
443

444
const char *prettify_refname(const char *refname);
445

446
char *shorten_unambiguous_ref(const char *refname, int strict);
447

448
/** rename ref, return 0 on success **/
Duy Nguyen's avatar
Duy Nguyen committed
449 450
int refs_rename_ref(struct ref_store *refs, const char *oldref,
		    const char *newref, const char *logmsg);
451 452 453 454 455 456 457 458
int rename_ref(const char *oldref, const char *newref,
			const char *logmsg);

/** copy ref, return 0 on success **/
int refs_copy_existing_ref(struct ref_store *refs, const char *oldref,
		    const char *newref, const char *logmsg);
int copy_existing_ref(const char *oldref, const char *newref,
			const char *logmsg);
459

Duy Nguyen's avatar
Duy Nguyen committed
460 461
int refs_create_symref(struct ref_store *refs, const char *refname,
		       const char *target, const char *logmsg);
462
int create_symref(const char *refname, const char *target, const char *logmsg);
463

464 465 466 467 468 469
enum action_on_err {
	UPDATE_REFS_MSG_ON_ERR,
	UPDATE_REFS_DIE_ON_ERR,
	UPDATE_REFS_QUIET_ON_ERR
};

470 471
/*
 * Begin a reference transaction.  The reference transaction must
472
 * be freed by calling ref_transaction_free().
473
 */
474 475
struct ref_transaction *ref_store_transaction_begin(struct ref_store *refs,
						    struct strbuf *err);
476
struct ref_transaction *ref_transaction_begin(struct strbuf *err);
477 478

/*
479 480 481 482 483 484 485 486 487 488
 * Reference transaction updates
 *
 * The following four functions add a reference check or update to a
 * ref_transaction.  They have some common similar parameters:
 *
 *     transaction -- a pointer to an open ref_transaction, obtained
 *         from ref_transaction_begin().
 *
 *     refname -- the name of the reference to be affected.
 *
489 490
 *     new_oid -- the object ID that should be set to be the new value
 *         of the reference. Some functions allow this parameter to be
491
 *         NULL, meaning that the reference is not changed, or
492
 *         null_oid, meaning that the reference should be deleted. A
493 494
 *         copy of this value is made in the transaction.
 *
495
 *     old_oid -- the object ID that the reference must have before
496 497
 *         the update. Some functions allow this parameter to be NULL,
 *         meaning that the old value of the reference is not checked,
498
 *         or null_oid, meaning that the reference must not exist
499 500 501
 *         before the update. A copy of this value is made in the
 *         transaction.
 *
502
 *     flags -- flags affecting the update, passed to
503
 *         update_ref_lock(). Possible flags: REF_NO_DEREF,
504 505
 *         REF_FORCE_CREATE_REFLOG. See those constants for more
 *         information.
506 507 508 509
 *
 *     msg -- a message describing the change (for the reflog).
 *
 *     err -- a strbuf for receiving a description of any error that
510
 *         might have occurred.
511 512 513 514 515 516 517
 *
 * The functions make internal copies of refname and msg, so the
 * caller retains ownership of these parameters.
 *
 * The functions return 0 on success and non-zero on failure. A
 * failure means that the transaction as a whole has failed and needs
 * to be rolled back.
518 519 520
 */

/*
521 522 523 524 525 526 527 528 529 530
 * The following flags can be passed to ref_transaction_update() etc.
 * Internally, they are stored in `ref_update::flags`, along with some
 * internal flags.
 */

/*
 * Act on the ref directly; i.e., without dereferencing symbolic refs.
 * If this flag is not specified, then symbolic references are
 * dereferenced and the update is applied to the referent.
 */
531
#define REF_NO_DEREF (1 << 0)
532 533 534 535 536 537 538 539 540 541 542 543

/*
 * Force the creation of a reflog for this reference, even if it
 * didn't previously have a reflog.
 */
#define REF_FORCE_CREATE_REFLOG (1 << 1)

/*
 * Bitmask of all of the flags that are allowed to be passed in to
 * ref_transaction_update() and friends:
 */
#define REF_TRANSACTION_UPDATE_ALLOWED_FLAGS \
544
	(REF_NO_DEREF | REF_FORCE_CREATE_REFLOG)
545 546 547 548 549 550 551

/*
 * Add a reference update to transaction. `new_oid` is the value that
 * the reference should have after the update, or `null_oid` if it
 * should be deleted. If `new_oid` is NULL, then the reference is not
 * changed at all. `old_oid` is the value that the reference must have
 * before the update, or `null_oid` if it must not have existed
552
 * beforehand. The old value is checked after the lock is taken to
553 554
 * prevent races. If the old value doesn't agree with old_oid, the
 * whole transaction fails. If old_oid is NULL, then the previous
555 556
 * value is not checked.
 *
557 558
 * See the above comment "Reference transaction updates" for more
 * information.
559
 */
560 561
int ref_transaction_update(struct ref_transaction *transaction,
			   const char *refname,
562 563
			   const struct object_id *new_oid,
			   const struct object_id *old_oid,
564
			   unsigned int flags, const char *msg,
565
			   struct strbuf *err);
566 567

/*
568
 * Add a reference creation to transaction. new_oid is the value that
569
 * the reference should have after the update; it must not be
570
 * null_oid. It is verified that the reference does not exist
571
 * already.
572 573 574
 *
 * See the above comment "Reference transaction updates" for more
 * information.
575
 */
576 577
int ref_transaction_create(struct ref_transaction *transaction,
			   const char *refname,
578
			   const struct object_id *new_oid,
579
			   unsigned int flags, const char *msg,
580
			   struct strbuf *err);
581 582

/*
583
 * Add a reference deletion to transaction. If old_oid is non-NULL,
584
 * then it holds the value that the reference should have had before
585
 * the update (which must not be null_oid).
586 587 588
 *
 * See the above comment "Reference transaction updates" for more
 * information.
589
 */
590 591
int ref_transaction_delete(struct ref_transaction *transaction,
			   const char *refname,
592
			   const struct object_id *old_oid,
593
			   unsigned int flags, const char *msg,
594
			   struct strbuf *err);
595

596
/*
597 598 599
 * Verify, within a transaction, that refname has the value old_oid,
 * or, if old_oid is null_oid, then verify that the reference
 * doesn't exist. old_oid must be non-NULL.
600 601 602
 *
 * See the above comment "Reference transaction updates" for more
 * information.
603 604 605
 */
int ref_transaction_verify(struct ref_transaction *transaction,
			   const char *refname,
606
			   const struct object_id *old_oid,
607 608 609
			   unsigned int flags,
			   struct strbuf *err);

610 611 612 613
/* Naming conflict (for example, the ref names A and A/B conflict). */
#define TRANSACTION_NAME_CONFLICT -1
/* All other errors. */
#define TRANSACTION_GENERIC_ERROR -2
614 615

/*
Ville Skyttä's avatar
Ville Skyttä committed
616
 * Perform the preparatory stages of committing `transaction`. Acquire
617 618 619 620 621 622 623 624 625 626 627
 * any needed locks, check preconditions, etc.; basically, do as much
 * as possible to ensure that the transaction will be able to go
 * through, stopping just short of making any irrevocable or
 * user-visible changes. The updates that this function prepares can
 * be finished up by calling `ref_transaction_commit()` or rolled back
 * by calling `ref_transaction_abort()`.
 *
 * On success, return 0 and leave the transaction in "prepared" state.
 * On failure, abort the transaction, write an error message to `err`,
 * and return one of the `TRANSACTION_*` constants.
 *
Ville Skyttä's avatar
Ville Skyttä committed
628
 * Callers who don't need such fine-grained control over committing
629 630 631 632 633 634 635 636 637 638 639 640
 * reference transactions should just call `ref_transaction_commit()`.
 */
int ref_transaction_prepare(struct ref_transaction *transaction,
			    struct strbuf *err);

/*
 * Commit all of the changes that have been queued in transaction, as
 * atomically as possible. On success, return 0 and leave the
 * transaction in "closed" state. On failure, roll back the
 * transaction, write an error message to `err`, and return one of the
 * `TRANSACTION_*` constants
 */
641
int ref_transaction_commit(struct ref_transaction *transaction,
642
			   struct strbuf *err);
643

644 645 646 647 648 649 650
/*
 * Abort `transaction`, which has been begun and possibly prepared,
 * but not yet committed.
 */
int ref_transaction_abort(struct ref_transaction *transaction,
			  struct strbuf *err);

651 652 653 654 655 656 657 658 659
/*
 * Like ref_transaction_commit(), but optimized for creating
 * references when originally initializing a repository (e.g., by "git
 * clone"). It writes the new references directly to packed-refs
 * without locking the individual references.
 *
 * It is a bug to call this function when there might be other
 * processes accessing the repository or if there are existing
 * references that might conflict with the ones being created. All
660
 * old_oid values must either be absent or null_oid.
661 662 663 664
 */
int initial_ref_transaction_commit(struct ref_transaction *transaction,
				   struct strbuf *err);

665
/*
666
 * Free `*transaction` and all associated data.
667 668 669
 */
void ref_transaction_free(struct ref_transaction *transaction);

670 671 672 673 674 675 676 677
/**
 * Lock, update, and unlock a single reference. This function
 * basically does a transaction containing a single call to
 * ref_transaction_update(). The parameters to this function have the
 * same meaning as the corresponding parameters to
 * ref_transaction_update(). Handle errors as requested by the `onerr`
 * argument.
 */
678
int refs_update_ref(struct ref_store *refs, const char *msg, const char *refname,
679
		    const struct object_id *new_oid, const struct object_id *old_oid,
680
		    unsigned int flags, enum action_on_err onerr);
681
int update_ref(const char *msg, const char *refname,
682 683
	       const struct object_id *new_oid, const struct object_id *old_oid,
	       unsigned int flags, enum action_on_err onerr);
Carlos Rica's avatar
Carlos Rica committed
684

685
int parse_hide_refs_config(const char *var, const char *value, const char *);
686

687 688 689 690 691 692 693 694
/*
 * Check whether a ref is hidden. If no namespace is set, both the first and
 * the second parameter point to the full ref name. If a namespace is set and
 * the ref is inside that namespace, the first parameter is a pointer to the
 * name of the ref with the namespace prefix removed. If a namespace is set and
 * the ref is outside that namespace, the first parameter is NULL. The second
 * parameter always points to the full ref name.
 */
695
int ref_is_hidden(const char *, const char *);
696

David Turner's avatar
David Turner committed
697 698 699 700 701 702 703 704
enum ref_type {
	REF_TYPE_PER_WORKTREE,
	REF_TYPE_PSEUDOREF,
	REF_TYPE_NORMAL,
};

enum ref_type ref_type(const char *refname);

705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728
enum expire_reflog_flags {
	EXPIRE_REFLOGS_DRY_RUN = 1 << 0,
	EXPIRE_REFLOGS_UPDATE_REF = 1 << 1,
	EXPIRE_REFLOGS_VERBOSE = 1 << 2,
	EXPIRE_REFLOGS_REWRITE = 1 << 3
};

/*
 * The following interface is used for reflog expiration. The caller
 * calls reflog_expire(), supplying it with three callback functions,
 * of the following types. The callback functions define the
 * expiration policy that is desired.
 *
 * reflog_expiry_prepare_fn -- Called once after the reference is
 *     locked.
 *
 * reflog_expiry_should_prune_fn -- Called once for each entry in the
 *     existing reflog. It should return true iff that entry should be
 *     pruned.
 *
 * reflog_expiry_cleanup_fn -- Called once before the reference is
 *     unlocked again.
 */
typedef void reflog_expiry_prepare_fn(const char *refname,
729
				      const struct object_id *oid,
730
				      void *cb_data);
731 732
typedef int reflog_expiry_should_prune_fn(struct object_id *ooid,
					  struct object_id *noid,
733
					  const char *email,
734
					  timestamp_t timestamp, int tz,
735 736 737 738
					  const char *message, void *cb_data);
typedef void reflog_expiry_cleanup_fn(void *cb_data);

/*
739
 * Expire reflog entries for the specified reference. oid is the old
740 741 742 743
 * value of the reference. flags is a combination of the constants in
 * enum expire_reflog_flags. The three function pointers are described
 * above. On success, return zero.
 */
Duy Nguyen's avatar
Duy Nguyen committed
744 745
int refs_reflog_expire(struct ref_store *refs,
		       const char *refname,
746
		       const struct object_id *oid,
Duy Nguyen's avatar
Duy Nguyen committed
747 748 749 750 751
		       unsigned int flags,
		       reflog_expiry_prepare_fn prepare_fn,
		       reflog_expiry_should_prune_fn should_prune_fn,
		       reflog_expiry_cleanup_fn cleanup_fn,
		       void *policy_cb_data);
752
int reflog_expire(const char *refname, const struct object_id *oid,
753 754 755 756 757
		  unsigned int flags,
		  reflog_expiry_prepare_fn prepare_fn,
		  reflog_expiry_should_prune_fn should_prune_fn,
		  reflog_expiry_cleanup_fn cleanup_fn,
		  void *policy_cb_data);
758

759 760
int ref_storage_backend_exists(const char *name);

761
struct ref_store *get_main_ref_store(struct repository *r);
762 763 764 765 766 767 768 769 770 771 772
/*
 * Return the ref_store instance for the specified submodule. For the
 * main repository, use submodule==NULL; such a call cannot fail. For
 * a submodule, the submodule must exist and be a nonbare repository,
 * otherwise return NULL. If the requested reference store has not yet
 * been initialized, initialize it first.
 *
 * For backwards compatibility, submodule=="" is treated the same as
 * submodule==NULL.
 */
struct ref_store *get_submodule_ref_store(const char *submodule);
773
struct ref_store *get_worktree_ref_store(const struct worktree *wt);
774

Daniel Barkalow's avatar
Daniel Barkalow committed
775
#endif /* REFS_H */