Provide a non-legacy version of branch apply

While at it, make it clearer from dependencies what's legacy and what not,
similar to the `but` (CLI) crate.

Author: Byron

Cargo.lock

@@ -22,12 +22,13 @@ tauri = ["dep:tauri"]
 path-bytes = ["dep:bstr"]
 ## Make legacy functionality available.
 legacy = [
+    "but-ctx/legacy",
+    "but-workspace/legacy",
     "dep:gitbutler-user",
     "dep:gitbutler-project",
     "dep:gitbutler-branch",
     "dep:gitbutler-branch-actions",
     "dep:gitbutler-commit",
-    "dep:but-ctx",
     "dep:gitbutler-reference",
     "dep:gitbutler-stack",
     "dep:gitbutler-repo",
@@ -36,35 +37,50 @@ legacy = [
     "dep:gitbutler-operating-modes",
     "dep:gitbutler-sync",
     "dep:gitbutler-oplog",
+    "dep:but-action",
+    "dep:but-hunk-assignment",
+    "dep:but-hunk-dependency",
+    "dep:but-claude",
+    "dep:but-rules",
+    "dep:but-gerrit",
+    "dep:but-worktrees",
 ]
 
 
 [dependencies]
+but-serde.workspace = true
+but-path.workspace = true
+but-api-macros.workspace = true
+but-oxidize.workspace = true
+but-error.workspace = true
+but-core.workspace = true
+but-graph.workspace = true
+but-ctx.workspace = true
+but-workspace.workspace = true
 but-settings.workspace = true
-but-github = { workspace = true, features = ["legacy"] }
 but-secret.workspace = true
-but-workspace = { workspace = true, features = ["legacy"] }
-but-worktrees.workspace = true
-but-core.workspace = true
-but-gerrit.workspace = true
-but-hunk-assignment.workspace = true
-but-action.workspace = true
-but-api-macros.workspace = true
 but-rebase.workspace = true
-but-serde.workspace = true
-but-graph.workspace = true
-but-meta = { workspace = true, features = ["legacy"] }
-but-claude.workspace = true
 but-cherry-apply.workspace = true
-but-hunk-dependency.workspace = true
-but-path.workspace = true
-but-forge-storage.workspace = true
-but-error.workspace = true
 but-db.workspace = true
-but-rules.workspace = true
-but-oxidize.workspace = true
 but-forge.workspace = true
-but-ctx = {workspace = true, optional = true}
+but-forge-storage.workspace = true
+# needs `gitbutler_user::User`, which can probably be ported over.
+but-github = { workspace = true, features = ["legacy"] }
+# 'legacy' is needed while we only have `virtual-branches.toml`
+but-meta = { workspace = true, features = ["legacy"] }
+# 'legacy' is needed while this is only a sketch of what the oplog could be.
+# For single-branch testing, we also want the oplog and just take it as it is.
+but-oplog = { workspace = true, features = ["legacy"] }
+
+# What follows is *basically* newly written crates that are built on top of legacy,
+# so need some refactoring/rethinking to become usable.
+but-action = { workspace = true, optional = true }
+but-hunk-assignment = { workspace = true, optional = true }
+but-hunk-dependency = { workspace = true, optional = true }
+but-claude = { workspace = true, optional = true }
+but-rules = { workspace = true, optional = true }
+but-gerrit = { workspace = true, optional = true }
+but-worktrees = { workspace = true, optional = true }
 
 gitbutler-user = {workspace = true, optional = true}
 gitbutler-project = {workspace = true, optional = true}

crates/but-api/Cargo.toml

@@ -0,0 +1,56 @@
+use but_core::worktree::checkout::UncommitedWorktreeChanges;
+use but_oplog::legacy::{OperationKind, SnapshotDetails, Trailer};
+use but_workspace::branch::OnWorkspaceMergeConflict;
+use but_workspace::branch::apply::{WorkspaceMerge, WorkspaceReferenceNaming};
+
+/// Just like [apply_without_oplog()] but runs application-specific side effects, typically undo-queue and oplog settings.
+pub fn apply_without_oplog(
+    ctx: &but_ctx::Context,
+    existing_branch: &gix::refs::FullNameRef,
+) -> anyhow::Result<but_workspace::branch::apply::Outcome<'static>> {
+    let mut guard = ctx.exclusive_worktree_access();
+    let (repo, mut meta, graph) =
+        ctx.graph_and_meta_mut_and_repo_from_head(guard.write_permission())?;
+    let ws = graph.to_workspace()?;
+    let out = but_workspace::branch::apply(
+        existing_branch,
+        &ws,
+        &repo,
+        &mut meta,
+        // NOTE: Options can later be passed as parameter, or we have a separate function for that.
+        //       Showing them off here while leaving defaults.
+        but_workspace::branch::apply::Options {
+            workspace_merge: WorkspaceMerge::default(),
+            on_workspace_conflict: OnWorkspaceMergeConflict::default(),
+            workspace_reference_naming: WorkspaceReferenceNaming::default(),
+            uncommitted_changes: UncommitedWorktreeChanges::default(),
+            order: None,
+            new_stack_id: None,
+        },
+    )?
+    .into_owned();
+    Ok(out)
+}
+
+/// Apply `existing_branch` to the workspace in the repository that `ctx` refers to, or create the workspace with default name.
+// TODO: generate this with an improved `api_cmd_tauri` macro.
+pub fn apply(
+    ctx: &but_ctx::Context,
+    existing_branch: &gix::refs::FullNameRef,
+) -> anyhow::Result<but_workspace::branch::apply::Outcome<'static>> {
+    // NOTE: since this is optional by nature, the same would be true if snapshotting/undo would be disabled via `ctx` app settings, for instance.
+    let maybe_oplog_entry = but_oplog::UnmaterializedOplogSnapshot::from_details(
+        ctx,
+        SnapshotDetails::new(OperationKind::CreateBranch).with_trailers(vec![Trailer {
+            key: "name".into(),
+            value: existing_branch.to_string(),
+        }]),
+    )
+    .ok();
+
+    let res = apply_without_oplog(ctx, existing_branch);
+    if let Some(snapshot) = maybe_oplog_entry.filter(|_| res.is_ok()) {
+        snapshot.commit(ctx).ok();
+    }
+    res
+}

