Basic apply and unapply

The idea is to develop both at the same time so it's easier to test
that 'unapply' truly goes back to the (mostly) original state.

Author: Byron

crates/but-graph/src/projection/workspace.rs

@@ -149,6 +149,11 @@ impl Workspace<'_> {
             })
     }
 
+    /// Return `true` if `name` is contained in the workspace as segment.
+    pub fn refname_is_segment(&self, name: &gix::refs::FullNameRef) -> bool {
+        self.find_segment_and_stack_by_refname(name).is_some()
+    }
+
     /// Try to find `name` in any named [`StackSegment`] and return it along with the stack containing it.
     pub fn find_segment_and_stack_by_refname(
         &self,
@@ -189,9 +194,9 @@ pub enum WorkspaceKind {
         /// The name of the reference pointing to the workspace commit. Useful for deriving the workspace name.
         ref_name: gix::refs::FullName,
     },
-    /// Information for when a workspace reference was advanced by hand and does not point to a
-    /// managed workspace commit anymore.
-    /// That commit, however, is reachable by following the first parent from the workspace reference.
+    /// Information for when a workspace reference was *possibly* advanced by hand and does not point to a
+    /// managed workspace commit (anymore).
+    /// That workspace commit, may be reachable by following the first parent from the workspace reference.
     ///
     /// Note that the stacks that follow *will* be in unusable if the workspace commit is in a segment below,
     /// but typically is usable if there is just a single real stack, or any amount of virtual stacks below

crates/but-workspace/src/branch/apply.rs

@@ -0,0 +1,123 @@
+/// Returned by [function::apply()].
+pub struct Outcome {
+    /// The newly created graph, useful to project a workspace and see how the workspace looks like with the branch applied.
+    pub graph: but_graph::Graph,
+    /// `true` if we created the given workspace ref as it didn't exist yet.
+    pub workspace_ref_created: bool,
+}
+
+impl std::fmt::Debug for Outcome {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Outcome")
+            .field("workspace_ref_created", &self.workspace_ref_created)
+            .finish()
+    }
+}
+
+/// How the newly applied branch should be integrated into the workspace.
+#[derive(Default, Debug, Copy, Clone)]
+pub enum IntegrationMode {
+    /// Do nothing but to merge it into the workspace commit.
+    #[default]
+    Merge,
+}
+
+/// What to do if the applied branch conflicts?
+#[derive(Default, Debug, Copy, Clone)]
+pub enum OnWorkspaceConflict {
+    /// Provide additional information about the stack that conflicted and the files involved in it,
+    /// and don't perform the operation.
+    #[default]
+    AbortAndReportConflictingStack,
+}
+
+/// Decide how a newly created workspace reference should be named.
+#[derive(Default, Debug, Clone)]
+pub enum WorkspaceReferenceNaming {
+    /// Create a default workspace branch
+    #[default]
+    Default,
+    /// Create a workspace with the given name instead.
+    Given(gix::refs::FullName),
+}
+
+/// Options for [function::apply()].
+#[derive(Default, Debug, Clone)]
+pub struct Options {
+    /// how the branch should be brought into the workspace.
+    pub integration_mode: IntegrationMode,
+    /// Decide how to deal with conflicts.
+    pub on_workspace_conflict: OnWorkspaceConflict,
+    /// How the workspace reference should be named should it be created.
+    /// The creation is always needed if there are more than one branch applied.
+    pub workspace_reference_naming: WorkspaceReferenceNaming,
+}
+
+pub(crate) mod function {
+    use super::{Options, Outcome, WorkspaceReferenceNaming};
+    use anyhow::bail;
+    use but_core::RefMetadata;
+    use but_graph::projection::WorkspaceKind;
+
+    /// Apply `branch` to the given `workspace`, and possibly create the workspace reference in `repo`
+    /// along with its `meta`-data if it doesn't exist yet.
+    /// Otherwise, add it to the existing `workspace`, and update its metadata accordingly.
+    /// **This means that the contents of `branch` is observable from the new state of `repo`**.
+    ///
+    /// Note that `workspace` is expected to match the state in `repo` as it's used instead of querying `repo` directly
+    /// where possible.
+    ///
+    /// Also note that we will create a managed workspace reference as needed if necessary, and a workspace commit if there is more than
+    /// one reference in the workspace afterward.
+    ///
+    /// On `error`, neither `repo` nor `meta` will have been changed.
+    /// Otherwise, objects will have been persisted, and references and metadata will have been updated.
+    pub fn apply<T: RefMetadata>(
+        branch: &gix::refs::FullNameRef,
+        workspace: &but_graph::projection::Workspace,
+        repo: &mut gix::Repository,
+        _meta: &mut T,
+        Options {
+            integration_mode: _,
+            on_workspace_conflict: _,
+            workspace_reference_naming,
+        }: Options,
+    ) -> anyhow::Result<Outcome> {
+        if workspace.refname_is_segment(branch) {
+            return Ok(Outcome {
+                graph: workspace.graph.clone(),
+                workspace_ref_created: false,
+            });
+        }
+
+        if let Some(ws_ref_name) = workspace.ref_name() {
+            if repo.try_find_reference(ws_ref_name)?.is_none() {
+                // The workspace is the probably ad-hoc, and doesn't exist, *assume* unborn.
+                bail!(
+                    "Cannot create reference on unborn branch '{}'",
+                    ws_ref_name.shorten()
+                );
+            }
+        }
+        let workspace_ref_name = match &workspace.kind {
+            WorkspaceKind::Managed { ref_name }
+            | WorkspaceKind::ManagedMissingWorkspaceCommit { ref_name } => ref_name.clone(),
+            WorkspaceKind::AdHoc => match workspace_reference_naming {
+                WorkspaceReferenceNaming::Default => {
+                    gix::refs::FullName::try_from("refs/heads/gitbutler/workspace")
+                        .expect("known statically")
+                }
+                WorkspaceReferenceNaming::Given(name) => name,
+            },
+        };
+
+        match repo.try_find_reference(workspace_ref_name.as_ref())? {
+            None => {
+                todo!("create ref and redo")
+            }
+            Some(_) => {
+                todo!("get bearings")
+            }
+        }
+    }
+}

