diff options
Diffstat (limited to 'refs.h')
-rw-r--r-- | refs.h | 282 |
1 files changed, 233 insertions, 49 deletions
@@ -1,6 +1,8 @@ #ifndef REFS_H #define REFS_H +#include "commit.h" + struct object_id; struct ref_store; struct repository; @@ -9,6 +11,9 @@ struct string_list; struct string_list_item; struct worktree; +unsigned int ref_storage_format_by_name(const char *name); +const char *ref_storage_format_to_name(unsigned int ref_storage_format); + /* * Resolve a reference, recursively following symbolic refererences. * @@ -54,18 +59,25 @@ struct worktree; * 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, + * Caps and underscores refers to the pseudorefs, 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 +struct pack_refs_opts { + unsigned int flags; + struct ref_exclusions *exclusions; + struct string_list *includes; +}; + const char *refs_resolve_ref_unsafe(struct ref_store *refs, const char *refname, int resolve_flags, struct object_id *oid, int *flags); + const char *resolve_ref_unsafe(const char *refname, int resolve_flags, struct object_id *oid, int *flags); @@ -75,12 +87,13 @@ char *refs_resolve_refdup(struct ref_store *refs, char *resolve_refdup(const char *refname, int resolve_flags, struct object_id *oid, int *flags); -int refs_read_ref_full(struct ref_store *refs, const char *refname, - int resolve_flags, struct object_id *oid, int *flags); int read_ref_full(const char *refname, int resolve_flags, struct object_id *oid, int *flags); int read_ref(const char *refname, struct object_id *oid); +int refs_read_symbolic_ref(struct ref_store *ref_store, const char *refname, + struct strbuf *referent); + /* * Return 0 if a reference named refname could be created without * conflicting with the name of an existing reference. Otherwise, @@ -105,25 +118,29 @@ int refs_verify_refname_available(struct ref_store *refs, const struct string_list *skip, struct strbuf *err); +int refs_ref_exists(struct ref_store *refs, const char *refname); + int ref_exists(const char *refname); int should_autocreate_reflog(const char *refname); int is_branch(const char *refname); -int refs_init_db(struct strbuf *err); +#define REFS_INIT_DB_IS_WORKTREE (1 << 0) + +int refs_init_db(struct ref_store *refs, int flags, struct strbuf *err); /* - * 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, - * 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. - * Symbolic references are considered unpeelable, even if they - * ultimately resolve to a peelable tag. + * Return the peeled value of the oid currently being iterated via + * for_each_ref(), etc. This is equivalent to calling: + * + * peel_object(oid, &peeled); + * + * with the "oid" value given to the each_ref_fn callback, except + * that some ref storage may be able to answer the query without + * actually loading the object in memory. */ -int refs_peel_ref(struct ref_store *refs, const char *refname, - struct object_id *oid); -int peel_ref(const char *refname, struct object_id *oid); +int peel_iterated_oid(const struct object_id *base, struct object_id *peeled); /** * Resolve refname in the nested "gitlink" repository in the specified @@ -149,9 +166,9 @@ struct strvec; void expand_ref_prefix(struct strvec *prefixes, const char *prefix); int expand_ref(struct repository *r, const char *str, int len, struct object_id *oid, char **ref); -int repo_dwim_ref(struct repository *r, const char *str, int len, struct object_id *oid, char **ref); +int repo_dwim_ref(struct repository *r, const char *str, int len, + struct object_id *oid, char **ref, int nonfatal_dangling_mark); int repo_dwim_log(struct repository *r, 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); int dwim_log(const char *str, int len, struct object_id *oid, char **ref); /* @@ -160,8 +177,8 @@ int dwim_log(const char *str, int len, struct object_id *oid, char **ref); * The return value of `repo_default_branch_name()` is an allocated string. The * return value of `git_default_branch_name()` is a singleton. */ -const char *git_default_branch_name(void); -char *repo_default_branch_name(struct repository *r); +const char *git_default_branch_name(int quiet); +char *repo_default_branch_name(struct repository *r, int quiet); /* * A ref_transaction represents a collection of reference updates that @@ -331,11 +348,29 @@ 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); +/* + * references matching any pattern in "exclude_patterns" are omitted from the + * result set on a best-effort basis. + */ int refs_for_each_fullref_in(struct ref_store *refs, const char *prefix, - each_ref_fn fn, void *cb_data, - unsigned int broken); -int for_each_fullref_in(const char *prefix, each_ref_fn fn, void *cb_data, - unsigned int broken); + const char **exclude_patterns, + each_ref_fn fn, void *cb_data); +int for_each_fullref_in(const char *prefix, each_ref_fn fn, void *cb_data); + +/** + * iterate all refs in "patterns" by partitioning patterns into disjoint sets + * and iterating the longest-common prefix of each set. + * + * references matching any pattern in "exclude_patterns" are omitted from the + * result set on a best-effort basis. + * + * callers should be prepared to ignore references that they did not ask for. + */ +int refs_for_each_fullref_in_prefixes(struct ref_store *refs, + const char *namespace, + const char **patterns, + const char **exclude_patterns, + each_ref_fn fn, void *cb_data); /** * iterate refs from the respective area. @@ -352,13 +387,24 @@ 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); +/* + * references matching any pattern in "exclude_patterns" are omitted from the + * result set on a best-effort basis. + */ +int for_each_namespaced_ref(const char **exclude_patterns, + each_ref_fn fn, void *cb_data); /* can be used to learn about broken ref and symref */ int refs_for_each_rawref(struct ref_store *refs, each_ref_fn fn, void *cb_data); int for_each_rawref(each_ref_fn fn, void *cb_data); /* + * Iterates over all refs including root refs, i.e. pseudorefs and HEAD. + */ +int refs_for_each_include_root_refs(struct ref_store *refs, each_ref_fn fn, + void *cb_data); + +/* * 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. @@ -391,16 +437,29 @@ void warn_dangling_symrefs(FILE *fp, const char *msg_fmt, * Write a packed-refs file for the current repository. * flags: Combination of the above PACK_REFS_* flags. */ -int refs_pack_refs(struct ref_store *refs, unsigned int flags); +int refs_pack_refs(struct ref_store *refs, struct pack_refs_opts *opts); /* * Setup reflog before using. Fill in err and return -1 on failure. */ int refs_create_reflog(struct ref_store *refs, const char *refname, - int force_create, struct strbuf *err); -int safe_create_reflog(const char *refname, int force_create, struct strbuf *err); + struct strbuf *err); +int safe_create_reflog(const char *refname, struct strbuf *err); -/** Reads log for the value of ref during at_time. **/ +/** + * Reads log for the value of ref during at_time (in which case "cnt" should be + * negative) or the reflog "cnt" entries from the top (in which case "at_time" + * should be 0). + * + * If we found the reflog entry in question, returns 0 (and details of the + * entry can be found in the out-parameters). + * + * If we ran out of reflog entries, the out-parameters are filled with the + * details of the oldest entry we did find, and the function returns 1. Note + * that there is one important special case here! If the reflog was empty + * and the caller asked for the 0-th cnt, we will return "1" but leave the + * "oid" field untouched. + **/ int read_ref_at(struct ref_store *refs, const char *refname, unsigned int flags, timestamp_t at_time, int cnt, @@ -443,7 +502,29 @@ int delete_reflog(const char *refname); /* * Callback to process a reflog entry found by the iteration functions (see - * below) + * below). + * + * The committer parameter is a single string, in the form + * "$GIT_COMMITTER_NAME <$GIT_COMMITTER_EMAIL>" (without double quotes). + * + * The timestamp parameter gives the time when entry was created as the number + * of seconds since the UNIX epoch. + * + * The tz parameter gives the timezone offset for the user who created + * the reflog entry, and its value gives a positive or negative offset + * from UTC. Its absolute value is formed by multiplying the hour + * part by 100 and adding the minute part. For example, 1 hour ahead + * of UTC, CET == "+0100", is represented as positive one hundred (not + * postiive sixty). + * + * The msg parameter is a single complete line; a reflog message given + * to refs_delete_ref, refs_update_ref, etc. is returned to the + * callback normalized---each run of whitespaces are squashed into a + * single whitespace, trailing whitespace, if exists, is trimmed, and + * then a single LF is added at the end. + * + * The cb_data is a caller-supplied pointer given to the iterator + * functions. */ typedef int each_reflog_ent_fn( struct object_id *old_oid, struct object_id *new_oid, @@ -473,11 +554,18 @@ int for_each_reflog_ent(const char *refname, each_reflog_ent_fn fn, void *cb_dat int for_each_reflog_ent_reverse(const char *refname, each_reflog_ent_fn fn, void *cb_data); /* + * The signature for the callback function for the {refs_,}for_each_reflog() + * functions below. The memory pointed to by the refname argument is only + * guaranteed to be valid for the duration of a single callback invocation. + */ +typedef int each_reflog_fn(const char *refname, void *cb_data); + +/* * Calls the specified function for each reflog file until it returns nonzero, * and returns the value. Reflog file order is unspecified. */ -int refs_for_each_reflog(struct ref_store *refs, each_ref_fn fn, void *cb_data); -int for_each_reflog(each_ref_fn fn, void *cb_data); +int refs_for_each_reflog(struct ref_store *refs, each_reflog_fn fn, void *cb_data); +int for_each_reflog(each_reflog_fn fn, void *cb_data); #define REFNAME_ALLOW_ONELEVEL 1 #define REFNAME_REFSPEC_PATTERN 2 @@ -596,11 +684,23 @@ struct ref_transaction *ref_transaction_begin(struct strbuf *err); #define REF_FORCE_CREATE_REFLOG (1 << 1) /* + * Blindly write an object_id. This is useful for testing data corruption + * scenarios. + */ +#define REF_SKIP_OID_VERIFICATION (1 << 10) + +/* + * Skip verifying refname. This is useful for testing data corruption scenarios. + */ +#define REF_SKIP_REFNAME_VERIFICATION (1 << 11) + +/* * 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 \ - (REF_NO_DEREF | REF_FORCE_CREATE_REFLOG) +#define REF_TRANSACTION_UPDATE_ALLOWED_FLAGS \ + (REF_NO_DEREF | REF_FORCE_CREATE_REFLOG | REF_SKIP_OID_VERIFICATION | \ + REF_SKIP_REFNAME_VERIFICATION) /* * Add a reference update to transaction. `new_oid` is the value that @@ -722,6 +822,20 @@ int initial_ref_transaction_commit(struct ref_transaction *transaction, struct strbuf *err); /* + * Execute the given callback function for each of the reference updates which + * have been queued in the given transaction. `old_oid` and `new_oid` may be + * `NULL` pointers depending on whether the update has these object IDs set or + * not. + */ +typedef void ref_transaction_for_each_queued_update_fn(const char *refname, + const struct object_id *old_oid, + const struct object_id *new_oid, + void *cb_data); +void ref_transaction_for_each_queued_update(struct ref_transaction *transaction, + ref_transaction_for_each_queued_update_fn cb, + void *cb_data); + +/* * Free `*transaction` and all associated data. */ void ref_transaction_free(struct ref_transaction *transaction); @@ -741,7 +855,8 @@ int update_ref(const char *msg, const char *refname, const struct object_id *new_oid, const struct object_id *old_oid, unsigned int flags, enum action_on_err onerr); -int parse_hide_refs_config(const char *var, const char *value, const char *); +int parse_hide_refs_config(const char *var, const char *value, const char *, + struct strvec *); /* * Check whether a ref is hidden. If no namespace is set, both the first and @@ -751,23 +866,47 @@ int parse_hide_refs_config(const char *var, const char *value, const char *); * the ref is outside that namespace, the first parameter is NULL. The second * parameter always points to the full ref name. */ -int ref_is_hidden(const char *, const char *); +int ref_is_hidden(const char *, const char *, const struct strvec *); -enum ref_type { - REF_TYPE_PER_WORKTREE, /* refs inside refs/ but not shared */ - REF_TYPE_PSEUDOREF, /* refs outside refs/ in current worktree */ - REF_TYPE_MAIN_PSEUDOREF, /* pseudo refs from the main worktree */ - REF_TYPE_OTHER_PSEUDOREF, /* pseudo refs from other worktrees */ - REF_TYPE_NORMAL, /* normal/shared refs inside refs/ */ +/* + * Returns an array of patterns to use as excluded_patterns, if none of the + * hidden references use the token '!' or '^'. + */ +const char **hidden_refs_to_excludes(const struct strvec *hide_refs); + +/* Is this a per-worktree ref living in the refs/ namespace? */ +int is_per_worktree_ref(const char *refname); + +/* Describes how a refname relates to worktrees */ +enum ref_worktree_type { + REF_WORKTREE_CURRENT, /* implicitly per worktree, eg. HEAD or + refs/bisect/SOMETHING */ + REF_WORKTREE_MAIN, /* explicitly in main worktree, eg. + main-worktree/HEAD */ + REF_WORKTREE_OTHER, /* explicitly in named worktree, eg. + worktrees/bla/HEAD */ + REF_WORKTREE_SHARED, /* the default, eg. refs/heads/main */ }; -enum ref_type ref_type(const char *refname); +/* + * Parse a `maybe_worktree_ref` as a ref that possibly refers to a worktree ref + * (ie. either REFNAME, main-worktree/REFNAME or worktree/WORKTREE/REFNAME). It + * returns what kind of ref was found, and in case of REF_WORKTREE_OTHER, the + * worktree name is returned in `worktree_name` (pointing into + * `maybe_worktree_ref`) and `worktree_name_length`. The bare refname (the + * refname stripped of prefixes) is returned in `bare_refname`. The + * `worktree_name`, `worktree_name_length` and `bare_refname` arguments may be + * NULL. + */ +enum ref_worktree_type parse_worktree_ref(const char *maybe_worktree_ref, + const char **worktree_name, + int *worktree_name_length, + const char **bare_refname); 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 + EXPIRE_REFLOGS_REWRITE = 1 << 2, }; /* @@ -777,7 +916,7 @@ enum expire_reflog_flags { * expiration policy that is desired. * * reflog_expiry_prepare_fn -- Called once after the reference is - * locked. + * locked. Called with the OID of the locked reference. * * reflog_expiry_should_prune_fn -- Called once for each entry in the * existing reflog. It should return true iff that entry should be @@ -797,28 +936,25 @@ typedef int reflog_expiry_should_prune_fn(struct object_id *ooid, typedef void reflog_expiry_cleanup_fn(void *cb_data); /* - * Expire reflog entries for the specified reference. oid is the old - * value of the reference. flags is a combination of the constants in + * Expire reflog entries for the specified reference. + * flags is a combination of the constants in * enum expire_reflog_flags. The three function pointers are described * above. On success, return zero. */ int refs_reflog_expire(struct ref_store *refs, const char *refname, - const struct object_id *oid, 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); -int reflog_expire(const char *refname, const struct object_id *oid, +int reflog_expire(const char *refname, 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); -int ref_storage_backend_exists(const char *name); - struct ref_store *get_main_ref_store(struct repository *r); /** @@ -868,4 +1004,52 @@ struct ref_store *get_main_ref_store(struct repository *r); struct ref_store *get_submodule_ref_store(const char *submodule); struct ref_store *get_worktree_ref_store(const struct worktree *wt); +/* + * Some of the names specified by refs have special meaning to Git. + * Organize these namespaces in a comon 'ref_namespace' array for + * reference from multiple places in the codebase. + */ + +struct ref_namespace_info { + char *ref; + enum decoration_type decoration; + + /* + * If 'exact' is true, then we must match the 'ref' exactly. + * Otherwise, use a prefix match. + * + * 'ref_updated' is for internal use. It represents whether the + * 'ref' value was replaced from its original literal version. + */ + unsigned exact:1, + ref_updated:1; +}; + +enum ref_namespace { + NAMESPACE_HEAD, + NAMESPACE_BRANCHES, + NAMESPACE_TAGS, + NAMESPACE_REMOTE_REFS, + NAMESPACE_STASH, + NAMESPACE_REPLACE, + NAMESPACE_NOTES, + NAMESPACE_PREFETCH, + NAMESPACE_REWRITTEN, + + /* Must be last */ + NAMESPACE__COUNT +}; + +/* See refs.c for the contents of this array. */ +extern struct ref_namespace_info ref_namespace[NAMESPACE__COUNT]; + +/* + * Some ref namespaces can be modified by config values or environment + * variables. Modify a namespace as specified by its ref_namespace key. + */ +void update_ref_namespace(enum ref_namespace namespace, char *ref); + +int is_pseudoref(struct ref_store *refs, const char *refname); +int is_headref(struct ref_store *refs, const char *refname); + #endif /* REFS_H */ |