Struct PlatformRef

pub struct PlatformRef<'parent> {
    pub current: ResourceRef<'parent>,
    pub ancestor: ResourceRef<'parent>,
    pub other: ResourceRef<'parent>,
    pub driver: DriverChoice,
    pub options: Options,
    /* private fields */
}

The product of a prepare_merge() call to finally perform the merge and retrieve the merge results.

Fields

current: ResourceRef<'parent>

The current or our side of the merge operation.

ancestor: ResourceRef<'parent>

The ancestor or base of the merge operation.

other: ResourceRef<'parent>

The other or their side of the merge operation.

driver: DriverChoice

Which driver to use according to the resource’s configuration, using the path of current to read git-attributes.

options: Options

Possibly processed options for use when performing the actual merge.

They may be inspected before the merge, or altered at will.

Implementations

impl<'parent> PlatformRef<'parent>

Plumbing

pub fn prepare_external_driver( &self, merge_command: BString, _: Labels<'_>, context: Context, ) -> Result<Command, Error>

Given merge_command and context, typically obtained from git-configuration, and the currently set merge-resources, prepare the invocation and temporary files needed to launch it according to protocol. See the documentation of Driver::command for possible substitutions.

Please note that this is an expensive operation this will always create three temporary files to hold all sides of the merge.

The resulting command should be spawned, and when successful, the result file can be opened to read back the result into a suitable buffer.

Deviation

• We allow passing more context than Git would by taking a whole context, it’s up to the caller to decide how much is filled.
• Our tempfiles aren’t suffixed .merge_file_XXXXXX with X replaced with characters for uniqueness.

pub fn configured_driver(&self) -> Result<&'parent Driver, BuiltinDriver>

Return the configured driver program for use with Self::prepare_external_driver(), or Err with the built-in driver to use instead.

impl<'parent> PlatformRef<'parent>

Plumbing

pub fn builtin_merge( &self, driver: BuiltinDriver, out: &mut Vec<u8>, input: &mut InternedInput<&'parent [u8]>, labels: Labels<'_>, ) -> (Pick, Resolution)

Perform the merge using the given driver, possibly placing the output in out. input can be used to keep tokens between runs, but note it will only grow in size unless cleared manually. Use labels to annotate conflict sections in case of a text-merge. Returns None if one of the buffers is too large, making a merge impossible. Note that if the pick wasn’t Pick::Buffer, then out will not have been cleared, and one has to take the data from the respective resource.

If there is no buffer loaded as the resource is too big, we will automatically perform a binary merge which effectively chooses our side by default.

impl<'parent> PlatformRef<'parent>

Convenience

pub fn merge( &self, out: &mut Vec<u8>, labels: Labels<'_>, context: &Context, ) -> Result<(Pick, Resolution), Error>

Perform the merge, possibly invoking an external merge command, and store the result in out, returning (pick, resolution). Note that pick indicates which resource the buffer should be taken from, unless it’s Pick::Buffer to indicate it’s out. Use labels to annotate conflict sections in case of a text-merge. The merge is configured by opts and possible merge driver command executions are affected by context.

Note that at this stage, none-existing input data will simply default to an empty buffer when running the actual merge algorithm. Too-large resources will result in an error.

Generally, it is assumed that standard logic, like deletions of files, is handled before any of this is called, so we are lenient in terms of buffer handling to make it more useful in the face of missing local files.

pub fn buffer_by_pick(&self, pick: Pick) -> Result<Option<&'parent [u8]>, ()>

Using a pick obtained from merge(), obtain the respective buffer suitable for reading or copying. Return Ok(None) if the pick corresponds to a buffer (that was written separately). Return Err(()) if the buffer is too large, so it was never read.

pub fn id_by_pick<E>( &self, pick: Pick, buf: &[u8], write_blob: impl FnMut(&[u8]) -> Result<ObjectId, E>, ) -> Result<Option<ObjectId>, E>

Use pick to return the object id of the merged result, assuming that buf was passed as out to merge(). In case of binary or large files, this will simply be the existing ID of the resource. In case of resources available in the object DB for binary merges, the object ID will be returned. If new content was produced due to a content merge, buf will be written out to the object database using write_blob. Beware that the returned ID could be Ok(None) if the underlying resource was loaded from the worktree and was too large so it was never loaded from disk. Ok(None) will also be returned if one of the resources was missing. write_blob() is used to turn buffers.

Trait Implementations

impl<'parent> Clone for PlatformRef<'parent>

fn clone(&self) -> PlatformRef<'parent>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'parent> Copy for PlatformRef<'parent>