Merge branch 'ps/pseudo-ref-terminology' into ps/ref-storage-migration

* ps/pseudo-ref-terminology:
  refs: refuse to write pseudorefs
  ref-filter: properly distinuish pseudo and root refs
  refs: pseudorefs are no refs
  refs: classify HEAD as a root ref
  refs: do not check ref existence in `is_root_ref()`
  refs: rename `is_special_ref()` to `is_pseudo_ref()`
  refs: rename `is_pseudoref()` to `is_root_ref()`
  Documentation/glossary: define root refs as refs
  Documentation/glossary: clarify limitations of pseudorefs
  Documentation/glossary: redefine pseudorefs as special refs

diff --cc Documentation/glossary-content.txt
Simple merge

diff --cc ref-filter.c
index 79e7d3910d3d9459b423c1daa6ab1a261bb1d7f1,41f639bc2fd87fede7fa5747e289abf1e8a431ea..f7fb0c7e0ec1b8ab3af987245dcb048a87ca1f3a
--- 1/ref-filter.c
--- 2/ref-filter.c
+++ b/ref-filter.c
@@@ -3086,10 -3074,9 +3088,10 @@@ static int do_filter_refs(struct ref_fi
                 * When printing all ref types, HEAD is already included,
                 * so we don't want to print HEAD again.
                 */
-               if (!ret && (filter->kind != FILTER_REFS_KIND_MASK) &&
+               if (!ret && !(filter->kind & FILTER_REFS_ROOT_REFS) &&
                    (filter->kind & FILTER_REFS_DETACHED_HEAD))
 -                      head_ref(fn, cb_data);
 +                      refs_head_ref(get_main_ref_store(the_repository), fn,
 +                                    cb_data);
        }
  
        clear_contains_cache(&filter->internal.contains_cache);

diff --cc refs.c
Simple merge

diff --cc refs.h
index b230cc89d1a28e4f59d622737b5291d14ce6b910,dc4358727f3f76ad336fcadc6c2dd60df4ea28a2..fe7f0db35e66c0a7d3029885e2dab7267902b275
--- 1/refs.h
--- 2/refs.h
+++ b/refs.h
@@@ -1006,214 -1051,51 +1006,258 @@@ extern struct ref_namespace_info ref_na
   */
  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);
