A low-level way to add dependent branches with single-branch support.

This means it's just taking care of the essential pieces, and will need at
least one layer on top to be suitable to be called by the various
application layers.

Author: Byron

crates/but-graph/tests/graph/init/utils.rs

@@ -1,7 +1,6 @@
 use but_core::ref_metadata::StackId;
 use but_graph::VirtualBranchesTomlMetadata;
 use but_graph::virtual_branches_legacy_types::{Stack, StackBranch, Target};
-use gix::Repository;
 
 pub fn read_only_in_memory_scenario(
     name: &str,
@@ -113,19 +112,6 @@ pub fn add_stack_with_segments(
     stack_id
 }
 
-pub fn id_at<'repo>(repo: &'repo Repository, name: &str) -> (gix::Id<'repo>, gix::refs::FullName) {
-    let mut rn = repo
-        .find_reference(name)
-        .expect("statically known reference exists");
-    let id = rn.peel_to_id_in_place().expect("must be valid reference");
-    (id, rn.inner.name)
-}
-
-pub fn id_by_rev<'repo>(repo: &'repo gix::Repository, rev: &str) -> gix::Id<'repo> {
-    repo.rev_parse_single(rev)
-        .expect("well-known revspec when testing")
-}
-
 pub fn standard_options() -> but_graph::init::Options {
     but_graph::init::Options {
         collect_tags: true,
@@ -145,3 +131,5 @@ pub fn standard_options_with_extra_target(
         ..standard_options()
     }
 }
+
+pub use but_testsupport::{id_at, id_by_rev};

crates/but-testsupport/src/lib.rs

@@ -1,6 +1,7 @@
 //! Utilities for testing.
 #![deny(rust_2018_idioms, missing_docs)]
 
+use gix::Repository;
 use gix::bstr::{BStr, ByteSlice};
 use gix::config::tree::Key;
 pub use gix_testtools;
@@ -236,6 +237,22 @@ pub fn visualize_disk_tree_skip_dot_git(_root: &Path) -> anyhow::Result<termtree
     anyhow::bail!("BUG: must not run on Windows - results won't be desirable");
 }
 
+/// Produce the id at the reference with `name` (short-name is fine), and also return the full name
+/// of the reference.
+pub fn id_at<'repo>(repo: &'repo Repository, name: &str) -> (gix::Id<'repo>, gix::refs::FullName) {
+    let mut rn = repo
+        .find_reference(name)
+        .expect("statically known reference exists");
+    let id = rn.peel_to_id_in_place().expect("must be valid reference");
+    (id, rn.inner.name)
+}
+
+/// Return the commit by the given `revspec`.
+pub fn id_by_rev<'repo>(repo: &'repo gix::Repository, revspec: &str) -> gix::Id<'repo> {
+    repo.rev_parse_single(revspec)
+        .expect("well-known revspec when testing")
+}
+
 mod graph {
     use but_graph::SegmentMetadata;
     use but_graph::{EntryPoint, Graph, SegmentIndex};

crates/but-workspace/src/branch.rs

@@ -131,7 +131,7 @@
 //! For instance, if a references is `refs/heads/gitbutler/workspace/one`, then the stash reference is in
 //! `<namespace: gitbutler-stashes>/refs/heads/gitbutler/workspace/one`. The reason for this is that they will not
 //! be garbage-collected that way.
-//! Note that any ref, like `refs/heads/feature` can carry a stash, so *workspace references* aren't special.
+//! Note that any ref, like `refs/heads/gitbutler/workspace` can carry one or more stashes, so *workspace references* aren't special.
 //!
 //! *This also makes stashes enumerable*. It's notable that it's entirely possible for stashes to become *orphaned*,
 //! i.e. their workspace commit (that the stash commit sits on top of) doesn't have a reference *with the same name*
@@ -530,7 +530,55 @@ impl Stack {
     }
 }
 
