gix_ref/
name.rs

1use std::{convert, convert::Infallible, ffi::OsStr, path::Path};
2
3use gix_object::bstr::{BStr, BString, ByteSlice, ByteVec};
4
5use crate::{Category, FullName, FullNameRef, PartialName, PartialNameRef};
6
7/// The error used in the [`PartialNameRef`]`::try_from`(…) implementations.
8pub type Error = gix_validate::reference::name::Error;
9
10impl Category<'_> {
11    /// Return the prefix that would contain all references of our kind, or an empty string if the reference would
12    /// be directly inside of the [`git_dir()`][crate::file::Store::git_dir()].
13    pub fn prefix(&self) -> &BStr {
14        match self {
15            Category::Tag => b"refs/tags/".as_bstr(),
16            Category::LocalBranch => b"refs/heads/".as_bstr(),
17            Category::RemoteBranch => b"refs/remotes/".as_bstr(),
18            Category::Note => b"refs/notes/".as_bstr(),
19            Category::MainPseudoRef => b"main-worktree/".as_bstr(),
20            Category::MainRef => b"main-worktree/refs/".as_bstr(),
21            Category::PseudoRef => b"".as_bstr(),
22            Category::LinkedPseudoRef { .. } => b"worktrees/".as_bstr(),
23            Category::LinkedRef { .. } => b"worktrees/".as_bstr(),
24            Category::Bisect => b"refs/bisect/".as_bstr(),
25            Category::Rewritten => b"refs/rewritten/".as_bstr(),
26            Category::WorktreePrivate => b"refs/worktree/".as_bstr(),
27        }
28    }
29
30    /// Returns `true` if the category is private to their worktrees, and never shared with other worktrees.
31    pub fn is_worktree_private(&self) -> bool {
32        matches!(
33            self,
34            Category::MainPseudoRef
35                | Category::PseudoRef
36                | Category::LinkedPseudoRef { .. }
37                | Category::WorktreePrivate
38                | Category::Rewritten
39                | Category::Bisect
40        )
41    }
42
43    /// Returns `true` if this category represents remote-tracking branches, like `refs/remotes/<remote>/<name>`.
44    pub fn is_remote_tracking_branch(&self) -> bool {
45        matches!(self, Category::RemoteBranch)
46    }
47}
48
49impl FullNameRef {
50    pub(crate) fn new_unchecked(v: &BStr) -> &Self {
51        // SAFETY: FullNameRef is transparent and equivalent to a &BStr if provided as reference
52        #[expect(unsafe_code)]
53        unsafe {
54            std::mem::transmute(v)
55        }
56    }
57}
58
59impl PartialNameRef {
60    pub(crate) fn new_unchecked(v: &BStr) -> &Self {
61        // SAFETY: PartialNameRef is transparent and equivalent to a &BStr if provided as reference
62        #[expect(unsafe_code)]
63        unsafe {
64            std::mem::transmute(v)
65        }
66    }
67}
68
69impl PartialNameRef {
70    pub(crate) fn looks_like_full_name(&self, consider_pseudo_ref: bool) -> bool {
71        let name = self.0.as_bstr();
72        name.starts_with_str("refs/")
73            || name.starts_with(Category::MainPseudoRef.prefix())
74            || name.starts_with(Category::LinkedPseudoRef { name: "".into() }.prefix())
75            || (consider_pseudo_ref && is_pseudo_ref(name))
76    }
77    pub(crate) fn construct_full_name_ref<'buf>(
78        &self,
79        inbetween: &str,
80        buf: &'buf mut BString,
81        consider_pseudo_ref: bool,
82    ) -> &'buf FullNameRef {
83        buf.clear();
84        if !self.looks_like_full_name(consider_pseudo_ref) {
85            buf.push_str("refs/");
86        }
87        if !inbetween.is_empty() {
88            buf.push_str(inbetween);
89            buf.push_byte(b'/');
90        }
91        buf.extend_from_slice(&self.0);
92        FullNameRef::new_unchecked(buf.as_bstr())
93    }
94}
95
96impl PartialNameRef {
97    /// Convert this name into the relative path possibly identifying the reference location.
98    /// Note that it may be only a partial path though.
99    pub fn to_partial_path(&self) -> &Path {
100        gix_path::from_byte_slice(self.0.as_bstr())
101    }
102
103    /// Provide the name as binary string which is known to be a valid partial ref name.
104    pub fn as_bstr(&self) -> &BStr {
105        &self.0
106    }
107}
108
109impl PartialName {
110    /// Append the `component` to ourselves and validate the newly created partial path.
111    pub fn join(self, component: &BStr) -> Result<Self, Error> {
112        let mut b = self.0;
113        b.push_byte(b'/');
114        b.extend(component.as_bytes());
115        gix_validate::reference::name_partial(b.as_ref())?;
116        Ok(PartialName(b))
117    }
118}
119
120impl<'a> convert::TryFrom<&'a BStr> for &'a FullNameRef {
121    type Error = Error;
122
123    fn try_from(v: &'a BStr) -> Result<Self, Self::Error> {
124        Ok(FullNameRef::new_unchecked(gix_validate::reference::name(v)?))
125    }
126}
127
128impl<'a> From<&'a FullNameRef> for &'a PartialNameRef {
129    fn from(v: &'a FullNameRef) -> Self {
130        PartialNameRef::new_unchecked(v.0.as_bstr())
131    }
132}
133
134impl<'a> convert::TryFrom<&'a OsStr> for &'a PartialNameRef {
135    type Error = Error;
136
137    fn try_from(v: &'a OsStr) -> Result<Self, Self::Error> {
138        let v = gix_path::os_str_into_bstr(v).map_err(|_| Error::InvalidByte {
139            byte: "<unknown encoding>".into(),
140        })?;
141        Ok(PartialNameRef::new_unchecked(gix_validate::reference::name_partial(
142            v.as_bstr(),
143        )?))
144    }
145}
146
147mod impls {
148    use std::borrow::Borrow;
149
150    use crate::{PartialName, PartialNameRef, bstr::ByteSlice};
151
152    impl Borrow<PartialNameRef> for PartialName {
153        #[inline]
154        fn borrow(&self) -> &PartialNameRef {
155            PartialNameRef::new_unchecked(self.0.as_bstr())
156        }
157    }
158
159    impl AsRef<PartialNameRef> for PartialName {
160        fn as_ref(&self) -> &PartialNameRef {
161            self.borrow()
162        }
163    }
164
165    impl ToOwned for PartialNameRef {
166        type Owned = PartialName;
167
168        fn to_owned(&self) -> Self::Owned {
169            PartialName(self.0.to_owned())
170        }
171    }
172}
173
174impl<'a> convert::TryFrom<&'a BString> for &'a PartialNameRef {
175    type Error = Error;
176
177    fn try_from(v: &'a BString) -> Result<Self, Self::Error> {
178        Ok(PartialNameRef::new_unchecked(gix_validate::reference::name_partial(
179            v.as_ref(),
180        )?))
181    }
182}
183
184impl<'a> convert::TryFrom<&'a BStr> for &'a PartialNameRef {
185    type Error = Error;
186
187    fn try_from(v: &'a BStr) -> Result<Self, Self::Error> {
188        Ok(PartialNameRef::new_unchecked(gix_validate::reference::name_partial(v)?))
189    }
190}
191
192impl<'a> convert::TryFrom<&'a PartialName> for &'a PartialNameRef {
193    type Error = Error;
194
195    fn try_from(v: &'a PartialName) -> Result<Self, Self::Error> {
196        Ok(PartialNameRef::new_unchecked(v.0.as_bstr()))
197    }
198}
199
200impl<'a> convert::TryFrom<&'a str> for &'a FullNameRef {
201    type Error = Error;
202
203    fn try_from(v: &'a str) -> Result<Self, Self::Error> {
204        let v = v.as_bytes().as_bstr();
205        Ok(FullNameRef::new_unchecked(gix_validate::reference::name(v)?))
206    }
207}
208
209impl<'a> convert::TryFrom<&'a str> for &'a PartialNameRef {
210    type Error = Error;
211
212    fn try_from(v: &'a str) -> Result<Self, Self::Error> {
213        let v = v.as_bytes().as_bstr();
214        Ok(PartialNameRef::new_unchecked(gix_validate::reference::name_partial(v)?))
215    }
216}
217
218impl<'a> convert::TryFrom<&'a str> for PartialName {
219    type Error = Error;
220
221    fn try_from(v: &'a str) -> Result<Self, Self::Error> {
222        let v = v.as_bytes().as_bstr();
223        Ok(PartialName(gix_validate::reference::name_partial(v)?.to_owned()))
224    }
225}
226
227#[expect(
228    clippy::infallible_try_from,
229    reason = "it's here so that it can be done, even if infallible. Needed for parameters that use `TryFrom` generically."
230)]
231impl<'a> convert::TryFrom<&'a FullName> for &'a PartialNameRef {
232    type Error = Infallible;
233
234    fn try_from(v: &'a FullName) -> Result<Self, Self::Error> {
235        Ok(v.as_ref().as_partial_name())
236    }
237}
238
239impl<'a> convert::TryFrom<&'a String> for &'a FullNameRef {
240    type Error = Error;
241
242    fn try_from(v: &'a String) -> Result<Self, Self::Error> {
243        let v = v.as_bytes().as_bstr();
244        Ok(FullNameRef::new_unchecked(gix_validate::reference::name(v)?))
245    }
246}
247
248impl<'a> convert::TryFrom<&'a String> for &'a PartialNameRef {
249    type Error = Error;
250
251    fn try_from(v: &'a String) -> Result<Self, Self::Error> {
252        let v = v.as_bytes().as_bstr();
253        Ok(PartialNameRef::new_unchecked(gix_validate::reference::name_partial(v)?))
254    }
255}
256
257impl convert::TryFrom<String> for PartialName {
258    type Error = Error;
259
260    fn try_from(v: String) -> Result<Self, Self::Error> {
261        gix_validate::reference::name_partial(v.as_bytes().as_bstr())?;
262        Ok(PartialName(v.into()))
263    }
264}
265
266impl convert::TryFrom<BString> for PartialName {
267    type Error = Error;
268
269    fn try_from(v: BString) -> Result<Self, Self::Error> {
270        gix_validate::reference::name_partial(v.as_ref())?;
271        Ok(PartialName(v))
272    }
273}
274
275impl std::fmt::Display for PartialName {
276    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
277        std::fmt::Display::fmt(&self.0, f)
278    }
279}
280
281impl std::fmt::Display for PartialNameRef {
282    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
283        std::fmt::Display::fmt(&self.0, f)
284    }
285}
286
287/// Note that this method is disagreeing with `gix_validate` as it allows dashes '-' for some reason.
288/// Since partial names cannot be created with dashes inside we adjusted this as it's probably unintended or git creates pseudo-refs
289/// which wouldn't pass its safety checks.
290pub(crate) fn is_pseudo_ref(name: &BStr) -> bool {
291    name.bytes().all(|b| b.is_ascii_uppercase() || b == b'_')
292}
gix_ref/name.rs

gix_ref/
name.rs
