Struct gix::remote::fetch::Prepare

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

Available on (crate features async-network-client or blocking-network-client) and (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<'remote, 'repo, T> Prepare<'remote, 'repo, T>where T: Transport,

pub fn receive<P>( self, progress: P, should_interrupt: &AtomicBool ) -> Result<Outcome, Error>where P: NestedProgress, P::SubProgress: 'static,

Receive the pack and perform the operation as configured by git via git-config or overridden by various builder methods. Return Ok(None) if there was nothing to do because all remote refs are at the same state as they are locally, or Ok(Some(outcome)) to inform about all the changes that were made.

Negotiation

“fetch.negotiationAlgorithm” describes algorithms git uses currently, with the default being consecutive and skipping being experimented with. We currently implement something we could call ‘naive’ which works for now.

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 that 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 user 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<'remote, 'repo, T> Prepare<'remote, 'repo, T>where T: Transport,

pub fn ref_map(&self) -> &RefMap

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

impl<'remote, 'repo, T> Prepare<'remote, 'repo, T>where T: Transport,

Builder

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

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

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

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

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

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

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

Trait Implementations

impl<'remote, 'repo, T> Drop for Prepare<'remote, 'repo, T>where T: Transport,

fn drop(&mut self)

Executes the destructor for this type.