Add a way to get a list of changed items in the worktree.

Author: Byron

Cargo.lock

@@ -12,6 +12,6 @@ doctest = false
 serde = { workspace = true, features = ["std"] }
 bstr.workspace = true
 anyhow = "1.0.95"
-gix = { workspace = true, features = ["dirwalk", "credentials", "parallel"] }
+gix = { workspace = true, features = ["dirwalk", "credentials", "parallel", "serde"] }
 walkdir = "2.5.0"
 toml.workspace = true

crates/but-core/Cargo.toml

@@ -5,25 +5,88 @@
 //!
 //! ### House-~~Rules~~ Guidance
 //!
-//! * Try hard to do write all the 'right' tests
+//! * **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.
+//! * **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
+//! * **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.
+//! * **Implement `Serialize` on utility types to facilitate transfer to the frontend**
+//!     - But don't make bigger types frontend-specific. If that is needed, create a new type in the frontend-crate that uses frontend types.
+//!     - `BString` has a `BStringForFrontend` counterpart.
+//!     - `gix::ObjectId` has a `with = gitbutler_serde::object_id` serialization module.
+//! * **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.**
+//!
+//! ### Terminology
+//!
+//! * **Worktree**
+//!     - A git worktree, i.e. the checkout of a tree that makes the tree accessible on disk.
+//! * **Workspace**
+//!     - A GitButler concept of the combination of one or more branches into one worktree. This allows
+//!       multiple branches to be perceived in one worktree, by merging multiple branches together.
+//!
 
 /// Functions related to a Git worktree, i.e. the files checked out from a repository.
 pub mod worktree {
+    use bstr::BString;
+    use serde::{Deserialize, Serialize};
     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<()> {
+    /// Identify where a [`Committable`] is from.
+    #[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+    pub enum DiffKind {
+        /// The change was detected when doing a diff between a tree and an index.
+        TreeIndex,
+        /// The change was detected when doing a diff between an index and a worktree.
+        IndexWorktree,
+    }
+
+    /// Something that fully identifies the state of a [`Committable`].
+    #[derive(Debug, Clone, Copy)]
+    pub struct CommittableState {
+        /// The content of the committable.
+        ///
+        /// If [`null`](gix::ObjectId::is_null), the current state isn't known which can happen
+        /// if this state is living in the worktree and has never been hashed.
+        pub id: gix::ObjectId,
+        /// The kind of the committable.
+        pub kind: gix::object::tree::EntryKind,
+    }
+
+    /// An entry in the worktree that changed and thus is eligible to being committed.
+    ///
+    /// It either lives (or lived) in the in `.git/index`, or in the `worktree`.
+    ///
+    /// ### Note
+    ///
+    /// For simplicity, copy-tracking is not representable right now, but `copy: bool` could be added
+    /// if needed.
+    #[derive(Debug, Clone)]
+    pub struct Committable {
+        /// If this item was renamed, this is the previous path relative to the worktree where it
+        /// was moved from.
+        pub previous_path: Option<BString>,
+        /// The *relative* path in the worktree where the entry can be found.
+        pub path: BString,
+        /// The state that was previously recorded.
+        ///
+        /// If `None`, there is no known previous value, so this is a newly added item.
+        pub previous_state: Option<CommittableState>,
+        /// The content that the entry has currently.
+        ///
+        /// If `None`, this means the entry was deleted, and no current state of it can be known.
+        pub state: Option<CommittableState>,
+    }
+
+    /// Return a list of `(DiffKind, Committable)` that live underneath `worktree_root` that changed and thus can become part of a commit.
+    ///
+    /// The [`DiffKind`] determines which diff was performed to learn about the [`Committable`].
+    pub fn committables(_worktree_root: &Path) -> anyhow::Result<Vec<(DiffKind, Committable)>> {
         todo!()
     }
 }

crates/but-core/src/lib.rs

@@ -44,6 +44,29 @@ pub mod oid_opt {
     }
 }
 
+///
+pub mod object_id {
+    use serde::{Deserialize, Deserializer, Serialize};
+    use std::str::FromStr;
+
+    /// serialize an object ID as hex-string.
+    pub fn serialize<S>(v: &gix::ObjectId, s: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        v.to_string().serialize(s)
+    }
+
+    /// deserialize an object ID from hex-string.
+    pub fn deserialize<'de, D>(d: D) -> Result<gix::ObjectId, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let hex = String::deserialize(d)?;
+        gix::ObjectId::from_str(hex.as_ref()).map_err(serde::de::Error::custom)
+    }
+}
+
 pub mod oid_vec {
     use serde::{Deserialize, Deserializer, Serialize};
 

crates/gitbutler-serde/src/lib.rs

@@ -83,6 +83,8 @@ gitbutler-edit-mode.workspace = true
 gitbutler-sync.workspace = true
 gitbutler-forge.workspace = true
 gitbutler-settings.workspace = true
+gitbutler-serde.workspace = true
+but-core.workspace = true
 open = "5"
 url = "2.5.4"
 itertools = "0.14"