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

@@ -189,9 +189,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,114 @@
+/// 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.
+    /// Note that `workspace` is expected to match the state in `repo` as it's used instead of querying `repo` directly
+    /// where possible.
+    /// 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
+            .find_segment_and_stack_by_refname(branch)
+            .is_some()
+        {
+            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() {
+                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 } => Ok(ref_name.clone()),
+            WorkspaceKind::AdHoc => Err(match workspace_reference_naming {
+                WorkspaceReferenceNaming::Default => {
+                    gix::refs::FullName::try_from("refs/heads/gitbutler/workspace")
+                        .expect("known statically")
+                }
+                WorkspaceReferenceNaming::Given(name) => name,
+            }),
+        };
+        todo!()
+    }
+}

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,5 @@
 /with-conflict.tar
 /journey*.tar
 /single-branch*.tar
-/index*.tar
+/index*.tar
+/detached-*.tar

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/workspace/branch/apply_unapply.rs

@@ -0,0 +1,102 @@
+use crate::ref_info::with_workspace_commit::utils::{
+    named_read_only_in_memory_scenario, named_writable_scenario_with_description_and_graph,
+};
+use crate::utils::r;
+use but_graph::init::Options;
+use but_testsupport::{graph_workspace, visualize_commit_graph_all};
+
+#[test]
+#[ignore = "TBD: idempotent"]
+fn unapply_branch_not_in_workspace() -> anyhow::Result<()> {
+    Ok(())
+}
+
+#[test]
+fn detached_head_journey() -> anyhow::Result<()> {
+    let (_tmp, graph, mut repo, mut meta, _description) =
+        named_writable_scenario_with_description_and_graph(
+            "detached-with-multiple-branches",
+            |_meta| {},
+        )?;
+    insta::assert_snapshot!(visualize_commit_graph_all(&repo)?, @r"
+    * 49d4b34 (A) A1
+    | * f57c528 (B) B1
+    |/  
+    | * aaa195b (HEAD, C) C1
+    |/  
+    * 3183e43 (main) M1
+    ");
+    let ws = graph.to_workspace()?;
+    insta::assert_snapshot!(graph_workspace(&ws), @r"
+    ⌂:0:DETACHED <> ✓!
+    └── ≡:0:anon:
+        ├── :0:anon:
+        │   └── ·aaa195b ►C
+        └── :1:main
+            └── ·3183e43
+    ");
+
+    let out = but_workspace::branch::apply(
+        r("refs/heads/A"),
+        &ws,
+        &mut repo,
+        &mut meta,
+        Default::default(),
+    )?;
+    insta::assert_debug_snapshot!(out, @r"
+    Outcome {
+        workspace_ref_created: false,
+    }
+    ");
+    Ok(())
+}
+
+#[test]
+fn unborn_apply_needs_base() -> anyhow::Result<()> {
+    let (mut repo, mut meta) =
+        named_read_only_in_memory_scenario("unborn-empty-detached-remote", "unborn")?;
+    insta::assert_snapshot!(visualize_commit_graph_all(&repo)?, @"* 3183e43 (orphan/main) M1");
+    let graph = but_graph::Graph::from_head(&repo, &*meta, Options::limited())?;
+    let ws = graph.to_workspace()?;
+    insta::assert_snapshot!(graph_workspace(&ws), @r"
+    ⌂:0:main <> ✓!
+    └── ≡:0:main
+        └── :0:main
+    ");
+
+    // Idempotency
+    let out = but_workspace::branch::apply(
+        r("refs/heads/main"),
+        &ws,
+        &mut repo,
+        &mut *meta,
+        Default::default(),
+    )?;
+    insta::assert_debug_snapshot!(out, @r"
+    Outcome {
+        workspace_ref_created: false,
+    }
+    ");
+
+    // Cannot apply branch without a base.
+    let err = but_workspace::branch::apply(
+        r("refs/remotes/orphan/main"),
+        &ws,
+        &mut repo,
+        &mut *meta,
+        Default::default(),
+    )
+    .unwrap_err();
+    assert_eq!(
+        err.to_string(),
+        "Cannot create reference on unborn branch 'main'"
+    );
+    Ok(())
+}
+
+#[test]
+#[ignore = "TBD"]
+fn apply_branch_resting_on_base() -> anyhow::Result<()> {
+    // THis can't work, but should fail gracefully.
+    Ok(())
+}

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

@@ -7,6 +7,7 @@ use but_core::ref_metadata::ValueInfo;
 use but_graph::init::Options;
 use but_testsupport::{graph_workspace, id_at, id_by_rev, visualize_commit_graph_all};
 use but_workspace::branch::create_reference::{Anchor, Position::*};
+use std::borrow::Cow;
 
 mod with_workspace {
     use crate::ref_info::with_workspace_commit::utils::{
@@ -1066,6 +1067,30 @@ mod with_workspace {
 
 #[test]
 fn errors() -> anyhow::Result<()> {
+    let (repo, mut meta) = named_read_only_in_memory_scenario("unborn-empty", "")?;
+    let graph = but_graph::Graph::from_head(&repo, &*meta, Options::limited())?;
+    let ws = graph.to_workspace()?;
+    insta::assert_snapshot!(graph_workspace(&ws), @r"
+    ⌂:0:main <> ✓!
+    └── ≡:0:main
+        └── :0:main
+    ");
+
+    // Below first in history
+    let new_name = r("refs/heads/does-not-matter");
+    let err = but_workspace::branch::create_reference(
+        new_name,
+        Anchor::AtSegment {
+            ref_name: Cow::Borrowed(r("refs/heads/main")),
+            position: Above,
+        },
+        &repo,
+        &ws,
+        &mut *meta,
+    )
+    .unwrap_err();
+    assert_eq!(err.to_string(), "Cannot create reference on unborn branch");
+
     let (repo, mut meta) =
         named_read_only_in_memory_scenario("with-remotes-no-workspace", "remote")?;
     insta::assert_snapshot!(visualize_commit_graph_all(&repo)?, @r"
@@ -1085,7 +1110,6 @@ fn errors() -> anyhow::Result<()> {
         ");
 
     let (id, ref_name) = id_at(&repo, "main");
-    let new_name = r("refs/heads/does-not-matter");
     for anchor in [
         Anchor::at_id(id, Below),
         Anchor::at_segment(ref_name.as_ref(), Below),
@@ -1252,7 +1276,7 @@ fn errors() -> anyhow::Result<()> {
 }
 
 #[test]
-fn journey() -> anyhow::Result<()> {
+fn journey_with_commits() -> anyhow::Result<()> {
     let (_tmp, repo, mut meta) = named_writable_scenario("single-branch-with-3-commits")?;
     insta::assert_snapshot!(visualize_commit_graph_all(&repo)?, @r"
         * 281da94 (HEAD -> main) 3

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

@@ -1,2 +1,3 @@
+mod apply_unapply;
 mod create_reference;
 mod remove_reference;