From 24237552ec452c892f6a589b2a56c5acfec44ede Mon Sep 17 00:00:00 2001
From: Lorenz Leutgeb <lorenz.leutgeb@radicle.xyz>
Date: Sun, 7 Sep 2025 18:42:28 +0200
Subject: [PATCH] ref-format: Relax first component of namespaced

The [manual page](man:gitnamespaces(7)) says:

> Git supports dividing the refs of a single repository into
> multiple namespaces, each of which has its own branches,
> tags, and `HEAD`.

Here, the mention of `HEAD` implies that requiring all
namespaced to start with

    refs/namespaces/*/refs

is too strict, as there are legal namespaced refs such as

    refs/namespaces/*/HEAD

which are not captured. Relax the corresponding condition, change
documentation and add a test to avoid regression.
---
 radicle-git-ext/git-ref-format/core/src/deriv.rs |  5 +++--
 radicle-git-ext/t/src/git_ref_format/tests.rs    | 11 +++++++++++
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/radicle-git-ext/git-ref-format/core/src/deriv.rs b/radicle-git-ext/git-ref-format/core/src/deriv.rs
index e67eb78..00c0a5f 100644
--- a/radicle-git-ext/git-ref-format/core/src/deriv.rs
+++ b/radicle-git-ext/git-ref-format/core/src/deriv.rs
@@ -267,9 +267,10 @@ impl Display for Qualified<'_> {
 /// A [`Qualified`] ref under a git namespace.
 ///
 /// A ref is namespaced if it starts with "refs/namespaces/", another path
-/// component, and "refs/". Eg.
+/// component, and "refs" or "HEAD". Eg.
 ///
 ///     refs/namespaces/xyz/refs/heads/main
+///     refs/namespaces/xyz/HEAD
 ///
 /// Note that namespaces can be nested, so the result of
 /// [`Namespaced::strip_namespace`] may be convertible to a [`Namespaced`]
@@ -365,7 +366,7 @@ impl<'a> From<&'a RefStr> for Option<Namespaced<'a>> {
     fn from(rs: &'a RefStr) -> Self {
         let mut cs = rs.iter();
         match (cs.next()?, cs.next()?, cs.next()?, cs.next()?) {
-            ("refs", "namespaces", _, "refs") => Some(Namespaced(Cow::from(rs))),
+            ("refs", "namespaces", _, "refs" | "HEAD") => Some(Namespaced(Cow::from(rs))),
 
             _ => None,
         }
diff --git a/radicle-git-ext/t/src/git_ref_format/tests.rs b/radicle-git-ext/t/src/git_ref_format/tests.rs
index 8a43669..e638bcf 100644
--- a/radicle-git-ext/t/src/git_ref_format/tests.rs
+++ b/radicle-git-ext/t/src/git_ref_format/tests.rs
@@ -156,6 +156,17 @@ fn namespaced() {
     )
 }
 
+#[test]
+fn namespaced_head() {
+    assert_eq!(
+        "refs/namespaces/foo/HEAD",
+        refname!("refs/namespaces/foo/HEAD")
+            .to_namespaced()
+            .unwrap()
+            .as_str()
+    )
+}
+
 #[test]
 fn not_namespaced() {
     assert!(name::REFS_HEADS_MAIN.to_namespaced().is_none())