crates/but-api/src/branch.rs

@@ -1,4 +1,5 @@
-//! In place of commands.rs
+// TODO: everything should be fully documented.
+#![allow(missing_docs)]
 use anyhow::Result;
 use but_api_macros::api_cmd_tauri;
 use but_github::{AuthStatusResponse, AuthenticatedUser, Verification};

crates/but-api/src/github.rs

@@ -1,3 +1,4 @@
+//! JSON types and utilities to produce decent JSON from API types.
 pub use error::{Error, ToJsonError, UnmarkedError};
 use gix::refs::Target;
 use schemars::{self, JsonSchema};
@@ -195,7 +196,9 @@ mod error {
         }
     }
 
+    /// A utility to convert any `Result<T, impl std::error::Error>` into a [JSON-Error](Error).
     pub trait ToJsonError<T> {
+        /// Convert this instance into a Result<T, [JSON-Error](Error)>.
         fn to_json_error(self) -> Result<T, Error>;
     }
 

crates/but-api/src/json.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 //! Legacy data structures and functionality tied to `gitbutler-*` crates.
 //!
 pub mod askpass;

crates/but-api/src/legacy/mod.rs

@@ -6,12 +6,16 @@
 //! on this level.
 //! Lower-level crates like `but-workspace` won't use filesystem-based locking beyond what Git offers natively.
 #![forbid(unsafe_code)]
+#![deny(missing_docs)]
 
 #[cfg(feature = "legacy")]
 pub mod legacy;
 
 pub mod github;
 
+/// Functions that take a branch as input.
+pub mod branch;
+
 /// Types meant to be serialised to JSON, without degenerating information despite the need to be UTF-8 encodable.
 /// EXPERIMENTAL
 pub mod json;

crates/but-api/src/lib.rs

@@ -51,6 +51,7 @@
 //! with the restore point.
 //!
 //! Non-legacy commands can use the [`UnmaterializedOplogSnapshot`] utility to insert the snapshot into the log on successful effects.
+#![forbid(unsafe_code, missing_docs)]
 
 /// This is just a sketch for an in-memory snapshot that isn't observable through the on-disk repository.
 /// It will be committed only if the main effect of a function was successfully applied.
@@ -61,10 +62,17 @@ pub struct UnmaterializedOplogSnapshot {
     /// The tree containing all snapshot information.
     #[cfg(feature = "legacy")]
     tree_id: gix::ObjectId,
+    /// Details to pass when committing the snapshot.
     #[cfg(feature = "legacy")]
     details: gitbutler_oplog::entry::SnapshotDetails,
 }
 
+/// legacy types for easy of use, all provided by `gitbutler-oplog`.
+#[cfg(feature = "legacy")]
+pub mod legacy {
+    pub use gitbutler_oplog::entry::{OperationKind, SnapshotDetails, Trailer};
+}
+
 #[cfg(feature = "legacy")]
 mod oplog_snapshot {
     use crate::UnmaterializedOplogSnapshot;

crates/but-oplog/src/lib.rs

@@ -32,6 +32,27 @@ impl Outcome<'_> {
     }
 }
 
+impl<'a> Outcome<'a> {
+    /// Convert this instance into a fully-owned one.
+    pub fn into_owned(self) -> Outcome<'static> {
+        let Outcome {
+            graph,
+            applied_branches,
+            workspace_ref_created,
+            workspace_merge,
+            conflicting_stack_ids,
+        } = self;
+
+        Outcome {
+            graph: Cow::Owned(graph.into_owned()),
+            applied_branches,
+            workspace_ref_created,
+            workspace_merge,
+            conflicting_stack_ids,
+        }
+    }
+}
+
 impl std::fmt::Debug for Outcome<'_> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         let Outcome {
@@ -137,6 +158,7 @@ pub(crate) mod function {
 
     /// 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.
+    /// The changed workspace will be checked out.
     /// If `branch` is a remote tracking branch, we will instead apply the local tracking branch if it exists or fail otherwise.
     /// Otherwise, add it to the existing `workspace`, and update its metadata accordingly.
     /// **This means that the contents of `branch` is observable from the new state of `repo`**.