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,28 @@
+/// 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,
+}
+
+pub(crate) mod function {
+    use super::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,
+    ) -> anyhow::Result<Outcome> {
+        todo!()
+    }
+}

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

@@ -220,9 +220,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/workspace/branch/apply_unapply.rs

@@ -0,0 +1,41 @@
+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;
+
+#[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", "")?;
+    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 err =
+        but_workspace::branch::apply(r("refs/heads/new"), &ws, &mut repo, &mut *meta).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

@@ -8,6 +8,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::{ReferenceAnchor, ReferencePosition};
+use std::borrow::Cow;
 
 mod with_workspace {
     use crate::ref_info::with_workspace_commit::utils::{
@@ -1068,6 +1069,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,
+        ReferenceAnchor::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"
@@ -1087,7 +1112,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 [
         ReferenceAnchor::at_id(id, Below),
         ReferenceAnchor::at_segment(ref_name.as_ref(), Below),
@@ -1257,7 +1281,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;