imrpove git2 mapping by using aliases.

Thanks so much, @epage, it's a game-changer.

Author: Byron

gix/src/lib.rs

@@ -56,19 +56,12 @@
 //!
 //! ### `libgit2` API to `gix`
 //!
-//! This section is a 'striving to be complete' mapping from `libgit2` APIs to the respective methods in `gix`.
+//! This doc-aliases are used to help finding methods under a possibly changed name. Just search in the docs.
+//! Entering `git2` into the search field will also surface all methods with such annotations.
 //!
-//! * [`git2::Repository::open()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.open) ➡ [`open()`]
-//! * [`git2::Repository::open_bare()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.open_bare) ➡ ❌
-//! * [`git2::Repository::open_from_env()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.open_from_env) ➡ [`ThreadSafeRepository::open_with_environment_overrides()`]
-//! * [`git2::Repository::open_ext()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.open_ext) ➡ [`open_opts()`]
-//! * [`git2::Repository::revparse()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.revparse) ➡ [`Repository::rev_parse()`]
-//! * [`git2::Repository::revparse_single()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.revparse_single) ➡ [`Repository::rev_parse_single()`]
-//! * [`git2::Repository::revwalk()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.revwalk) ➡ [`Repository::rev_walk()`]
+//! What follows is a list of methods you might be missing, along with workarounds if available.
+//! * [`git2::Repository::open_bare()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.open_bare) ➡ ❌ - use [`open()`] and discard it is not bare.
 //! * [`git2::build::CheckoutBuilder::disable_filters()](https://docs.rs/git2/*/git2/build/struct.CheckoutBuilder.html#method.disable_filters) ➡ ❌ *(filters are always applied during checkouts)*
-//! * [`git2::Odb::read_header()`](https://docs.rs/git2/*/git2/struct.Odb.html#method.read_header) ➡ [`Repository::find_header()`]
-//! * [`git2::Repository::submodules()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.submodules) ➡ [`Repository::submodules()`]
-//! * [`git2::Repository::submodules()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.submodules) ➡ [`Repository::submodules()`]
 //! * [`git2::Repository::submodule_status()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.submodule_status) ➡ [`Submodule::state()`] - status provides more information and conveniences though, and an actual worktree status isn't performed.
 //!
 //! ## Feature Flags
