[ref #175] follow (try_)find(_what) naming convention

Note that the find::existing::Error remains as used in 'find()' as it
is it is more descriptive.

Author: Byron

experiments/diffing/src/main.rs

@@ -32,7 +32,7 @@ fn main() -> anyhow::Result<()> {
     let packed = repo.refs.packed_buffer()?;
     let commit_id = repo
         .refs
-        .find_existing(&name, packed.as_ref())?
+        .find(&name, packed.as_ref())?
         .peel_to_id_in_place(&repo.refs, packed.as_ref(), peel::none)?
         .to_owned();
     let db = &repo.odb;

experiments/traversal/src/main.rs

@@ -28,7 +28,7 @@ fn main() -> anyhow::Result<()> {
         let packed = repo.refs.packed_buffer()?;
         let commit_id = repo
             .refs
-            .find_existing(&name, packed.as_ref())?
+            .find(&name, packed.as_ref())?
             .peel_to_id_in_place(&repo.refs, packed.as_ref(), peel::none)?
             .to_owned();
         (repo, commit_id)

git-ref/src/store/file/find.rs

@@ -34,7 +34,7 @@ impl file::Store {
     /// The lookup algorithm follows the one in [the git documentation][git-lookup-docs].
     ///
     /// [git-lookup-docs]: https://github.com/git/git/blob/5d5b1473453400224ebb126bf3947e0a3276bdf5/Documentation/revisions.txt#L34-L46
-    pub fn find<'a, 'p, 's, Name, E>(
+    pub fn try_find<'a, 'p, 's, Name, E>(
         &'s self,
         partial: Name,
         packed: Option<&'p packed::Buffer>,
@@ -48,12 +48,16 @@ impl file::Store {
     }
 
     /// Similar to [`file::Store::find()`] but a non-existing ref is treated as error.
-    pub fn loose_find<'a, Name, E>(&self, partial: Name) -> Result<Option<loose::Reference>, Error>
+    ///
+    /// Find only loose references, that is references that aren't in the packed-refs buffer.
+    /// All symbolic references are loose references.
+    /// `HEAD` is always a loose reference.
+    pub fn try_find_loose<'a, Name, E>(&self, partial: Name) -> Result<Option<loose::Reference>, Error>
     where
         Name: TryInto<PartialNameRef<'a>, Error = E>,
         Error: From<E>,
     {
-        self.find(partial, None)
+        self.try_find(partial, None)
             .map(|r| r.map(|r| r.try_into().expect("only loose refs are found without pack")))
     }
 
@@ -116,7 +120,7 @@ impl file::Store {
                     if let Some(packed) = packed {
                         let full_name = path_to_name(relative_path);
                         let full_name = PartialNameRef((*full_name).as_bstr());
-                        if let Some(packed_ref) = packed.find(full_name)? {
+                        if let Some(packed_ref) = packed.try_find(full_name)? {
                             return Ok(Some(file::Reference::Packed(packed_ref)));
                         };
                     }
@@ -176,8 +180,8 @@ pub mod existing {
     };
 
     impl file::Store {
-        /// Similar to [`file::Store::find_existing()`] but a non-existing ref is treated as error.
-        pub fn find_existing<'a, 'p, 's, Name, E>(
+        /// Similar to [`file::Store::find()`] but a non-existing ref is treated as error.
+        pub fn find<'a, 'p, 's, Name, E>(
             &'s self,
             partial: Name,
             packed: Option<&'p packed::Buffer>,
@@ -197,12 +201,12 @@ pub mod existing {
         }
 
         /// Similar to [`file::Store::find()`] won't handle packed-refs.
-        pub fn loose_find_existing<'a, Name, E>(&self, partial: Name) -> Result<loose::Reference, Error>
+        pub fn find_loose<'a, Name, E>(&self, partial: Name) -> Result<loose::Reference, Error>
         where
             Name: TryInto<PartialNameRef<'a>, Error = E>,
             crate::name::Error: From<E>,
         {
-            self.find_existing(partial, None)
+            self.find(partial, None)
                 .map(|r| r.try_into().expect("always loose without packed"))
         }
     }

git-ref/src/store/file/reference.rs

@@ -81,7 +81,7 @@ impl<'p> Reference<'p> {
         match self {
             Reference::Loose(r) => r.follow_symbolic(store, packed),
             Reference::Packed(p) => packed
-                .and_then(|packed| packed.find(p.name).ok().flatten()) // needed to get data with 'p2 lifetime
+                .and_then(|packed| packed.try_find(p.name).ok().flatten()) // needed to get data with 'p2 lifetime
                 .and_then(|np| {
                     p.object.and(np.object).map(|peeled| {
                         Ok(Reference::Packed(packed::Reference {

git-ref/src/store/file/transaction/prepare.rs

@@ -44,7 +44,7 @@ impl<'s> Transaction<'s> {
             })
             .and_then(|maybe_loose| match (maybe_loose, packed) {
                 (None, Some(packed)) => packed
-                    .find(change.update.name.to_ref())
+                    .try_find(change.update.name.to_ref())
                     .map(|opt| opt.map(file::Reference::Packed))
                     .map_err(Error::from),
                 (None, None) => Ok(None),
@@ -191,7 +191,7 @@ impl<'s> Transaction<'s> {
                 |name| {
                     let symbolic_refs_are_never_packed = None;
                     store
-                        .find_existing(name, symbolic_refs_are_never_packed)
+                        .find(name, symbolic_refs_are_never_packed)
                         .map(|r| r.into_target())
                         .ok()
                 },

git-ref/src/store/packed/find.rs

@@ -7,7 +7,7 @@ use crate::{store::packed, PartialNameRef};
 /// packed-refs specific functionality
 impl packed::Buffer {
     /// Find a reference with the given `name` and return it.
-    pub fn find<'a, Name, E>(&self, name: Name) -> Result<Option<packed::Reference<'_>>, Error>
+    pub fn try_find<'a, Name, E>(&self, name: Name) -> Result<Option<packed::Reference<'_>>, Error>
     where
         Name: TryInto<PartialNameRef<'a>, Error = E>,
         Error: From<E>,
@@ -52,12 +52,12 @@ impl packed::Buffer {
     }
 
     /// Find a reference with the given `name` and return it.
-    pub fn find_existing<'a, Name, E>(&self, name: Name) -> Result<packed::Reference<'_>, existing::Error>
+    pub fn find<'a, Name, E>(&self, name: Name) -> Result<packed::Reference<'_>, existing::Error>
     where
         Name: TryInto<PartialNameRef<'a>, Error = E>,
         Error: From<E>,
     {
-        match self.find(name) {
+        match self.try_find(name) {
             Ok(Some(r)) => Ok(r),
             Ok(None) => Err(existing::Error::NotFound),
             Err(err) => Err(existing::Error::Find(err)),

git-ref/src/store/packed/transaction.rs

@@ -54,9 +54,7 @@ impl packed::Transaction {
             .into_iter()
             .filter(|edit| {
                 if let Change::Delete { .. } = edit.change {
-                    buffer
-                        .as_ref()
-                        .map_or(true, |b| b.find_existing(edit.name.to_ref()).is_ok())
+                    buffer.as_ref().map_or(true, |b| b.find(edit.name.to_ref()).is_ok())
                 } else {
                     true
                 }

git-ref/tests/file/reference.rs

@@ -6,7 +6,7 @@ mod reflog {
         fn iter() -> crate::Result {
             let store = file::store_with_packed_refs()?;
             let packed = store.packed_buffer()?;
-            let r = store.find_existing("main", packed.as_ref())?;
+            let r = store.find("main", packed.as_ref())?;
             let mut buf = Vec::new();
             assert_eq!(r.log_iter(&store, &mut buf)?.expect("log exists").count(), 1);
             assert!(r.log_exists(&store), "it exists if its readable");
@@ -17,7 +17,7 @@ mod reflog {
         fn iter_rev() -> crate::Result {
             let store = file::store_with_packed_refs()?;
             let packed = store.packed_buffer()?;
-            let r = store.find_existing("main", packed.as_ref())?;
+            let r = store.find("main", packed.as_ref())?;
             let mut buf = [0u8; 256];
             assert_eq!(r.log_iter_rev(&store, &mut buf)?.expect("log exists").count(), 1);
             Ok(())
@@ -30,7 +30,7 @@ mod reflog {
         #[test]
         fn iter() -> crate::Result {
             let store = file::store()?;
-            let r = store.loose_find_existing("HEAD")?;
+            let r = store.find_loose("HEAD")?;
             let mut buf = Vec::new();
             assert_eq!(r.log_iter(&store, &mut buf)?.expect("log exists").count(), 1);
             assert!(r.log_exists(&store), "it exists if its readable");
@@ -40,7 +40,7 @@ mod reflog {
         #[test]
         fn iter_rev() -> crate::Result {
             let store = file::store()?;
-            let r = store.loose_find_existing("HEAD")?;
+            let r = store.find_loose("HEAD")?;
             let mut buf = [0u8; 256];
             assert_eq!(r.log_iter_rev(&store, &mut buf)?.expect("log exists").count(), 1);
             Ok(())
@@ -60,7 +60,7 @@ mod peel {
     #[test]
     fn one_level() -> crate::Result {
         let store = file::store()?;
-        let r = store.loose_find_existing("HEAD")?;
+        let r = store.find_loose("HEAD")?;
         assert_eq!(r.kind(), git_ref::Kind::Symbolic, "there is something to peel");
 
         let nr = git_ref::file::loose::Reference::try_from(
@@ -83,13 +83,13 @@ mod peel {
     #[test]
     fn peel_with_packed_involvement() -> crate::Result {
         let store = store_with_packed_refs()?;
-        let mut head = store.loose_find_existing("HEAD")?;
+        let mut head = store.find_loose("HEAD")?;
         let packed = store.packed_buffer()?;
         let expected = hex_to_id("134385f6d781b7e97062102c6a483440bfda2a03");
         assert_eq!(head.peel_to_id_in_place(&store, packed.as_ref(), peel::none)?, expected);
         assert_eq!(head.target.as_id().map(ToOwned::to_owned), Some(expected));
 
-        let mut head = store.find_existing("dt1", packed.as_ref())?;
+        let mut head = store.find("dt1", packed.as_ref())?;
         assert_eq!(head.peel_to_id_in_place(&store, packed.as_ref(), peel::none)?, expected);
         assert_eq!(head.target().as_id().map(ToOwned::to_owned), Some(expected));
         Ok(())
@@ -100,7 +100,7 @@ mod peel {
         let store = store_with_packed_refs()?;
         let packed = store.packed_buffer()?;
 
-        let head = store.find_existing("dt1", packed.as_ref())?;
+        let head = store.find("dt1", packed.as_ref())?;
         assert!(head.is_packed());
         assert_eq!(
             head.target().as_id().map(ToOwned::to_owned),
@@ -128,14 +128,14 @@ mod peel {
     #[test]
     fn to_id_multi_hop() -> crate::Result {
         let store = file::store()?;
-        let mut r = store.loose_find_existing("multi-link")?;
+        let mut r = store.find_loose("multi-link")?;
         assert_eq!(r.kind(), git_ref::Kind::Symbolic, "there is something to peel");
 
         let commit = hex_to_id("134385f6d781b7e97062102c6a483440bfda2a03");
         assert_eq!(r.peel_to_id_in_place(&store, None, peel::none)?, commit);
         assert_eq!(r.name.as_bstr(), "refs/remotes/origin/multi-link-target3");
 
-        let mut r = store.loose_find_existing("dt1")?;
+        let mut r = store.find_loose("dt1")?;
         assert_eq!(
             r.peel_to_id_in_place(&store, None, peel::none)?,
             hex_to_id("4c3f4cce493d7beb45012e478021b5f65295e5a3"),
@@ -158,7 +158,7 @@ mod peel {
     #[test]
     fn to_id_cycle() -> crate::Result {
         let store = file::store()?;
-        let mut r = store.loose_find_existing("loop-a")?;
+        let mut r = store.find_loose("loop-a")?;
         assert_eq!(r.kind(), git_ref::Kind::Symbolic, "there is something to peel");
         assert_eq!(r.name.as_bstr(), "refs/loop-a");
 

git-ref/tests/file/store/find.rs

@@ -8,7 +8,7 @@ mod existing {
         let store = store_at("make_packed_ref_repository_for_overlay.sh")?;
         let c1 = hex_to_id("134385f6d781b7e97062102c6a483440bfda2a03");
         let packed = store.packed_buffer()?;
-        let r = store.find_existing("main", packed.as_ref())?;
+        let r = store.find("main", packed.as_ref())?;
         assert_eq!(r.target().to_ref().as_id().expect("peeled"), c1);
         assert_eq!(r.name().as_bstr(), "refs/heads/main");
         Ok(())
@@ -27,7 +27,7 @@ mod loose {
         fn success_and_failure() -> crate::Result {
             let store = store()?;
             for (partial_name, expected_path) in &[("main", Some("refs/heads/main")), ("does-not-exist", None)] {
-                let reference = store.loose_find_existing(*partial_name);
+                let reference = store.find_loose(*partial_name);
                 match expected_path {
                     Some(expected_path) => assert_eq!(reference?.name.as_bstr(), expected_path),
                     None => match reference {
@@ -60,7 +60,7 @@ mod loose {
             ("heads/main", "refs/heads/main", git_ref::Kind::Peeled),
             ("refs/heads/main", "refs/heads/main", git_ref::Kind::Peeled),
         ] {
-            let reference = store.loose_find(*partial_name)?.expect("exists");
+            let reference = store.try_find_loose(*partial_name)?.expect("exists");
             assert_eq!(reference.name.as_bstr(), expected_path);
             assert_eq!(reference.target.to_ref().kind(), *expected_ref_kind);
         }
@@ -75,7 +75,7 @@ mod loose {
             ("broken", "does not parse", true),
             ("../escaping", "an invalid ref name", true),
         ] {
-            let reference = store.loose_find(*partial_name);
+            let reference = store.try_find_loose(*partial_name);
             if *is_err {
                 assert!(reference.is_err(), "{}", reason);
             } else {