Use but-rebase to rewrite the history up to tips of workspaces.

Additionally, provide the information needed to rewrite hidden/internal
references.

Author: Byron

Cargo.lock

@@ -94,7 +94,7 @@ pub enum UnifiedDiff {
 }
 
 /// Either git reference or a virtual reference (i.e. a reference not visible in Git).
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, PartialEq)]
 pub enum Reference {
     /// A git reference or lightweight tag.
     Git(gix::refs::PartialName),

crates/but-core/src/lib.rs

@@ -9,5 +9,6 @@ publish = false
 doctest = false
 
 [dependencies]
+gix.workspace = true
 
 [dev-dependencies]

crates/but-debugging/Cargo.toml

@@ -1,8 +1,20 @@
+use gix::bstr::ByteSlice;
 /// But Debugging contains utilities that aid in debugging gitbutler.
 /// Utilities defined inside of but-debugging should not be relied upon in
 /// tests or used in production code.
 use std::{path::Path, process::Command};
 
+/// Produce a graph of all commits reachable from `refspec`.
+pub fn commit_graph(repo: &gix::Repository, refspec: impl ToString) -> std::io::Result<String> {
+    let log = std::process::Command::new(gix::path::env::exe_invocation())
+        .current_dir(repo.path())
+        .args(["log", "--oneline", "--graph", "--decorate"])
+        .arg(refspec.to_string())
+        .output()?;
+    assert!(log.status.success());
+    Ok(log.stdout.to_str().expect("no illformed UTF-8").to_string())
+}
+
 /// Options passed to `git log`
 pub struct LogOptions {
     /// Controls whether the `--oneline` flag is passed.

crates/but-debugging/src/lib.rs

@@ -22,6 +22,7 @@ tempfile.workspace = true
 
 [dev-dependencies]
 gix-testtools.workspace = true
+but-debugging.workspace = true
 gix = {workspace = true, features = ["revision"]}
 insta = "1.42.1"
 but-core = { workspace = true, features = ["testing"] }

crates/but-rebase/Cargo.toml

@@ -1,4 +1,4 @@
-//! An API for an interactive rebase.
+//! An API for an interactive rebases, suitable for interactive, UI driven, and programmatic use.
 #![deny(rust_2018_idioms, missing_docs)]
 
 use anyhow::{anyhow, bail, Ok, Result};
@@ -19,6 +19,9 @@ pub enum RebaseStep {
         commit_id: gix::ObjectId,
         /// Optional message to use for newly produced commit
         new_message: Option<BString>,
+        // TODO: add `base: Option<ObjectId>` to allow restarting the sequence at a new base
+        //       for multi-branch rebasing. It would keep the previous cursor, to allow the last
+        //       branch to contain a pick of the merge commit on top, which it can then correctly re-merge.
     },
     /// Merge an existing commit and it's parents producing a new merge commit.
     Merge {

crates/but-rebase/src/lib.rs

@@ -1,5 +1,6 @@
-use crate::utils::{assure_stable_env, commit_graph, fixture_writable, four_commits_writable};
+use crate::utils::{assure_stable_env, fixture_writable, four_commits_writable};
 use anyhow::Result;
+use but_debugging::commit_graph;
 use but_rebase::{RebaseBuilder, RebaseStep};
 
 mod error_handling;
@@ -144,20 +145,8 @@ fn pick_the_first_commit_with_no_parents_for_squashing() -> Result<()> {
 
 pub mod utils {
     use anyhow::Result;
-    use bstr::ByteSlice;
     use gix::ObjectId;
 
-    /// Produce a graph of all commits reachable from `refspec`.
-    pub fn commit_graph(repo: &gix::Repository, refspec: impl ToString) -> Result<String> {
-        let log = std::process::Command::new(gix::path::env::exe_invocation())
-            .current_dir(repo.path())
-            .args(["log", "--oneline", "--graph", "--decorate"])
-            .arg(refspec.to_string())
-            .output()?;
-        assert!(log.status.success());
-        Ok(log.stdout.to_str().expect("no illformed UTF-8").to_string())
-    }
-
     /// Returns a fixture that may not be written to, objects will never touch disk either.
     pub fn fixture(fixture_name: &str) -> Result<gix::Repository> {
         let root = gix_testtools::scripted_fixture_read_only("rebase.sh")

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

@@ -28,6 +28,7 @@ url = { version = "2.5.4", features = ["serde"] }
 md5 = "0.7.0"
 
 [dev-dependencies]
+but-debugging.workspace = true
 gix-testtools = "0.15.0"
 gitbutler-testsupport.workspace = true
 insta = "1.42.1"

crates/but-workspace/Cargo.toml

@@ -1,14 +1,16 @@
-//! The machinery used to alter and mutate commits in various ways.
+//! The machinery used to alter and mutate commits in various ways whilst adjusting descendant commits within a [reference frame](ReferenceFrame).
 
 use anyhow::{bail, Context};
 use bstr::{BString, ByteSlice};
 use but_core::unified_diff::DiffHunk;
 use but_core::{RepositoryExt, UnifiedDiff};
+use gitbutler_stack::VirtualBranchesState;
 use gix::filter::plumbing::driver::apply::{Delay, MaybeDelayed};
 use gix::filter::plumbing::pipeline::convert::{ToGitOutcome, ToWorktreeOutcome};
 use gix::merge::tree::TreatAsUnresolved;
 use gix::objs::tree::EntryKind;
 use gix::prelude::ObjectIdExt;
+use gix::refs::transaction::PreviousValue;
 use serde::{Deserialize, Serialize};
 use std::io::Read;
 
@@ -35,6 +37,35 @@ pub enum Destination {
     AmendCommit(gix::ObjectId),
 }
 
+/// Quite literally a set of commits that surround the commit to be altered or created to help finding descendant
+/// commits that should be rewritten to integrate the new commit.
+///
+/// Or explained differently, a set of commits that helps to navigate the commit graph to steer the necessary
+/// [rewrites](but_rebase::RebaseBuilder::rebase()), keeping them linear.
+#[derive(Debug, Clone)]
+pub struct ReferenceFrame {
+    /// The commit at the top of the branch which has the parent of the new commit or the amended commit
+    /// in its ancestry.
+    pub branch_tip: gix::ObjectId,
+    /// If present, the merge commit that integrates all branches into one workspace.
+    /// Must have the [`branch_tip`](Self::branch_tip) as direct ancestor/parent.
+    pub workspace_tip: Option<gix::ObjectId>,
+    /// A set of literal references along with the commit they point to, ideally (but not necessarily) filtered to only
+    /// the commits we would have to rebase.
+    /// If a reference is unborn, it can't be listed here and needs special treatment.
+    pub references: Vec<(but_core::Reference, gix::ObjectId)>,
+}
+
+/// Identify the commit that contains the patches to be moved, along with the branch that should be rewritten.
+#[derive(Debug, Clone, Copy)]
+pub struct MoveSourceCommit {
+    /// The commit that acts as the source of all changes. Note that these changes will be *removed* from the
+    /// commit, which gets rewritten in the process.
+    pub commit_id: gix::ObjectId,
+    /// The commit at the top of the branch which has the commit that acts as source of changes in its ancestry.
+    pub branch_tip: gix::ObjectId,
+}
+
 /// A change that should be used to create a new commit or alter an existing one, along with enough information to know where to find it.
 #[derive(Debug, Default, Clone, PartialEq)]
 pub struct DiffSpec {
@@ -93,6 +124,10 @@ pub struct CreateCommitOutcome {
     pub rejected_specs: Vec<DiffSpec>,
     /// The newly created commit, or `None` if no commit could be created as all changes-requests were rejected.
     pub new_commit: Option<gix::ObjectId>,
+    /// The rewritten references `(old, new, reference)`, along with their `old` and `new` commit location, along
+    /// with the reference itself.
+    /// If `new_commit` is `None`, this array will be an empty.
+    pub references: Vec<(gix::ObjectId, gix::ObjectId, but_core::Reference)>,
 }
 
 /// Additional information about the outcome of a [`create_tree()`] call.
@@ -102,15 +137,16 @@ pub struct CreateTreeOutcome {
     /// when merging the workspace commit, or because the specified hunks didn't match exactly due to changes
     /// that happened in the meantime, or if a file without a change was specified.
     pub rejected_specs: Vec<DiffSpec>,
-    /// The newly created tree, or `None` if no commit could be created as all changes-requests were rejected.
-    pub new_tree: Option<gix::ObjectId>,
+    /// The newly created tree that acts as the destination of the changes, or `None` if no commit could be
+    /// created as all changes-requests were rejected.
+    pub destination_tree: Option<gix::ObjectId>,
 }
 
 /// Like [`create_commit()`], but lower-level and only returns a new tree, without finally associating it with a commit.
 pub fn create_tree(
     repo: &gix::Repository,
     destination: &Destination,
-    origin_commit: Option<gix::ObjectId>,
+    move_source: Option<MoveSourceCommit>,
     changes: Vec<DiffSpec>,
     context_lines: u32,
 ) -> anyhow::Result<CreateTreeOutcome> {
@@ -136,7 +172,7 @@ pub fn create_tree(
 
     let mut changes: Vec<_> = changes.into_iter().map(Ok).collect();
     let new_tree = 'retry: loop {
-        let (maybe_new_tree, actual_base_tree) = if let Some(_origin_commit) = origin_commit {
+        let (maybe_new_tree, actual_base_tree) = if let Some(_source) = move_source {
             todo!("get base tree and apply changes by cherry-picking, probably can all be done by one function, but optimizations are different")
         } else {
             let changes_base_tree = repo.head()?.id().and_then(|id| {
@@ -196,25 +232,25 @@ pub fn create_tree(
     };
     Ok(CreateTreeOutcome {
         rejected_specs: changes.into_iter().filter_map(Result::err).collect(),
-        new_tree,
+        destination_tree: new_tree,
     })
 }
 
 /// Alter the single `destination` in a given `frame` with as many `changes` as possible and write new objects into `repo`,
 /// but only if the commit succeeds.
-/// If `origin_commit` is `Some(commit)`, all changes are considered to originate from the given commit, otherwise they originate from the worktree.
+///
+/// If `move_source` is `Some(source)`, all changes are considered to originate from the given commit to move out of, otherwise they originate from the worktree.
 /// `context_lines` is the amount of lines of context included in each [`HunkHeader`], and the value that will be used to recover the existing hunks,
 /// so that the hunks can be matched.
 ///
 /// Return additional information that helps to understand to what extent the commit was created, as the commit might not contain all the [`DiffSpecs`](DiffSpec)
 /// that were requested if they failed to apply.
 ///
-/// Note that the ref pointed to by `HEAD` will be updated with the new commit if the new commits parent was pointed to by `HEAD` before. Detached heads will cause failure.
-/// If `allow_ref_change` is false, `HEAD` will never be adjusted to prevent additional side-effects.
+/// No reference is touched in the process.
 pub fn create_commit(
     repo: &gix::Repository,
     destination: Destination,
-    origin_commit: Option<gix::ObjectId>,
+    move_source: Option<MoveSourceCommit>,
     changes: Vec<DiffSpec>,
     context_lines: u32,
 ) -> anyhow::Result<CreateCommitOutcome> {
@@ -242,9 +278,9 @@ pub fn create_commit(
 
     let CreateTreeOutcome {
         rejected_specs,
-        new_tree,
-    } = create_tree(repo, &destination, origin_commit, changes, context_lines)?;
-    let new_commit = if let Some(new_tree) = new_tree {
+        destination_tree,
+    } = create_tree(repo, &destination, move_source, changes, context_lines)?;
+    let new_commit = if let Some(new_tree) = destination_tree {
         match destination {
             Destination::NewCommit {
                 message,
@@ -273,9 +309,74 @@ pub fn create_commit(
     Ok(CreateCommitOutcome {
         rejected_specs,
         new_commit,
+        references: Vec::new(),
     })
 }
 
+/// Like [`create_commit()`], but allows to also update virtual branches and git references pointing to commits
+///
+/// `frame` is used to rebase all descendants to rewrite the relevant history to include the new or amended commit.
+pub fn create_commit_and_update_refs(
+    repo: &gix::Repository,
+    branches: &mut VirtualBranchesState,
+    destination: Destination,
+    move_source: Option<MoveSourceCommit>,
+    changes: Vec<DiffSpec>,
+    context_lines: u32,
+) -> anyhow::Result<CreateCommitOutcome> {
+    let mut out = create_commit(
+        repo,
+        destination.clone(),
+        move_source,
+        changes,
+        context_lines,
+    )?;
+
+    // TODO: if move_source is used, we will have another field here.
+    let CreateCommitOutcome {
+        rejected_specs,
+        new_commit,
+        references,
+    } = &mut out;
+
+    let Some(new_commit) = new_commit else {
+        return Ok(out);
+    };
+
+    let commit_to_find = match destination {
+        Destination::NewCommit {
+            parent_commit_id, ..
+        } => parent_commit_id,
+        Destination::AmendCommit(commit) => Some(commit),
+    };
+
+    if let Some(destination_commit) = commit_to_find {
+        // Traverse all stacks in the workspace and find the one that contains the destination commit
+        // branches.list_stacks_in_workspace()
+        // but_rebase::RebaseBuilder::new()?.step
+        todo!("rewrite existing commits")
+    } else {
+        // unborn branch special case.
+        repo.reference(
+            repo.head_name()?
+                .context("unborn HEAD must contain a ref-name")?,
+            *new_commit,
+            PreviousValue::Any,
+            format!(
+                "commit (initial): {title}",
+                title = new_commit
+                    .attach(repo)
+                    .object()?
+                    .into_commit()
+                    .message()?
+                    .title
+            ),
+        )?;
+    }
+
+    Ok(out)
+}
+
 fn into_err_spec(input: &mut PossibleChange) {
     *input = match std::mem::replace(input, Ok(Default::default())) {
         // What we thought was a good change turned out to be a no-op, rejected.

crates/but-workspace/src/commit_engine/mod.rs

@@ -50,6 +50,7 @@ impl From<super::CreateCommitOutcome> for CreateCommitOutcome {
         super::CreateCommitOutcome {
             rejected_specs,
             new_commit,
+            references: _,
         }: super::CreateCommitOutcome,
     ) -> Self {
         CreateCommitOutcome {

crates/but-workspace/src/commit_engine/ui.rs

@@ -27,6 +27,7 @@ fn all_changes_and_renames_to_topmost_commit_no_parent() -> anyhow::Result<()> {
         new_commit: Some(
             Sha1(aacf6391c96a59461df0a241caad4ad24368f542),
         ),
+        references: [],
     }
     ");
     let tree = visualize_tree(&repo, &outcome)?;

crates/but-workspace/tests/workspace/commit_engine/amend_commit.rs

@@ -1,3 +1,4 @@
 mod amend_commit;
 mod new_commit;
+mod refs_update;
 mod utils;