@@ -234,12 +227,14 @@ fn open_opts_with_git_binary_config() -> open::Options {
 
 /// See [`ThreadSafeRepository::open()`], but returns a [`Repository`] instead.
 #[allow(clippy::result_large_err)]
+#[doc(alias = "git2")]
 pub fn open(directory: impl Into<std::path::PathBuf>) -> Result<Repository, open::Error> {
     ThreadSafeRepository::open(directory).map(Into::into)
 }
 
 /// See [`ThreadSafeRepository::open_opts()`], but returns a [`Repository`] instead.
 #[allow(clippy::result_large_err)]
+#[doc(alias = "open_ext", alias = "git2")]
 pub fn open_opts(directory: impl Into<std::path::PathBuf>, options: open::Options) -> Result<Repository, open::Error> {
     ThreadSafeRepository::open_opts(directory, options).map(Into::into)
 }

gix/src/open/repository.rs

@@ -108,6 +108,7 @@ impl ThreadSafeRepository {
     // TODO: The following vars should end up as overrides of the respective configuration values (see git-config).
     //       GIT_PROXY_SSL_CERT, GIT_PROXY_SSL_KEY, GIT_PROXY_SSL_CERT_PASSWORD_PROTECTED.
     //       GIT_PROXY_SSL_CAINFO, GIT_SSL_CIPHER_LIST, GIT_HTTP_MAX_REQUESTS, GIT_CURL_FTP_NO_EPSV,
+    #[doc(alias = "open_from_env", alias = "git2")]
     pub fn open_with_environment_overrides(
         fallback_directory: impl Into<PathBuf>,
         trust_map: gix_sec::trust::Mapping<Options>,

gix/src/pathspec.rs

@@ -84,6 +84,14 @@ impl<'repo> Pathspec<'repo> {
     /// Return the first [`Match`](search::Match) of `relative_path`, or `None`.
     /// Note that the match might [be excluded](search::Match::is_excluded()).
     /// `is_dir` is true if `relative_path` is a directory.
+    #[doc(
+        alias = "match_diff",
+        alias = "match_tree",
+        alias = "match_index",
+        alias = "match_workdir",
+        alias = "matches_path",
+        alias = "git2"
+    )]
     pub fn pattern_matching_relative_path<'a>(
         &mut self,
         relative_path: impl Into<&'a BStr>,

gix/src/repository/object.rs

@@ -39,6 +39,7 @@ impl crate::Repository {
     /// Obtain information about an object without fully decoding it, or fail if the object doesn't exist.
     ///
     /// Note that despite being cheaper than [`Self::find_object()`], there is still some effort traversing delta-chains.
+    #[doc(alias = "read_header", alias = "git2")]
     pub fn find_header(&self, id: impl Into<ObjectId>) -> Result<gix_odb::find::Header, object::find::existing::Error> {
         let id = id.into();
         if id == gix_hash::ObjectId::empty_tree(self.object_hash()) {

gix/src/repository/pathspec.rs

@@ -11,6 +11,7 @@ impl Repository {
     ///
     /// It will be initialized exactly how it would, and attribute matching will be conducted by reading the worktree first if available.
     /// If that is not desirable, consider calling [`Pathspec::new()`] directly.
+    #[doc(alias = "Pathspec", alias = "git2")]
     pub fn pathspec(
         &self,
         patterns: impl IntoIterator<Item = impl AsRef<BStr>>,

gix/src/repository/revision.rs

@@ -8,6 +8,7 @@ impl crate::Repository {
     ///
     /// - `@` actually stands for `HEAD`, whereas `git` resolves it to the object pointed to by `HEAD` without making the
     ///   `HEAD` ref available for lookups.
+    #[doc(alias = "revparse", alias = "git2")]
     pub fn rev_parse<'a>(&self, spec: impl Into<&'a BStr>) -> Result<revision::Spec<'_>, revision::spec::parse::Error> {
         revision::Spec::from_bstr(
             spec,
@@ -20,6 +21,7 @@ impl crate::Repository {
     }
 
     /// Parse a revision specification and return single object id as represented by this instance.
+    #[doc(alias = "revparse_single", alias = "git2")]
     pub fn rev_parse_single<'repo, 'a>(
         &'repo self,
         spec: impl Into<&'a BStr>,
@@ -33,6 +35,7 @@ impl crate::Repository {
     /// Create the baseline for a revision walk by initializing it with the `tips` to start iterating on.
     ///
     /// It can be configured further before starting the actual walk.
+    #[doc(alias = "revwalk", alias = "git2")]
     pub fn rev_walk(
         &self,
         tips: impl IntoIterator<Item = impl Into<gix_hash::ObjectId>>,

gix/src/repository/submodule.rs

@@ -73,6 +73,7 @@ impl Repository {
     }
 
     /// Return the list of available submodules, or `None` if there is no submodule configuration.
+    #[doc(alias = "git2")]
     pub fn submodules(&self) -> Result<Option<impl Iterator<Item = crate::Submodule<'_>>>, submodule::modules::Error> {
         let modules = match self.modules()? {
             None => return Ok(None),

gix/src/submodule/mod.rs

@@ -226,6 +226,7 @@ impl<'repo> Submodule<'repo> {
     }
 
     /// Query various parts of the submodule and assemble it into state information.
+    #[doc(alias = "status", alias = "git2")]
     pub fn state(&self) -> Result<State, config::path::Error> {
         let maybe_old_path = self.git_dir_try_old_form()?;
         let git_dir = self.git_dir();