-
Notifications
You must be signed in to change notification settings - Fork 426
git2 feature: Custom Odb backends #1180
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Draft
tecc
wants to merge
23
commits into
rust-lang:master
Choose a base branch
from
tecc:feat/custom-odb-backend
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Draft
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Added type definition for struct `libgit2-sys::git_odb_stream`. Previously incorrectly defined as an opaque enum. See git2/odb_backend.h line 196. Added type definition for enum `git_odb_stream_t`. I believe it corresponds to the `mode` field of `git_odb_stream`, but that's just a guess. See git2/odb_backend.h line 182.
Added struct `git_config_backend_entry`. See git2/sys/config.h line 27. Added struct `git_config_iterator`. Previously incorrectly defined as an empty enum. See git2/sys/config.h line 49. Added struct `git_config_backend`. See git2/sys/config.h line 69. Added constant `GIT_CONFIG_BACKEND_VERSION`. See git2/sys/config.h line 103. Added struct `git_config_backend_memory_options`. See git2/sys/config.h line 148. Added constant `GIT_CONFIG_BACKEND_MEMORY_OPTIONS_VERSION`. See git2/sys/config.h line 165. Added function `git_config_add_backend`. See git2/sys/config.h line 140. Added function `git_config_backend_from_string`. See git2/sys/config.h line 181. Added function `git_config_backend_from_values`. See git2/sys/config.h line 197. Added function `git_config_init_backend`. See git2/sys/config.h line 116.
Added struct `git_reference_iterator`. See git2/sys/refdb_backend.h line 35.
`git_commit_nth_gen_ancestor`'s first argument has been changed to `ancestor` from the previous `commit` to bring it closer to the actual definition (git2/commit.h line 282) and because the previous name is also used for the second argument.
`CustomOdbBackend` does not drop the inner `Backend` value, leaving it to libgit2 calling the backend's `free` function. This function cannot be called if the `git_odb_add_backend` call fails. Now, `Odb::add_custom_backend` first creates the inner `Backend` value and only when the value has successfully been passed to libgit2 do we stop managing the memory.
Some methods don't necessarily return just `git_error_code`.
Added more documentation to clarify how to do error handling properly. Clarified the default behaviour of `OdbBackend::exists`.
Added `OdbBackend::write_multipack_index`, corresponding to the `writemidx` function of `git_odb_backend`. Fix reference to `Odb` in `OdbBackend` documentation.
This is mostly to bring it inline with the other modules' code style.
Added `OdbBackend::open_writepack`, for opening streams that write packfiles. Added `OdbWritepack` trait for custom Writepack implementations. Added an associated type `OdbBackend::Writepack: OdbWritepack` that tells git2 what data to include for writepack implementations. Implemented `OdbWritepack` for `Infallible` so that people can opt out of implementing the Writepack trait. The implementation panics when any method is called, though that would be undefined behaviour since it would require `Infallible` to have been instantiated. A lot of types were duplicated in the process of this commit. I want other people's thoughts on how to merge them before I make any changes to their code, so I'll open a draft PR soon.
5fa4485
to
5e4fb91
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR is largely an attempt at making a "safe" API for adding custom ODB backends.
Additions made for this purpose have been concentrated in
src/odb_backend.rs
, with minor modifications tosrc/odb.rs
andsrc/lib.rs
to make it accessible.A disclaimer, however: custom ODB backends lack documentation in libgit2, so most of the code and documentation (of which there is plenty) is based upon what I think the code does; if someone else knows better, feel free to tell me and I'll fix it.
I also haven't verified correctness nor safety, although I suspect the code does not violate all too many of Rust's memory rules.
The code has however been documented as thoroughly as I could be bothered to. It's not guaranteed to be correct, because libgit2 lacks documentation, but it should be largely correct as I cross-referenced with both libgit2 and libgit2sharp's source code and documentation to what extent I could.
Usage
This is largely untested (as of writing), so I may have made mistakes here and there.
YourBackend
).git2::odb_backend::OdbBackend
trait forYourBackend
. The only required method isfn supported_operations(&self) -> SupportedOperations
- we'll come back to it.supported_operations
method, add a flag for each method your backend supports. The appropriate flags are described in each method's documentation.YourBackend
as a backend to anodb: Odb
, useodb.add_custom_backend(your_backend, priority)
.YourBackend
, you can do so with theCustomOdbBackend
handle that was returned in the previous call.TODO
There may also be some TODOs littered throughout the code.
readstream
andwritestream
methodsforeach
methododb_backend::Indexer
toindexer::Indexer
andodb_backend::IndexerProgress
toindexer::Progress
)