Sketch of the APIs involved in branch::apply().

Author: Byron

crates/but-workspace/src/lib.rs

@@ -1,4 +1,4 @@
-#![deny(missing_docs, rust_2018_idioms)]
+#![deny(missing_docs)]
 #![deny(clippy::indexing_slicing)]
 
 //! ### Terminology
@@ -55,6 +55,8 @@ pub use head::{head, merge_worktree_with_workspace};
 /// Ignore the name of this module; it's just a place to put code by now.
 pub mod branch;
 
+pub mod snapshot;
+
 mod changeset;
 
 mod commit;

crates/but-workspace/src/snapshot.rs

@@ -0,0 +1,109 @@
+//! The ability to create a Git representation of diverse 'state' that can be restored at a later time.
+
+///
+pub mod create_tree {
+    use bstr::BString;
+
+    /// A way to determine what should be included in the snapshot when calling [create_tree()](function::create_tree).
+    pub struct State<'a> {
+        /// The result of a previous worktree changes call.
+        ///
+        /// It contains detailed information about the complete set of possible changes to become part of the worktree.
+        pub changes: &'a but_core::WorktreeChanges,
+        /// Repository-relative and slash-separated paths that match any change in the  [`changes`](State::changes) field.
+        /// **It's an error if there is no match.** as there is not supposed to be a snapshot without a change to the working tree.
+        pub selection: Vec<BString>,
+    }
+
+    /// Contains all state that the snapshot contains.
+    #[derive(Debug, Copy, Clone)]
+    pub struct Outcome {
+        /// The snapshot itself, with all the subtrees available that are also listed in this structure.
+        pub snapshot_tree: gix::ObjectId,
+        /// For good measure, the input `HEAD^{tree}` that is used as the basis to learn about worktree changes.
+        pub head_tree: gix::ObjectId,
+        /// The `head_tree`  with the selected worktree changes applied, suitable for being stored in a commit.
+        pub wortree: gix::ObjectId,
+        /// The tree representing the current changed index, without conflicts, or `None` if there was no change to the index.
+        pub index: Option<gix::ObjectId>,
+        /// A tree with files in a custom storage format to allow keeping conflicting blobs reachable, along with detailed conflict information
+        /// to allow restoring the conflict entries in the index.
+        pub index_conflicts: Option<gix::ObjectId>,
+        /// The tree representing the reference targets of all references within the *workspace*.
+        pub workspace_reference: Option<gix::ObjectId>,
+        /// The tree representing the metadata of all references within the *workspace*.
+        pub metadata: Option<gix::ObjectId>,
+    }
+
+    pub(super) mod function {
+        use super::{Outcome, State};
+        use but_core::RefMetadata;
+        /// Create a tree that represents the snapshot for the given `selection`, with the basis for everything
+        /// being the `head_tree_id` (i.e. the tree to which `HEAD` is ultimately pointing to).
+        ///
+        /// If `workspace_and_meta` is not `None`, the workspace and metadata to store in the snapshot.
+        /// We will only store reference positions, and assume that their commits are safely stored in the reflog to not
+        /// be garbage collected. Metadata is only stored for the references that are included in the `workspace`.
+        /// This way we will also store the `HEAD` position to keep track of where the user is located.
+        ///
+        /// Note that objects will be written into the repository behind `head_tree_id` unless it's configured
+        /// to keep everything in memory.
+        pub fn create_tree(
+            head_tree_id: gix::Id<'_>,
+            selection: State,
+            workspace_and_meta: Option<(&but_graph::projection::Workspace, &impl RefMetadata)>,
+        ) -> anyhow::Result<Outcome> {
+            todo!()
+        }
+    }
+}
+pub use create_tree::function::create_tree;
+
+/// Utilities related to resolving previously created snapshots.
+pub mod resolve_tree {
+
+    /// The information extracted from [`resolve_tree`](function::resolve_tree()).
+    pub struct Outcome<'repo> {
+        /// The cherry-pick result as merge between the target worktree and the snapshot, **possibly with conflicts**.
+        ///
+        /// This tree, may be checked out to the working tree, with or without conflicts.
+        pub workspace_cherry_pick: gix::merge::tree::Outcome<'repo>,
+        /// If an index was stored in the snapshot, this is the reconstructed index, including conflicts.
+        pub index: Option<gix::index::State>,
+        /// Reference edits that when applied in a transaction will set the workspace back to where it was. Only available
+        /// if it was part of the snapshot to begin with.
+        pub workspace_references: Option<Vec<gix::refs::transaction::RefEdit>>,
+        /// The metadata to be applied to the ref-metadata store.
+        pub metadata: Option<MetadataEdits>,
+    }
+
+    /// Edits for application via [`but_core::RefMetadata`].
+    pub struct MetadataEdits {
+        /// The workspace metadata stored in the snapshot.
+        pub workspace: (gix::refs::FullName, but_core::ref_metadata::Workspace),
+        /// The branch metadata stored in snapshots.
+        pub branches: Vec<(gix::refs::FullName, but_core::ref_metadata::Branch)>,
+    }
+
+    pub(super) mod function {
+        use super::Outcome;
+
+        /// Given the `snapshot` tree as previously returned via [super::create_tree::Outcome::snapshot_tree], extract the data and…
+        ///
+        /// * …cherry-pick the worktree changes onto the `target_worktree_tree_id`, which is assumed to represent the future working directory state
+        ///    and which either contains the worktree changes or *preferably* is the `HEAD^{tree}` as the working directory is clean.
+        /// * …reconstruct the index to write into `.git/index`, assuming that the current `.git/index` is clean.
+        /// * …produce reference edits to put the workspace refs back into place with.
+        /// * …produce metadata that if set will represent the metadata of the entire workspace.
+        ///
+        /// Note that none of this data is actually manifested in the repository or working tree, they only exists as objects in the Git database,
+        /// assuming in-memory objects aren't used in the repository.
+        pub fn resolve_tree<'repo>(
+            snapshot: gix::Id<'_>,
+            target_worktree_tree_id: gix::ObjectId,
+        ) -> anyhow::Result<Outcome<'_>> {
+            todo!()
+        }
+    }
+}
+pub use resolve_tree::function::resolve_tree;