Struct Platform

pub struct Platform {
    pub options: Options,
    pub filter: Pipeline,
    pub attr_stack: Stack,
    /* private fields */
}

Available on crate feature blob only.

A utility for performing a diff of two blobs, including flexible conversions, conversion-caching acquisition of diff information. Note that this instance will not call external filters as their output can’t be known programmatically, but it allows to prepare their input if the caller wishes to perform this task.

Optimized for NxM lookups with built-in caching.

Fields

options: Options

Options to alter how diffs should be performed.

filter: Pipeline

A way to convert objects into a diff-able format.

attr_stack: Stack

A way to access .gitattributes

Implementations

impl Platform

pub fn set_resource_by_change( &mut self, change: ChangeRef<'_>, objects: &impl FindObjectOrHeader, ) -> Result<&mut Self, Error>

Set ourselves up to produces blob-diffs from change, so this platform can be used to produce diffs easily. objects are used to fetch object data as needed.

Warning about Memory Consumption

This instance only grows, so one should call crate::blob::Platform::clear_resource_cache occasionally.

impl Platform

Lifecycle

pub fn new( options: Options, filter: Pipeline, filter_mode: Mode, attr_stack: Stack, ) -> Self

Create a new instance with options, and a way to filter data from the object database to data that is diff-able. filter_mode decides how to do that specifically. Use attr_stack to access attributes pertaining worktree filters and diff settings.

impl Platform

Conversions

pub fn set_resource( &mut self, id: ObjectId, mode: EntryKind, rela_path: &BStr, kind: ResourceKind, objects: &impl FindObjectOrHeader, ) -> Result<(), Error>

Store enough information about a resource to eventually diff it, where…

• id is the hash of the resource. If it is null, it should either be a resource in the worktree, or it’s considered a non-existing, deleted object. If an id is known, as the hash of the object as (would) be stored in git, then it should be provided for completeness.
• mode is the kind of object (only blobs and links are allowed)
• rela_path is the relative path as seen from the (work)tree root.
• kind identifies the side of the diff this resource will be used for. A diff needs both OldOrSource and NewOrDestination.
• objects provides access to the object database in case the resource can’t be read from a worktree.

Note that it’s assumed that either id + mode ( or rela_path can serve as unique identifier for the resource, depending on whether or not a worktree root is set for the resource of kind, with resources with worktree roots using the rela_path as unique identifier.

Important

If an error occurs, the previous resource of kind will be cleared, preventing further diffs unless another attempt succeeds.

pub fn prepare_diff_command( &self, diff_command: BString, context: Context, count: usize, total: usize, ) -> Result<Command, Error>

Given diff_command and context, typically obtained from git-configuration, and the currently set diff-resources, prepare the invocation and temporary files needed to launch it according to protocol. count / total are used for progress indication passed as environment variables GIT_DIFF_PATH_(COUNTER|TOTAL) respectively (0-based), so the first path has count=0 and total=1 (assuming there is only one path). Returns None if at least one resource is unset, see set_resource().

Please note that this is an expensive operation this will always create up to two temporary files to hold the data for the old and new resources.

Deviation

If one of the resources is binary, the operation reports an error as such resources don’t make their data available which is required for the external diff to run.

pub fn resource(&self, kind: ResourceKind) -> Option<Resource<'_>>

Returns the resource of the given kind if it was set.

pub fn resources(&self) -> Option<(Resource<'_>, Resource<'_>)>

Obtain the two resources that were previously set as (OldOrSource, NewOrDestination), if both are set and available.

This is useful if one wishes to manually prepare the diff, maybe for invoking external programs, instead of relying on Self::prepare_diff().

pub fn prepare_diff(&mut self) -> Result<Outcome<'_>, Error>

Prepare a diff operation on the previously set old and new resources.

The returned outcome allows to easily perform diff operations, based on the prepare_diff::Outcome::operation field, which hints at what should be done.

pub fn clear_resource_cache(&mut self)

Every call to set_resource() will keep the diffable data in memory, and that will never be cleared.

Use this method to clear the cache, releasing memory. Note that this will also lose all information about resources which means diffs would fail unless the resources are set again.

Note that this also has to be called if the same resource is going to be diffed in different states, i.e. using different ids, but the same rela_path.

pub fn clear_resource_cache_keep_allocation(&mut self) -> usize

Every call to set_resource() will keep the diffable data in memory, and that will never be cleared.

Use this method to clear the cache, but keep the previously used buffers around for later re-use.

If there are more buffers on the free-list than there are stored sources, we half that amount each time this method is called, or keep as many resources as were previously stored, or 2 buffers, whatever is larger. If there are fewer buffers in the free-list than are in the resource cache, we will keep as many as needed to match the number of previously stored resources.

Returns the number of available buffers.

Trait Implementations

impl Clone for Platform

fn clone(&self) -> Platform

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.