imrpove git2 mapping by using aliases.

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

Sebastian Thiel committed 3 years ago

Commit 6194ebe1 parent 12699d78 files · +22 −11Browse files

Unified · Split

8 files

gix/src/lib.rs +6 −11
gix/src/open/repository.rs +1 −0
gix/src/pathspec.rs +8 −0
gix/src/repository/object.rs +1 −0
gix/src/repository/pathspec.rs +1 −0
gix/src/repository/revision.rs +3 −0
gix/src/repository/submodule.rs +1 −0
gix/src/submodule/mod.rs +1 −0

@@ -56,19 +56,12 @@ · 55 unmodified lines
56	56	//!
57	57	//! ### `libgit2` API to `gix`
58	58	//!
59		−//! This section is a 'striving to be complete' mapping from `libgit2` APIs to the respective methods in `gix`.
	59	+//! This doc-aliases are used to help finding methods under a possibly changed name. Just search in the docs.
	60	+//! Entering `git2` into the search field will also surface all methods with such annotations.
60	61	//!
61		−//! * [`git2::Repository::open()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.open) ➡ [`open()`]
62		−//! * [`git2::Repository::open_bare()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.open_bare) ➡ ❌
63		−//! * [`git2::Repository::open_from_env()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.open_from_env) ➡ [`ThreadSafeRepository::open_with_environment_overrides()`]
64		−//! * [`git2::Repository::open_ext()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.open_ext) ➡ [`open_opts()`]
65		−//! * [`git2::Repository::revparse()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.revparse) ➡ [`Repository::rev_parse()`]
66		−//! * [`git2::Repository::revparse_single()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.revparse_single) ➡ [`Repository::rev_parse_single()`]
67		−//! * [`git2::Repository::revwalk()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.revwalk) ➡ [`Repository::rev_walk()`]
	62	+//! What follows is a list of methods you might be missing, along with workarounds if available.
	63	+//! * [`git2::Repository::open_bare()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.open_bare) ➡ ❌ - use [`open()`] and discard it is not bare.
68	64	//! * [`git2::build::CheckoutBuilder::disable_filters()](https://docs.rs/git2//git2/build/struct.CheckoutBuilder.html#method.disable_filters) ➡ ❌ (filters are always applied during checkouts)*
69		−//! * [`git2::Odb::read_header()`](https://docs.rs/git2/*/git2/struct.Odb.html#method.read_header) ➡ [`Repository::find_header()`]
70		−//! * [`git2::Repository::submodules()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.submodules) ➡ [`Repository::submodules()`]
71		−//! * [`git2::Repository::submodules()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.submodules) ➡ [`Repository::submodules()`]
72	65	//! * [`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.
73	66	//!
74	67	//! ## Feature Flags
@@ -234,12 +227,14 @@ fn open_opts_with_git_binary_config() -> open::Options { · 159 unmodified lines
234	227
235	228	/// See [`ThreadSafeRepository::open()`], but returns a [`Repository`] instead.
236	229	#[allow(clippy::result_large_err)]
	230	+#[doc(alias = "git2")]
237	231	pub fn open(directory: impl Into<std::path::PathBuf>) -> Result<Repository, open::Error> {
238	232	ThreadSafeRepository::open(directory).map(Into::into)
239	233	}
240	234
241	235	/// See [`ThreadSafeRepository::open_opts()`], but returns a [`Repository`] instead.
242	236	#[allow(clippy::result_large_err)]
	237	+#[doc(alias = "open_ext", alias = "git2")]
243	238	pub fn open_opts(directory: impl Into<std::path::PathBuf>, options: open::Options) -> Result<Repository, open::Error> {
244	239	ThreadSafeRepository::open_opts(directory, options).map(Into::into)
245	240	}

gix/src/open/repository.rs+1−0

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

gix/src/pathspec.rs+8−0

@@ -84,6 +84,14 @@ impl<'repo> Pathspec<'repo> { · 83 unmodified lines
84	84	/// Return the first [`Match`](search::Match) of `relative_path`, or `None`.
85	85	/// Note that the match might [be excluded](search::Match::is_excluded()).
86	86	/// `is_dir` is true if `relative_path` is a directory.
	87	+ #[doc(
	88	+ alias = "match_diff",
	89	+ alias = "match_tree",
	90	+ alias = "match_index",
	91	+ alias = "match_workdir",
	92	+ alias = "matches_path",
	93	+ alias = "git2"
	94	+ )]
87	95	pub fn pattern_matching_relative_path<'a>(
88	96	&mut self,
89	97	relative_path: impl Into<&'a BStr>,

gix/src/repository/object.rs+1−0

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

gix/src/repository/pathspec.rs+1−0

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

gix/src/repository/revision.rs+3−0

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

gix/src/repository/submodule.rs+1−0

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

gix/src/submodule/mod.rs+1−0

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