Add a new crate with a sketch of the V3 staging API.

Author: Byron

Cargo.lock

@@ -1,42 +1,7 @@
 [workspace]
 members = [
-    "crates/gitbutler-tauri",
-    "crates/gitbutler-git",
-    "crates/gitbutler-watcher",
-    "crates/gitbutler-watcher/vendor/debouncer",
-    "crates/gitbutler-testsupport",
-    "crates/gitbutler-cli",
-    "crates/gitbutler-branch-actions",
-    "crates/gitbutler-sync",
-    "crates/gitbutler-oplog",
-    "crates/gitbutler-repo",
-    "crates/gitbutler-repo-actions",
-    "crates/gitbutler-command-context",
-    "crates/gitbutler-feedback",
-    "crates/gitbutler-config",
-    "crates/gitbutler-project",
-    "crates/gitbutler-user",
-    "crates/gitbutler-branch",
-    "crates/gitbutler-reference",
-    "crates/gitbutler-error",
-    "crates/gitbutler-serde",
-    "crates/gitbutler-secret",
-    "crates/gitbutler-id",
-    "crates/gitbutler-storage",
-    "crates/gitbutler-fs",
-    "crates/gitbutler-time",
-    "crates/gitbutler-commit",
-    "crates/gitbutler-tagged-string",
-    "crates/gitbutler-url",
-    "crates/gitbutler-diff",
-    "crates/gitbutler-operating-modes",
-    "crates/gitbutler-edit-mode",
-    "crates/gitbutler-cherry-pick",
-    "crates/gitbutler-oxidize",
-    "crates/gitbutler-stack",
-    "crates/gitbutler-hunk-dependency",
-    "crates/gitbutler-settings",
-    "crates/gitbutler-workspace",
+    "crates/gitbutler-*",
+    "crates/but-*"
 ]
 resolver = "2"
 
@@ -96,6 +61,7 @@ gitbutler-forge = { path = "crates/gitbutler-forge" }
 gitbutler-hunk-dependency = { path = "crates/gitbutler-hunk-dependency" }
 gitbutler-settings = { path = "crates/gitbutler-settings" }
 gitbutler-workspace = { path = "crates/gitbutler-workspace" }
+but-core = { path = "crates/but-core" }
 
 [profile.release]
 codegen-units = 1 # Compile crates one after another so the compiler can optimize better

Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "but-cli"
+version = "0.0.0"
+edition = "2021"
+authors = ["GitButler <gitbutler@gitbutler.com>"]
+publish = false
+rust-version = "1.74"
+
+[[bin]]
+name = "but-cli"
+path = "src/main.rs"
+doctest = false
+
+[dependencies]
+but-core.workspace = true
+
+clap = { version = "4.5.23", features = ["derive", "env"] }
+anyhow = "1.0.95"
+tracing-forest = { version = "0.1.6" }
+tracing-subscriber.workspace = true
+tracing.workspace = true

crates/but-cli/Cargo.toml

@@ -0,0 +1,32 @@
+use std::path::PathBuf;
+
+#[derive(Debug, clap::Parser)]
+#[clap(name = "gitbutler-cli", about = "A CLI for GitButler", version = option_env!("GIX_VERSION"))]
+pub struct Args {
+    /// Enable tracing for debug and performance information printed to stderr.
+    #[clap(short = 'd', long)]
+    pub trace: bool,
+    /// Run as if gitbutler-cli was started in PATH instead of the current working directory.
+    #[clap(short = 'C', long, default_value = ".", value_name = "PATH")]
+    pub current_dir: PathBuf,
+
+    #[clap(subcommand)]
+    pub cmd: Subcommands,
+}
+
+#[derive(Debug, clap::Subcommand)]
+pub enum Subcommands {
+    /// Update the local workspace against an updated remote or target branch.
+    Status,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn clap() {
+        use clap::CommandFactory;
+        Args::command().debug_assert();
+    }
+}

