gix-ref 0.68.0

A crate to handle git references
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

use gix_error::{ErrorExt, ExnResult, Message, ResultExt, message};

use gix_object::bstr::{BStr, BString};

use crate::{FullNameRef, PartialNameRef, store_impl::packed};

/// packed-refs specific functionality
impl packed::Buffer {
    /// Find a reference with the given `name` and return it.
    ///
    /// Note that it will look it up verbatim and does not deal with namespaces or special prefixes like
    /// `main-worktree/` or `worktrees/<name>/`, as this is left to the caller.
    pub fn try_find<'a, Name, E>(&self, name: Name) -> ExnResult<Option<packed::Reference<'_>>>
    where
        Name: TryInto<&'a PartialNameRef, Error = E>,
        Result<&'a PartialNameRef, E>: ResultExt<Success = &'a PartialNameRef>,
    {
        let name = name
            .try_into()
            .or_raise_erased(|| message("The ref name or path is not a valid ref name"))?;
        let mut buf = BString::default();
        for inbetween in &["", "tags", "heads", "remotes"] {
            let (name, was_absolute) = if name.looks_like_full_name(false) {
                let name = FullNameRef::new_unchecked(name.as_bstr());
                let name = match transform_full_name_for_lookup(name) {
                    None => return Ok(None),
                    Some(name) => name,
                };
                (name, true)
            } else {
                let full_name = name.construct_full_name_ref(inbetween, &mut buf, false);
                (full_name, false)
            };
            match self.try_find_full_name(name)? {
                Some(r) => return Ok(Some(r)),
                None if was_absolute => return Ok(None),
                None => continue,
            }
        }
        Ok(None)
    }

    /// Look up a resolved name. Decode failures include [metadata](gix_error::Exn::metadata()) `name` (bytes), the
    /// requested full name.
    pub(crate) fn try_find_full_name(&self, name: &FullNameRef) -> ExnResult<Option<packed::Reference<'_>>> {
        match self.binary_search_by(name.as_bstr()) {
            Ok(line_start) => {
                let mut input = &self.as_ref()[line_start..];
                packed::decode::reference(&mut input, self.object_hash).map(Some)
            }
            Err((parse_failure, _)) => {
                if parse_failure {
                    Err(gix_error::corruption("Malformed packed reference record").raise())
                } else {
                    Ok(None)
                }
            }
        }
        .or_raise_erased(|| Message::new("Could not decode packed reference").with("name", name.as_bstr()))
    }

    /// Find a reference with the given `name` and return it.
    pub fn find<'a, Name, E>(&self, name: Name) -> ExnResult<packed::Reference<'_>>
    where
        Name: TryInto<&'a PartialNameRef, Error = E>,
        Result<&'a PartialNameRef, E>: ResultExt<Success = &'a PartialNameRef>,
    {
        let name = name
            .try_into()
            .or_raise_erased(|| message("The ref name or path is not a valid ref name"))?;
        self.try_find::<_, std::convert::Infallible>(name)?.ok_or_else(|| {
            crate::file::find::NotFound {
                name: name.to_partial_path().to_owned(),
            }
            .raise_erased()
        })
    }

    /// Perform a binary search where `Ok(pos)` is the beginning of the line that matches `name` perfectly and `Err(pos)`
    /// is the beginning of the line at which `name` could be inserted to still be in sort order.
    pub(in crate::store_impl::packed) fn binary_search_by(&self, full_name: &BStr) -> Result<usize, (bool, usize)> {
        let a = self.as_ref();
        let mut encountered_parse_failure = false;
        a.binary_search_by_key(&full_name.as_ref(), |b: &u8| {
            let ofs = std::ptr::from_ref::<u8>(b) as usize - a.as_ptr() as usize;
            let line = packed::decode::record_at_offset(a, ofs);
            // The binary search only needs the name bytes for ordered
            // comparison; skip ref-name and hex-hash validation here and let
            // the final match site re-parse the record via `decode::reference`
            // (which validates fully). This saves the `logâ‚‚(n)` per-query.
            match packed::decode::name_at_record_start(line, self.object_hash) {
                Some(name) => name,
                None => {
                    encountered_parse_failure = true;
                    &[]
                }
            }
        })
        .map(|pos| packed::decode::record_start_at_offset(a, pos))
        .map_err(|pos| {
            (
                encountered_parse_failure,
                packed::decode::record_start_at_offset(a, pos),
            )
        })
    }
}

pub(crate) fn transform_full_name_for_lookup(name: &FullNameRef) -> Option<&FullNameRef> {
    match name.category_and_short_name() {
        Some((c, sn)) => {
            use crate::Category::*;
            Some(match c {
                MainRef | LinkedRef { .. } => FullNameRef::new_unchecked(sn),
                Tag | RemoteBranch | LocalBranch | Bisect | Rewritten | Note => name,
                MainPseudoRef | PseudoRef | LinkedPseudoRef { .. } | WorktreePrivate => return None,
            })
        }
        None => Some(name),
    }
}