docs: Add some more docs for move commit and branch

Add documentation explaining the usage of some parameters for
move_commit and move_branch. 
Also document the reasoning behind using the workspace projection for
this operations.

Author: estib-vega

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

@@ -30,6 +30,9 @@ pub(super) mod function {
 
     /// Move a branch between stacks in the `workspace`.
     ///
+    /// `editor` is assumed to have been generated from the given `workspace`
+    /// and therefore aligned.
+    ///
     /// `subject_branch_name` is the full reference name of the branch to move.
     ///
     /// `target_branch_name` is the full reference name of the branch to move the subject
@@ -43,18 +46,8 @@ pub(super) mod function {
         subject_branch_name: &FullNameRef,
         target_branch_name: &FullNameRef,
     ) -> anyhow::Result<Outcome> {
-        let Some(source) = workspace.find_segment_and_stack_by_refname(subject_branch_name) else {
-            bail!(
-                "Couldn't find branch to move in workspace with reference name: {subject_branch_name}"
-            );
-        };
-
-        let Some(destination) = workspace.find_segment_and_stack_by_refname(target_branch_name)
-        else {
-            bail!(
-                "Couldn't find target branch to move in workspace with reference name: {target_branch_name}"
-            );
-        };
+        let (source, destination) =
+            retrieve_branches_and_containers(workspace, subject_branch_name, target_branch_name)?;
 
         let Some(workspace_head) = workspace.tip_commit().map(|commit| commit.id) else {
             bail!("Couldn't find workspace head.")
@@ -123,6 +116,56 @@ pub(super) mod function {
             ws_meta,
         })
     }
+
+    /// A segment and its container stack.
+    type WorkspaceSegmentContext<'a> = (
+        &'a but_graph::projection::Stack,
+        &'a but_graph::projection::StackSegment,
+    );
+
+    /// Determine the surrounding context of the subject and target branches.
+    ///
+    /// Currently, this looks into the workspace projection in order to determine **where to take the branch from and to**.
+    ///
+    /// ### The issue
+    /// It's impossible to know for sure what is the exact intention of 'moving a branch' inside a complex git graph.
+    /// Any commit, can have N children and M parents. 'Moving' it somewhere else can imply:
+    /// - Disconnecting all parents and children, and inserting it somewhere else.
+    /// - Disconnecting the first parent and all children, and then inserting.
+    /// - Disconnecting *some* parents and *some* children, and then inserting it.
+    ///
+    /// This condition holds for every commit in a branch.
+    ///
+    /// ### The GitButler assumption
+    /// In the context of a GitButler workspace (as of this writting), we want to disconnect the branch (segment) from
+    /// the stack, and insert it on top of another. In graph terms, this means that we:
+    /// - Disconnect the reference node from the base segment (the branch under the subject or the target base)
+    /// - Disconnect the last commit node of the child segment (the branch over the subject or the workspace commit)
+    /// - Nothing else. Other parentage and childrent are kept, since this is what we care about in a GB workspace world.
+    ///
+    /// ### What the future holds
+    /// In the future, where we're not afraid of complex graphs, we've figured out UX and data wrangling,
+    /// the concept of a segment might not hold, and hence we'll have to figure out a better way of dermining
+    /// what to cut (e.g. letting the clients decide what to cut).
+    fn retrieve_branches_and_containers<'a>(
+        workspace: &'a but_graph::projection::Workspace,
+        subject_branch_name: &FullNameRef,
+        target_branch_name: &FullNameRef,
+    ) -> anyhow::Result<(WorkspaceSegmentContext<'a>, WorkspaceSegmentContext<'a>)> {
+        let Some(source) = workspace.find_segment_and_stack_by_refname(subject_branch_name) else {
+            bail!(
+                "Couldn't find branch to move in workspace with reference name: {subject_branch_name}"
+            );
+        };
+
+        let Some(destination) = workspace.find_segment_and_stack_by_refname(target_branch_name)
+        else {
+            bail!(
+                "Couldn't find target branch to move in workspace with reference name: {target_branch_name}"
+            );
+        };
+        Ok((source, destination))
+    }
 }
 
 /// Get the right disconnect parameters for the given subject segment and source stack.

crates/but-workspace/src/commit/move_commit.rs

@@ -9,6 +9,15 @@ pub(crate) mod function {
 
     /// Move a commit.
     ///
+    /// `editor` is assumed to have been generated from the given `workspace`
+    /// and therefore aligned.
+    ///
+    /// `subject_commit` - The commit to be moved.
+    ///
+    /// `anchor` - A git graph node selector to move the subject commit relative to.
+    ///
+    /// `side` - The side relative to the anchor at which to insert the subject commit.
+    ///
     /// The subject commit will be detached from the source segment, and inserted relative
     /// to a given anchor (branch or commit).
     pub fn move_commit(
@@ -21,9 +30,7 @@ pub(crate) mod function {
         let (subject_commit_selector, subject_commit) =
             editor.find_selectable_commit(subject_commit)?;
 
-        let Some(subject) = workspace.find_commit_and_containers(&subject_commit.id) else {
-            bail!("Failed to find the commit to move in the workspace.");
-        };
+        let subject = retrieve_commit_and_containers(workspace, &subject_commit)?;
 
         let (source_stack, source_segment, _) = subject;
 
@@ -50,16 +57,33 @@ pub(crate) mod function {
             index_of_subject_commit,
         )?;
 
+        // Step 2: Disconnect
         editor.disconnect_segment_from(
             commit_delimiter.clone(),
             child_to_disconnect,
             parent_to_disconnect,
             false,
         )?;
+
+        // Step 3: Insert
         editor.insert_segment(anchor, commit_delimiter, side)?;
         editor.rebase()
     }
 
+    fn retrieve_commit_and_containers<'a>(
+        workspace: &'a but_graph::projection::Workspace,
+        subject_commit: &but_core::CommitOwned,
+    ) -> anyhow::Result<(
+        &'a but_graph::projection::Stack,
+        &'a but_graph::projection::StackSegment,
+        &'a but_graph::projection::StackCommit,
+    )> {
+        let Some(subject) = workspace.find_commit_and_containers(&subject_commit.id) else {
+            bail!("Failed to find the commit to move in the workspace.");
+        };
+        Ok(subject)
+    }
+
     /// Determine which children to disconnect, based on the position of the subject commit in the segment.
     fn determine_child_selector(
         editor: &Editor,