refname_is_safe(): improve docstring

diff --git a/refs.c b/refs.c
index 480de9ac92bbc7b48202ca3dd1029ab16a19b739..f48c58a7b672920d3975c21a2bcd61f6b55ab8ec 100644 (file)
--- a/refs.c
+++ b/refs.c
@@ -341,13 +341,17 @@ static struct ref_dir *get_ref_dir(struct ref_entry *entry)
 }
 
 /*
- * Check if a refname is safe.
- * For refs that start with "refs/" we consider it safe as long they do
- * not try to resolve to outside of refs/.
+ * Return true iff refname is minimally safe. "Safe" here means that
+ * deleting a loose reference by this name will not do any damage, for
+ * example by causing a file that is not a reference to be deleted.
+ * This function does not check that the reference name is legal; for
+ * that, use check_refname_format().
  *
- * For all other refs we only consider them safe iff they only contain
- * upper case characters and '_' (like "HEAD" AND "MERGE_HEAD", and not like
- * "config").
+ * We consider a refname that starts with "refs/" to be safe as long
+ * as any ".." components that it might contain do not escape "refs/".
+ * Names that do not start with "refs/" are considered safe iff they
+ * consist entirely of upper case characters and '_' (like "HEAD" and
+ * "MERGE_HEAD" but not "config" or "FOO/BAR").
  */
 static int refname_is_safe(const char *refname)
 {
@@ -2671,8 +2675,6 @@ struct pack_refs_cb_data {
        struct ref_to_prune *ref_to_prune;
 };
 
-static int is_per_worktree_ref(const char *refname);
-
 /*
  * An each_ref_entry_fn that is run over loose references only.  If
  * the loose reference can be packed, add an entry in the packed ref
@@ -2687,7 +2689,7 @@ static int pack_if_possible_fn(struct ref_entry *entry, void *cb_data)
        int is_tag_ref = starts_with(entry->name, "refs/tags/");
 
        /* Do not pack per-worktree refs: */
-       if (is_per_worktree_ref(entry->name))
+       if (ref_type(entry->name) != REF_TYPE_NORMAL)
                return 0;
 
        /* ALWAYS pack tags */