+ /*
+  * Check whether the provided name names a root reference. This function only
+  * performs a syntactic check.
+  *
+  * A root ref is a reference that lives in the root of the reference hierarchy.
+  * These references must conform to special syntax:
+  *
+  *   - Their name must be all-uppercase or underscores ("_").
+  *
+  *   - Their name must end with "_HEAD". As a special rule, "HEAD" is a root
+  *     ref, as well.
+  *
+  *   - Their name may not contain a slash.
+  *
+  * There is a special set of irregular root refs that exist due to historic
+  * reasons, only. This list shall not be expanded in the future:
+  *
+  *   - AUTO_MERGE
+  *
+  *   - BISECT_EXPECTED_REV
+  *
+  *   - NOTES_MERGE_PARTIAL
+  *
+  *   - NOTES_MERGE_REF
+  *
+  *   - MERGE_AUTOSTASH
+  */
+ int is_root_ref(const char *refname);
+ 
+ /*
+  * Pseudorefs are refs that have different semantics compared to
+  * "normal" refs. These refs can thus not be stored in the ref backend,
+  * but must always be accessed via the filesystem. The following refs
+  * are pseudorefs:
+  *
+  * - FETCH_HEAD may contain multiple object IDs, and each one of them
+  *   carries additional metadata like where it came from.
+  *
+  * - MERGE_HEAD may contain multiple object IDs when merging multiple
+  *   heads.
+  *
+  * Reading, writing or deleting references must consistently go either
+  * through the filesystem (pseudorefs) or through the reference
+  * backend (normal ones).
+  */
+ int is_pseudo_ref(const char *refname);
  
 +/*
 + * The following functions have been removed in Git v2.45 in favor of functions
 + * that receive a `ref_store` as parameter. The intent of this section is
 + * merely to help patch authors of in-flight series to have a reference what
 + * they should be migrating to. The section will be removed in Git v2.46.
 + */
 +#if 0
 +static char *resolve_refdup(const char *refname, int resolve_flags,
 +                          struct object_id *oid, int *flags)
 +{
 +      return refs_resolve_refdup(get_main_ref_store(the_repository),
 +                                 refname, resolve_flags,
 +                                 oid, flags);
 +}
 +
 +static int read_ref_full(const char *refname, int resolve_flags,
 +                       struct object_id *oid, int *flags)
 +{
 +      return refs_read_ref_full(get_main_ref_store(the_repository), refname,
 +                                resolve_flags, oid, flags);
 +}
 +
 +static int read_ref(const char *refname, struct object_id *oid)
 +{
 +      return refs_read_ref(get_main_ref_store(the_repository), refname, oid);
 +}
 +
 +static int ref_exists(const char *refname)
 +{
 +      return refs_ref_exists(get_main_ref_store(the_repository), refname);
 +}
 +
 +static int for_each_tag_ref(each_ref_fn fn, void *cb_data)
 +{
 +      return refs_for_each_tag_ref(get_main_ref_store(the_repository), fn, cb_data);
 +}
 +
 +static int for_each_branch_ref(each_ref_fn fn, void *cb_data)
 +{
 +      return refs_for_each_branch_ref(get_main_ref_store(the_repository), fn, cb_data);
 +}
 +
 +static int for_each_remote_ref(each_ref_fn fn, void *cb_data)
 +{
 +      return refs_for_each_remote_ref(get_main_ref_store(the_repository), fn, cb_data);
 +}
 +
 +static int head_ref_namespaced(each_ref_fn fn, void *cb_data)
 +{
 +      return refs_head_ref_namespaced(get_main_ref_store(the_repository),
 +                                      fn, cb_data);
 +}
 +
 +static int for_each_glob_ref_in(each_ref_fn fn, const char *pattern,
 +                              const char *prefix, void *cb_data)
 +{
 +      return refs_for_each_glob_ref_in(get_main_ref_store(the_repository),
 +                                       fn, pattern, prefix, cb_data);
 +}
 +
 +static int for_each_glob_ref(each_ref_fn fn, const char *pattern, void *cb_data)
 +{
 +      return refs_for_each_glob_ref(get_main_ref_store(the_repository),
 +                                    fn, pattern, cb_data);
 +}
 +
 +static int delete_ref(const char *msg, const char *refname,
 +                    const struct object_id *old_oid, unsigned int flags)
 +{
 +      return refs_delete_ref(get_main_ref_store(the_repository), msg, refname,
 +                             old_oid, flags);
 +}
 +
 +static struct ref_transaction *ref_transaction_begin(struct strbuf *err)
 +{
 +      return ref_store_transaction_begin(get_main_ref_store(the_repository), err);
 +}
 +
 +static 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)
 +{
 +      return refs_update_ref(get_main_ref_store(the_repository), msg, refname, new_oid,
 +                             old_oid, flags, onerr);
 +}
 +
 +static char *shorten_unambiguous_ref(const char *refname, int strict)
 +{
 +      return refs_shorten_unambiguous_ref(get_main_ref_store(the_repository),
 +                                          refname, strict);
 +}
 +
 +static int head_ref(each_ref_fn fn, void *cb_data)
 +{
 +      return refs_head_ref(get_main_ref_store(the_repository), fn, cb_data);
 +}
 +
 +static int for_each_ref(each_ref_fn fn, void *cb_data)
 +{
 +      return refs_for_each_ref(get_main_ref_store(the_repository), fn, cb_data);
 +}
 +
 +static int for_each_ref_in(const char *prefix, each_ref_fn fn, void *cb_data)
 +{
 +      return refs_for_each_ref_in(get_main_ref_store(the_repository), prefix, fn, cb_data);
 +}
 +
 +static int for_each_fullref_in(const char *prefix,
 +                             const char **exclude_patterns,
 +                             each_ref_fn fn, void *cb_data)
 +{
 +      return refs_for_each_fullref_in(get_main_ref_store(the_repository),
 +                                      prefix, exclude_patterns, fn, cb_data);
 +}
 +
 +static int for_each_namespaced_ref(const char **exclude_patterns,
 +                                 each_ref_fn fn, void *cb_data)
 +{
 +      return refs_for_each_namespaced_ref(get_main_ref_store(the_repository),
 +                                          exclude_patterns, fn, cb_data);
 +}
 +
 +static int for_each_rawref(each_ref_fn fn, void *cb_data)
 +{
 +      return refs_for_each_rawref(get_main_ref_store(the_repository), fn, cb_data);
 +}
 +
 +static const char *resolve_ref_unsafe(const char *refname, int resolve_flags,
 +                                    struct object_id *oid, int *flags)
 +{
 +      return refs_resolve_ref_unsafe(get_main_ref_store(the_repository), refname,
 +                                     resolve_flags, oid, flags);
 +}
 +
 +static int create_symref(const char *ref_target, const char *refs_heads_master,
 +                       const char *logmsg)
 +{
 +      return refs_create_symref(get_main_ref_store(the_repository), ref_target,
 +                                refs_heads_master, logmsg);
 +}
 +
 +static int for_each_reflog(each_reflog_fn fn, void *cb_data)
 +{
 +      return refs_for_each_reflog(get_main_ref_store(the_repository), fn, cb_data);
 +}
 +
 +static int for_each_reflog_ent_reverse(const char *refname, each_reflog_ent_fn fn,
 +                                     void *cb_data)
 +{
 +      return refs_for_each_reflog_ent_reverse(get_main_ref_store(the_repository),
 +                                              refname, fn, cb_data);
 +}
 +
 +static int for_each_reflog_ent(const char *refname, each_reflog_ent_fn fn,
 +                             void *cb_data)
 +{
 +      return refs_for_each_reflog_ent(get_main_ref_store(the_repository), refname,
 +                                      fn, cb_data);
 +}
 +
 +static int reflog_exists(const char *refname)
 +{
 +      return refs_reflog_exists(get_main_ref_store(the_repository), refname);
 +}
 +
 +static int safe_create_reflog(const char *refname, struct strbuf *err)
 +{
 +      return refs_create_reflog(get_main_ref_store(the_repository), refname,
 +                                err);
 +}
 +
 +static int delete_reflog(const char *refname)
 +{
 +      return refs_delete_reflog(get_main_ref_store(the_repository), refname);
 +}
 +
 +static 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)
 +{
 +      return refs_reflog_expire(get_main_ref_store(the_repository),
 +                                refname, flags,
 +                                prepare_fn, should_prune_fn,
 +                                cleanup_fn, policy_cb_data);
 +}
 +
 +static int delete_refs(const char *msg, struct string_list *refnames,
 +                     unsigned int flags)
 +{
 +      return refs_delete_refs(get_main_ref_store(the_repository), msg, refnames, flags);
 +}
 +
 +static int rename_ref(const char *oldref, const char *newref, const char *logmsg)
 +{
 +      return refs_rename_ref(get_main_ref_store(the_repository), oldref, newref, logmsg);
 +}
 +
 +static int copy_existing_ref(const char *oldref, const char *newref, const char *logmsg)
 +{
 +      return refs_copy_existing_ref(get_main_ref_store(the_repository), oldref, newref, logmsg);
 +}
 +#endif
 +
  #endif /* REFS_H */

diff --cc refs/files-backend.c
Simple merge

diff --cc refs/reftable-backend.c
Simple merge

diff --cc t/t5510-fetch.sh
Simple merge