Struct Prepare 

pub struct Prepare<'remote, 'repo, T>
where
    T: Transport,
{ /* private fields */ }

Available on crate features blocking-network-client or async-network-client only.

A structure to hold the result of the handshake with the remote and configure the upcoming fetch operation.

Implementations

impl<T> Prepare<'_, '_, T>

where T: Transport,

pub fn receive<P>( self, progress: P, should_interrupt: &AtomicBool, ) -> Result<Outcome, Error>

where P: NestedProgress, P::SubProgress: 'static,

Available on crate features async-network-client or blocking-network-client only.

Receive the pack and perform the operation as configured by git via git-config or overridden by various builder methods. Return Ok(Outcome) with an Outcome::status indicating if a change was made or not.

Note that when in dry-run mode, we don’t read the pack the server prepared, which leads the server to be hung up on unexpectedly.

Negotiation

“fetch.negotiationAlgorithm” describes algorithms git uses currently, with the default being consecutive and skipping being experimented with.

Pack .keep files

That packs that are freshly written to the object database are vulnerable to garbage collection for the brief time that it takes between them being placed and the respective references to be written to disk which binds their objects to the commit graph, making them reachable.

To circumvent this issue, a .keep file is created before any pack related file (i.e. .pack or .idx) is written, which indicates the garbage collector (like git maintenance, git gc) to leave the corresponding pack file alone.

If there were any ref updates or the received pack was empty, the .keep file will be deleted automatically leaving in its place at write_pack_bundle.keep_path a None. However, if no ref-update happened the path will still be present in write_pack_bundle.keep_path and is expected to be handled by the caller. A known application for this behaviour is in remote-helper implementations which should send this path via lock <path> to stdout to inform git about the file that it will remove once it updated the refs accordingly.

Deviation

When updating refs, the git-fetch docs state the following:

Unlike when pushing with git-push, any updates outside of refs/{tags,heads}/* will be accepted without + in the refspec (or –force), whether that’s swapping e.g. a tree object for a blob, or a commit for another commit that’s doesn’t have the previous commit as an ancestor etc.

We explicitly don’t special case those refs and expect the caller to take control. Note that by its nature, force only applies to refs pointing to commits and if they don’t, they will be updated either way in our implementation as well.

Async Mode Shortcoming

Currently, the entire process of resolving a pack is blocking the executor. This can be fixed using the blocking crate, but it didn’t seem worth the tradeoff of having more complex code.

Configuration

• gitoxide.userAgent is read to obtain the application user agent for git servers and for HTTP servers as well.

impl<T> Prepare<'_, '_, T>

where T: Transport,

pub fn ref_map(&self) -> &RefMap

Available on crate features async-network-client or blocking-network-client only.

Return the ref_map (that includes the server handshake) which was part of listing refs prior to fetching a pack.

impl<T> Prepare<'_, '_, T>

where T: Transport,

Builder

pub fn with_dry_run(self, enabled: bool) -> Self

Available on crate features async-network-client or blocking-network-client only.

If dry run is enabled, no change to the repository will be made.

This works by not actually fetching the pack after negotiating it, nor will refs be updated.

pub fn with_write_packed_refs_only(self, enabled: bool) -> Self

Available on crate features async-network-client or blocking-network-client only.

If enabled, don’t write ref updates to loose refs, but put them exclusively to packed-refs.

This improves performance and allows case-sensitive filesystems to deal with ref names that would otherwise collide.

pub fn with_reflog_message(self, reflog_message: RefLogMessage) -> Self

Available on crate features async-network-client or blocking-network-client only.

Set the reflog message to use when updating refs after fetching a pack.

pub fn with_shallow(self, shallow: Shallow) -> Self

Available on crate features async-network-client or blocking-network-client only.

Define what to do when the current repository is a shallow clone.

Has no effect if the current repository is not as shallow clone.