-/// Return all stack segments within the given `stack`.
-pub fn stack_segments(stack: Stack) -> anyhow::Result<Vec<ref_info::ui::Segment>> {
+mod create_reference {
+    /// For use in [`ReferenceAnchor`].
+    #[derive(Debug, Clone, Copy)]
+    pub enum ReferencePosition {
+        /// The new dependent branch will appear above its anchor.
+        Above,
+        /// The new dependent branch will appear below its anchor.
+        Below,
+    }
+
+    /// For use in [`create_reference()`].
+    #[derive(Debug, Clone)]
+    pub enum ReferenceAnchor {
+        /// Create the reference above this commit.
+        /// This will fail if there already is a named segment
+        /// at exactly this commit.
+        AtCommit {
+            /// The commit that `position` relates to.
+            commit: gix::ObjectId,
+            /// The reference points at `commit` when [`ReferencePosition::Above`],
+            /// or the first parent of `commit` when [`ReferencePosition::Below`].
+            position: ReferencePosition,
+        },
+        /// Create a dependent reference in relation to the commit pointed to by another reference.
+        AtReference {
+            /// The reference that `position` relates to.
+            ref_name: gix::refs::FullName,
+            /// The reference points at the commit of `ref_name` when [`ReferencePosition::Above`],
+            /// or the first parent the first commit of `ref_name` when [`ReferencePosition::Below`].
+            position: ReferencePosition,
+        },
+    }
+}
+pub use create_reference::*;
+
+/// Create a new reference named `ref_name` in relation to `anchor`, which is expected to be contained
+/// in any stack in `workspace`, and place it into `repo`.
+/// Fail if the reference already exists *and* points somewhere else.
+/// Note that `workspace` is frozen in time and won't contain the newly created reference or new segment.
+/// `meta` will be created for `ref_name` as well, or its data update if it did exist already.
+///
+///  - if there is no managed workspace, then dependent branches must be exclusive on each commit to identify ordering
+///  - if there is a workspace, we store the order in workspace metadata
+pub fn create_reference(
+    repo: &gix::Repository,
+    ref_name: &gix::refs::FullNameRef,
+    anchor: ReferenceAnchor,
+    workspace: &but_graph::projection::Workspace<'_>,
+    meta: &mut impl RefMetadata,
+) -> anyhow::Result<()> {
     todo!()
 }

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

@@ -0,0 +1,47 @@
+mod create_reference {
+    use crate::ref_info::with_workspace_commit::utils::named_read_only_in_memory_scenario;
+    use but_graph::init::Options;
+    use but_testsupport::{id_at, visualize_commit_graph_all};
+    use but_workspace::branch::{ReferenceAnchor, ReferencePosition};
+
+    #[test]
+    fn error_creating_below_first_commit() -> anyhow::Result<()> {
+        let (repo, mut meta) =
+            named_read_only_in_memory_scenario("with-remotes-no-workspace", "remote")?;
+        insta::assert_snapshot!(visualize_commit_graph_all(&repo)?, @r"
+        * 89cc2d3 (A) change in A
+        * d79bba9 new file in A
+        * c166d42 (HEAD -> main) init-integration
+        ");
+
+        let graph = but_graph::Graph::from_head(&repo, &*meta, Options::limited())?;
+        let ws = graph.to_workspace()?;
+        let (id, ref_name) = id_at(&repo, "main");
+        for anchor in [
+            ReferenceAnchor::AtCommit {
+                commit: id.detach(),
+                position: ReferencePosition::Below,
+            },
+            ReferenceAnchor::AtReference {
+                ref_name: ref_name.clone(),
+                position: ReferencePosition::Below,
+            },
+        ] {
+            let err = but_workspace::branch::create_reference(
+                &repo,
+                // existing name, but that's not the problem
+                ref_name.as_ref(),
+                anchor,
+                &ws,
+                &mut *meta,
+            )
+            .unwrap_err();
+            assert_eq!(
+                err.to_string(),
+                "TBD",
+                "it's not possible to show anything before the beginning of time"
+            );
+        }
+        Ok(())
+    }
+}

crates/but-workspace/tests/workspace/main.rs

@@ -1,5 +1,6 @@
 use but_workspace::{DiffSpec, HunkHeader, flatten_diff_specs};
 
+mod branch;
 mod branch_details;
 mod commit_engine;
 mod flatten_diff_specs;

crates/but-workspace/tests/workspace/ui.rs

@@ -1,5 +1,6 @@
 mod changes_in_branch {
     use crate::ref_info::with_workspace_commit::utils::read_only_in_memory_scenario;
+    use crate::utils::r;
     use but_graph::init::Options;
     use but_testsupport::visualize_commit_graph_all;
     use but_workspace::ui;
@@ -137,8 +138,4 @@ mod changes_in_branch {
         );
         Ok(())
     }
-
-    fn r(name: &str) -> &gix::refs::FullNameRef {
-        name.try_into().expect("statically known valid ref-name")
-    }
 }

crates/but-workspace/tests/workspace/utils.rs

@@ -361,3 +361,7 @@ pub fn hunk_header(old: &str, new: &str) -> HunkHeader {
         new_lines,
     }
 }
+
+pub fn r(name: &str) -> &gix::refs::FullNameRef {
+    name.try_into().expect("statically known valid ref-name")
+}