crates/but-workspace/src/branch/create_reference.rs

@@ -218,9 +218,14 @@ pub(super) mod function {
                                 ref_name.shorten()
                             );
                         };
-                        position.resolve_commit(segment.commits.first().context(
-                            "BUG: empty segments aren't possible without workspace metadata",
-                        )?.into(), ws_base)?
+                        position.resolve_commit(
+                            segment
+                                .commits
+                                .first()
+                                .context("Cannot create reference on unborn branch")?
+                                .into(),
+                            ws_base,
+                        )?
                     };
                     (
                         validate_id,

crates/but-workspace/src/branch/mod.rs

@@ -456,6 +456,10 @@ impl Stack {
     }
 }
 
+/// Functions and types related to applying a workspace branch.
+pub mod apply;
+pub use apply::function::apply;
+
 /// related types for removing a workspace reference.
 pub mod remove_reference;
 pub use remove_reference::function::remove_reference;

crates/but-workspace/tests/fixtures/generated-archives/.gitignore

@@ -29,4 +29,6 @@
 /with-conflict.tar
 /journey*.tar
 /single-branch*.tar
-/index*.tar
+/index*.tar
+/detached-*.tar
+/ws-ref-*

crates/but-workspace/tests/fixtures/scenario/detached-with-multiple-branches.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+set -eu -o pipefail
+source "${BASH_SOURCE[0]%/*}/shared.sh"
+
+### Description
+# The HEAD is detached, and there are multiple branches.
+
+git init
+commit M1
+git branch B
+git branch C
+git checkout -b A
+  commit A1
+git checkout B
+  commit B1
+git checkout C
+  commit C1
+git checkout --detach HEAD

crates/but-workspace/tests/fixtures/scenario/unborn-empty-detached-remote.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+set -eu -o pipefail
+
+source "${BASH_SOURCE[0]%/*}/shared.sh"
+
+### Description
+# A newly initialized git repository, but with a known remote that has an object.
+
+git init remote
+(cd remote
+  commit "M1"
+)
+
+git init unborn
+(cd unborn
+  git remote add orphan ../remote
+  git fetch orphan
+)

crates/but-workspace/tests/fixtures/scenario/with-remotes-and-workspace.sh

@@ -1,13 +1,13 @@
 #!/usr/bin/env bash
 
-### General Description
-
-# Various directories with different scenarios for testing stack information *with* a workspace commit,
-# and of course with a remote and a branch to integrate with.
 set -eu -o pipefail
 
 source "${BASH_SOURCE[0]%/*}/shared.sh"
 
+### General Description
+
+# Various directories with different scenarios for testing stack information *with* a workspace commit,
+# and of course with a remote and a branch to integrate with.
 
 git init remote
 (cd remote

crates/but-workspace/tests/fixtures/scenario/ws-ref-no-ws-commit-one-stack-one-branch.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+set -eu -o pipefail
+
+source "${BASH_SOURCE[0]%/*}/shared.sh"
+
+### General Description
+
+# A ws-ref points to a commit, which is also owned by a stack. There is another branch outside of the workspace pointing to the same commit.
+git init
+
+git checkout -b A
+commit A
+git branch B
+git checkout -b gitbutler/workspace