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

@@ -0,0 +1,50 @@
+/// Returned by [function::apply()].
+#[derive(Debug)]
+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,
+}
+
+/// How the newly applied branch should be integrated into the workspace.
+#[derive(Default, Debug, Copy, Clone)]
+pub enum IntegrationMode {
+    /// Do nothing, just merge it into
+    #[default]
+    Merge,
+}
+
+/// What to do if the applied branch conflicts?
+#[derive(Default, Debug, Copy, Clone)]
+pub enum OnWorkspaceConflict {}
+
+/// Options for [function::apply()].
+#[derive(Default, Debug, Copy, 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,
+}
+
+pub(crate) mod function {
+    use super::{Options, Outcome};
+    use but_core::RefMetadata;
+
+    /// 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.
+    ///
+    /// 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 }: Options,
+    ) -> anyhow::Result<Outcome> {
+        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/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,49 @@
+use crate::ref_info::with_workspace_commit::utils::named_read_only_in_memory_scenario;
+use crate::utils::r;
+use but_graph::init::Options;
+use but_testsupport::{graph_workspace, visualize_commit_graph_all};
+
+#[test]
+#[ignore = "TBD: idempotent"]
+fn apply_branch_already_in_workspace() -> anyhow::Result<()> {
+    Ok(())
+}
+
+#[test]
+#[ignore = "TBD: idempotent"]
+fn unapply_branch_not_in_workspace() -> anyhow::Result<()> {
+    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(&mut 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
+    ");
+
+    // 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");
+    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;