crates/but-cli/src/args.rs

@@ -0,0 +1,12 @@
+fn debug_print(this: impl std::fmt::Debug) -> anyhow::Result<()> {
+    println!("{:#?}", this);
+    Ok(())
+}
+
+pub mod status {
+    use crate::command::debug_print;
+
+    pub fn doit() -> anyhow::Result<()> {
+        debug_print("call into but-core")
+    }
+}

crates/but-cli/src/command/mod.rs

@@ -0,0 +1,39 @@
+//! A debug-CLI for making `but`-crates functionality available in real-world repositories.
+use anyhow::Result;
+
+mod args;
+use args::Args;
+
+mod command;
+
+fn main() -> Result<()> {
+    let args: Args = clap::Parser::parse();
+
+    if args.trace {
+        trace::init()?;
+    }
+    let _op_span = tracing::info_span!("cli-op").entered();
+
+    match args.cmd {
+        args::Subcommands::Status => command::status::doit(),
+    }
+}
+
+mod trace {
+    use tracing::metadata::LevelFilter;
+    use tracing_subscriber::layer::SubscriberExt;
+    use tracing_subscriber::util::SubscriberInitExt;
+    use tracing_subscriber::Layer;
+
+    pub fn init() -> anyhow::Result<()> {
+        tracing_subscriber::registry()
+            .with(
+                tracing_forest::ForestLayer::from(
+                    tracing_forest::printer::PrettyPrinter::new().writer(std::io::stderr),
+                )
+                .with_filter(LevelFilter::DEBUG),
+            )
+            .init();
+        Ok(())
+    }
+}

crates/but-cli/src/main.rs

@@ -0,0 +1,17 @@
+[package]
+name = "but-core"
+version = "0.0.0"
+edition = "2021"
+authors = ["GitButler <gitbutler@gitbutler.com>"]
+publish = false
+
+[lib]
+doctest = false
+
+[dependencies]
+serde = { workspace = true, features = ["std"] }
+bstr.workspace = true
+anyhow = "1.0.95"
+gix = { workspace = true, features = ["dirwalk", "credentials", "parallel"] }
+walkdir = "2.5.0"
+toml.workspace = true

crates/but-core/Cargo.toml

@@ -0,0 +1,29 @@
+#![deny(missing_docs, rust_2018_idioms)]
+//! The basic primitives that GitButler is built around.
+//!
+//! It also is a catch-all for code until it's worth putting it into its own crate.
+//!
+//! ### House-~~Rules~~ Guidance
+//!
+//! * Try hard to do write all the 'right' tests
+//!    - Tests should challenge the implementation, try hard to break it.
+//!    - capture *all* business requirements
+//!    - Try to avoid doing read-only filesystem fixtures with `tempdir`, instead use `gitbutler-testtools::readonly`.
+//! * minimal dependencies
+//!    - both for the crate and for parameters of functions as well.
+//!         - i.e. try to avoid 'God' structures so the function only has access to what it needs to.
+//! * The filesystem is `Sync` but we don't have atomic operations
+//!    - Let's be very careful about changes to the filesystem, must at least be on the level of Git which means `.lock` files instead of direct writes.
+//!    - If only one part of the application is supposed to change the worktree, let's protect the Application from itself by using `gitbutler::access` just like we do now.
+//! * Make it work, make it work right, and if time and profiler permits, make it work fast.
+//! * All of the above can and should be scrutinized and is there is no hard rules.
+
+/// Functions related to a Git worktree, i.e. the files checked out from a repository.
+pub mod worktree {
+    use std::path::Path;
+
+    /// Return a list of items that live underneath `worktree_root` that changed and thus can become part of a commit.
+    pub fn committable_entries(_worktree_root: &Path) -> anyhow::Result<()> {
+        todo!()
+    }
+}

crates/but-core/src/lib.rs

@@ -0,0 +1,2 @@
+#[test]
+fn itworks() {}