Merge pull request #1453 from cruessler/gix-blame

Explore gix APIs, experiment with gix-blame API

Author: Byron

Diff for: Cargo.lock

@@ -139,6 +139,7 @@ is usable to some extent.
   * [gix-shallow](https://github.com/GitoxideLabs/gitoxide/blob/main/crate-status.md#gix-shallow)
   * `gitoxide-core`
 * **very early**  _(possibly without any documentation and many rough edges)_
+  * [gix-blame](https://github.com/GitoxideLabs/gitoxide/blob/main/crate-status.md#gix-blame)
 * **idea** _(just a name placeholder)_
   * [gix-note](https://github.com/GitoxideLabs/gitoxide/blob/main/crate-status.md#gix-note)
   * [gix-fetchhead](https://github.com/GitoxideLabs/gitoxide/blob/main/crate-status.md#gix-fetchhead)

Diff for: README.md

@@ -293,7 +293,7 @@ The top-level crate that acts as hub to all functionality provided by the `gix-*
     * [x] safe with cycles and recursive configurations
     * [x] multi-line with comments and quotes
 * **promisor**
-    * It's vague, but these seems to be like index files allowing to fetch objects from a server on demand.
+    * It's vague, but these seem to be like index files allowing to fetch objects from a server on demand.
 * [x] API documentation
     * [ ] Some examples
 
@@ -361,6 +361,25 @@ Check out the [performance discussion][gix-diff-performance] as well.
 * [x] API documentation
     * [ ] Examples
 
+### gix-blame
+
+* [x] commit-annotations for a single file
+    - [ ] progress
+    - [ ] interruptibility
+    - [ ] streaming
+- [ ] support for worktree changes (creates virtual commit on top of `HEAD`) 
+- [ ] shallow-history support
+- [ ] rename tracking (track different paths through history)
+- [ ] commits to ignore
+- [ ] pass all blame-cornercases (from Git)
+* **Performance-Improvements**
+    * Without the following the performance isn't competitive with Git.
+    1. Implement custom graph walk which won't run down parents that don't have the path in question.
+    2. Implement access of trees from commit-graph and fill that information into the traversal info by default.
+    3. commit-graph with bloom filter, used to quickly check if a commit has a path.
+* [x] API documentation
+    * [ ] Examples
+
 ### gix-traverse
 
 Check out the [performance discussion][gix-traverse-performance] as well.

Diff for: crate-status.md

@@ -49,7 +49,7 @@ serde = ["gix/serde", "dep:serde_json", "dep:serde", "bytesize/serde"]
 
 [dependencies]
 # deselect everything else (like "performance") as this should be controllable by the parent application.
-gix = { version = "^0.69.1", path = "../gix", default-features = false, features = ["merge", "blob-diff", "revision", "mailmap", "excludes", "attributes", "worktree-mutation", "credentials", "interrupt", "status", "dirwalk"] }
+gix = { version = "^0.69.1", path = "../gix", default-features = false, features = ["merge", "blob-diff", "blame", "revision", "mailmap", "excludes", "attributes", "worktree-mutation", "credentials", "interrupt", "status", "dirwalk"] }
 gix-pack-for-configuration-only = { package = "gix-pack", version = "^0.56.0", path = "../gix-pack", default-features = false, features = ["pack-cache-lru-dynamic", "pack-cache-lru-static", "generate", "streaming-input"] }
 gix-transport-configuration-only = { package = "gix-transport", version = "^0.44.0", path = "../gix-transport", default-features = false }
 gix-archive-for-configuration-only = { package = "gix-archive", version = "^0.18.0", path = "../gix-archive", optional = true, features = ["tar", "tar_gz"] }

Diff for: gitoxide-core/Cargo.toml

@@ -0,0 +1,71 @@
+use gix::bstr::ByteSlice;
+use gix::config::tree;
+use std::ffi::OsStr;
+
+pub fn blame_file(
+    mut repo: gix::Repository,
+    file: &OsStr,
+    out: impl std::io::Write,
+    err: Option<&mut dyn std::io::Write>,
+) -> anyhow::Result<()> {
+    {
+        let mut config = repo.config_snapshot_mut();
+        if config.string(&tree::Core::DELTA_BASE_CACHE_LIMIT).is_none() {
+            config.set_value(&tree::Core::DELTA_BASE_CACHE_LIMIT, "100m")?;
+        }
+    }
+    let index = repo.index_or_empty()?;
+    repo.object_cache_size_if_unset(repo.compute_object_cache_size_for_tree_diffs(&index));
+
+    let file = gix::path::os_str_into_bstr(file)?;
+    let specs = repo.pathspec(
+        false,
+        [file],
+        true,
+        &index,
+        gix::worktree::stack::state::attributes::Source::WorktreeThenIdMapping.adjust_for_bare(repo.is_bare()),
+    )?;
+    // TODO: there should be a way to normalize paths without going through patterns, at least in this case maybe?
+    //       `Search` actually sorts patterns by excluding or not, all that can lead to strange results.
+    let file = specs
+        .search()
+        .patterns()
+        .map(|p| p.path().to_owned())
+        .next()
+        .expect("exactly one pattern");
+
+    let suspect = repo.head()?.peel_to_commit_in_place()?;
+    let traverse =
+        gix::traverse::commit::topo::Builder::from_iters(&repo.objects, [suspect.id], None::<Vec<gix::ObjectId>>)
+            .with_commit_graph(repo.commit_graph_if_enabled()?)
+            .build()?;
+    let mut resource_cache = repo.diff_resource_cache_for_tree_diff()?;
+    let outcome = gix::blame::file(&repo.objects, traverse, &mut resource_cache, file.as_bstr())?;
+    let statistics = outcome.statistics;
+    write_blame_entries(out, outcome)?;
+
+    if let Some(err) = err {
+        writeln!(err, "{statistics:#?}")?;
+    }
+    Ok(())
+}
+
+fn write_blame_entries(mut out: impl std::io::Write, outcome: gix::blame::Outcome) -> Result<(), std::io::Error> {
+    for (entry, lines_in_hunk) in outcome.entries_with_lines() {
+        for ((actual_lno, source_lno), line) in entry
+            .range_in_blamed_file()
+            .zip(entry.range_in_source_file())
+            .zip(lines_in_hunk)
+        {
+            write!(
+                out,
+                "{short_id} {line_no} {src_line_no} {line}",
+                line_no = actual_lno + 1,
+                src_line_no = source_lno + 1,
+                short_id = entry.commit_id.to_hex_with_len(8),
+            )?;
+        }
+    }
+
+    Ok(())
+}

Diff for: gitoxide-core/src/repository/blame.rs

@@ -21,6 +21,7 @@ pub enum PathsOrPatterns {
 pub mod archive;
 pub mod cat;
 pub use cat::function::cat;
+pub mod blame;
 pub mod commit;
 pub mod config;
 mod credential;

Diff for: gitoxide-core/src/repository/mod.rs

@@ -5,7 +5,7 @@ name = "gix-blame"
 version = "0.0.0"
 repository = "https://github.com/GitoxideLabs/gitoxide"
 license = "MIT OR Apache-2.0"
-description = "A crate of the gitoxide project dedicated implementing a 'blame' algorithm"
+description = "A crate of the gitoxide project dedicated to implementing a 'blame' algorithm"
 authors = ["Christoph Rüßler <christoph.ruessler@mailbox.org>", "Sebastian Thiel <sebastian.thiel@icloud.com>"]
 edition = "2021"
 rust-version = "1.65"
@@ -14,6 +14,19 @@ rust-version = "1.65"
 doctest = false
 
 [dependencies]
+gix-trace = { version = "^0.1.11", path = "../gix-trace" }
+gix-diff = { version = "^0.49.0", path = "../gix-diff", default-features = false, features = ["blob"] }
+gix-object = { version = "^0.46.0", path = "../gix-object" }
+gix-hash = { version = "^0.15.0", path = "../gix-hash" }
+gix-worktree = { version = "^0.38.0", path = "../gix-worktree", default-features = false, features = ["attributes"] }
+gix-traverse = { version = "^0.43.0", path = "../gix-traverse" }
+
+thiserror = "2.0.0"
 
 [dev-dependencies]
+gix-ref = { version = "^0.49.0", path = "../gix-ref" }
+gix-filter = { version = "^0.16.0", path = "../gix-filter" }
+gix-fs = { version = "^0.12.0", path = "../gix-fs" }
+gix-index = { version = "^0.37.0", path = "../gix-index" }
+gix-odb = { version = "^0.66.0", path = "../gix-odb" }
 gix-testtools = { path = "../tests/tools" }

Diff for: gix-blame/Cargo.toml

@@ -0,0 +1,30 @@
+use gix_object::bstr::BString;
+
+/// The error returned by [file()](crate::file()).
+#[derive(Debug, thiserror::Error)]
+#[allow(missing_docs)]
+pub enum Error {
+    #[error("No commit was given")]
+    EmptyTraversal,
+    #[error(transparent)]
+    BlobDiffSetResource(#[from] gix_diff::blob::platform::set_resource::Error),
+    #[error(transparent)]
+    BlobDiffPrepare(#[from] gix_diff::blob::platform::prepare_diff::Error),
+    #[error("The file to blame at '{file_path}' wasn't found in the first commit at {commit_id}")]
+    FileMissing {
+        /// The file-path to the object to blame.
+        file_path: BString,
+        /// The commit whose tree didn't contain `file_path`.
+        commit_id: gix_hash::ObjectId,
+    },
+    #[error("Couldn't find commit or tree in the object database")]
+    FindObject(#[from] gix_object::find::Error),
+    #[error("Could not find existing blob or commit")]
+    FindExistingObject(#[from] gix_object::find::existing_object::Error),
+    #[error("Could not find existing iterator over a tree")]
+    FindExistingIter(#[from] gix_object::find::existing_iter::Error),
+    #[error("Failed to obtain the next commit in the commit-graph traversal")]
+    Traverse(#[source] Box<dyn std::error::Error + Send + Sync>),
+    #[error(transparent)]
+    DiffTree(#[from] gix_diff::tree::Error),
+}

Diff for: gix-blame/src/error.rs

@@ -1,10 +1,23 @@
 //! A crate to implement an algorithm to annotate lines in tracked files with the commits that changed them.
-#![deny(rust_2018_idioms)]
+//!
+//! ### Terminology
+//!
+//! * **Source File**
+//!    - The file as it exists in `HEAD`.
+//!    - the initial state with all lines that we need to associate with a *Source File*.
+//! * **Blamed File**
+//!    - A file at a version (i.e. commit) that introduces hunks into the final 'image'.
+//! * **Suspects**
+//!    - The versions of the files that can contain hunks that we could use in the final 'image'
+//!    - multiple at the same time as the commit-graph may split up.
+//!    - turns into *Source File* once we have found an association into the *Blamed File*.
+#![deny(rust_2018_idioms, missing_docs)]
 #![forbid(unsafe_code)]
 
-#[cfg(test)]
-mod tests {
-    #[test]
-    #[ignore]
-    fn it_works() {}
-}
+mod error;
+pub use error::Error;
+mod types;
+pub use types::{BlameEntry, Outcome, Statistics};
+
+mod file;
+pub use file::function::file;

Diff for: gix-blame/src/file/function.rs

@@ -0,0 +1,207 @@
+use crate::file::function::tokens_for_diffing;
+use gix_hash::ObjectId;
+use gix_object::bstr::BString;
+use std::num::NonZeroU32;
+use std::{
+    collections::BTreeMap,
+    ops::{AddAssign, Range, SubAssign},
+};
+
+/// The outcome of [`file()`](crate::file()).
+#[derive(Debug, Default, Clone)]
+pub struct Outcome {
+    /// One entry in sequential order, to associate a hunk in the blamed file with the source commit (and its lines)
+    /// that introduced it.
+    pub entries: Vec<BlameEntry>,
+    /// A buffer with the file content of the *Blamed File*, ready for tokenization.
+    pub blob: Vec<u8>,
+    /// Additional information about the amount of work performed to produce the blame.
+    pub statistics: Statistics,
+}
+
+/// Additional information about the performed operations.
+#[derive(Debug, Default, Copy, Clone)]
+pub struct Statistics {
+    /// The amount of commits it traversed until the blame was complete.
+    pub commits_traversed: usize,
+    /// The amount of commits whose trees were extracted.
+    pub commits_to_tree: usize,
+    /// The amount of trees that were decoded to find the entry of the file to blame.
+    pub trees_decoded: usize,
+    /// The amount of fully-fledged tree-diffs to see if the filepath was added, deleted or modified.
+    pub trees_diffed: usize,
+    /// The amount of blobs there were compared to each other to learn what changed between commits.
+    /// Note that in order to diff a blob, one needs to load both versions from the database.
+    pub blobs_diffed: usize,
+}
+
+impl Outcome {
+    /// Return an iterator over each entry in [`Self::entries`], along with its lines, line by line.
+    ///
+    /// Note that [`Self::blob`] must be tokenized in exactly the same way as the tokenizer that was used
+    /// to perform the diffs, which is what this method assures.
+    pub fn entries_with_lines(&self) -> impl Iterator<Item = (BlameEntry, Vec<BString>)> + '_ {
+        use gix_diff::blob::intern::TokenSource;
+        let mut interner = gix_diff::blob::intern::Interner::new(self.blob.len() / 100);
+        let lines_as_tokens: Vec<_> = tokens_for_diffing(&self.blob)
+            .tokenize()
+            .map(|token| interner.intern(token))
+            .collect();
+        self.entries.iter().map(move |e| {
+            (
+                e.clone(),
+                lines_as_tokens[e.range_in_blamed_file()]
+                    .iter()
+                    .map(|token| BString::new(interner[*token].into()))
+                    .collect(),
+            )
+        })
+    }
+}
+
+/// Describes the offset of a particular hunk relative to the *Blamed File*.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum Offset {
+    /// The amount of lines to add.
+    Added(u32),
+    /// The amount of lines to remove.
+    Deleted(u32),
+}
+
+impl Offset {
+    /// Shift the given `range` according to our offset.
+    pub fn shifted_range(&self, range: &Range<u32>) -> Range<u32> {
+        match self {
+            Offset::Added(added) => {
+                debug_assert!(range.start >= *added, "{self:?} {range:?}");
+                Range {
+                    start: range.start - added,
+                    end: range.end - added,
+                }
+            }
+            Offset::Deleted(deleted) => Range {
+                start: range.start + deleted,
+                end: range.end + deleted,
+            },
+        }
+    }
+}
+
+impl AddAssign<u32> for Offset {
+    fn add_assign(&mut self, rhs: u32) {
+        match self {
+            Self::Added(added) => *self = Self::Added(*added + rhs),
+            Self::Deleted(deleted) => {
+                if rhs > *deleted {
+                    *self = Self::Added(rhs - *deleted);
+                } else {
+                    *self = Self::Deleted(*deleted - rhs);
+                }
+            }
+        }
+    }
+}
+
+impl SubAssign<u32> for Offset {
+    fn sub_assign(&mut self, rhs: u32) {
+        match self {
+            Self::Added(added) => {
+                if rhs > *added {
+                    *self = Self::Deleted(rhs - *added);
+                } else {
+                    *self = Self::Added(*added - rhs);
+                }
+            }
+            Self::Deleted(deleted) => *self = Self::Deleted(*deleted + rhs),
+        }
+    }
+}
+
+/// A mapping of a section of the *Blamed File* to the section in a *Source File* that introduced it.
+///
+/// Both ranges are of the same size, but may use different [starting points](Range::start). Naturally,
+/// they have the same content, which is the reason they are in what is returned by [`file()`](crate::file()).
+#[derive(Clone, Debug, PartialEq)]
+pub struct BlameEntry {
+    /// The index of the token in the *Blamed File* (typically lines) where this entry begins.
+    pub start_in_blamed_file: u32,
+    /// The index of the token in the *Source File* (typically lines) where this entry begins.
+    ///
+    /// This is possibly offset compared to `start_in_blamed_file`.
+    pub start_in_source_file: u32,
+    /// The amount of lines the hunk is spanning.
+    pub len: NonZeroU32,
+    /// The commit that introduced the section into the *Source File*.
+    pub commit_id: ObjectId,
+}
+
+impl BlameEntry {
+    /// Create a new instance.
+    pub fn new(range_in_blamed_file: Range<u32>, range_in_source_file: Range<u32>, commit_id: ObjectId) -> Self {
+        debug_assert!(
+            range_in_blamed_file.end > range_in_blamed_file.start,
+            "{range_in_blamed_file:?}"
+        );
+        debug_assert!(
+            range_in_source_file.end > range_in_source_file.start,
+            "{range_in_source_file:?}"
+        );
+        debug_assert_eq!(range_in_source_file.len(), range_in_blamed_file.len());
+
+        Self {
+            start_in_blamed_file: range_in_blamed_file.start,
+            start_in_source_file: range_in_source_file.start,
+            len: NonZeroU32::new(range_in_blamed_file.len() as u32).expect("BUG: hunks are never empty"),
+            commit_id,
+        }
+    }
+}
+
+impl BlameEntry {
+    /// Return the range of tokens this entry spans in the *Blamed File*.
+    pub fn range_in_blamed_file(&self) -> Range<usize> {
+        let start = self.start_in_blamed_file as usize;
+        start..start + self.len.get() as usize
+    }
+    /// Return the range of tokens this entry spans in the *Source File*.
+    pub fn range_in_source_file(&self) -> Range<usize> {
+        let start = self.start_in_source_file as usize;
+        start..start + self.len.get() as usize
+    }
+}
+
+pub(crate) trait LineRange {
+    fn shift_by(&self, offset: Offset) -> Self;
+}
+
+impl LineRange for Range<u32> {
+    fn shift_by(&self, offset: Offset) -> Self {
+        offset.shifted_range(self)
+    }
+}
+
+/// Tracks the hunks in the *Blamed File* that are not yet associated with the commit that introduced them.
+#[derive(Debug, PartialEq)]
+pub struct UnblamedHunk {
+    /// The range in the file that is being blamed that this hunk represents.
+    pub range_in_blamed_file: Range<u32>,
+    /// Maps a commit to the range in a source file (i.e. *Blamed File* at a revision) that is equal to `range_in_blamed_file`.
+    pub suspects: BTreeMap<ObjectId, Range<u32>>,
+}
+
+#[derive(Debug)]
+pub(crate) enum Either<T, U> {
+    Left(T),
+    Right(U),
+}
+
+/// A single change between two blobs, or an unchanged region.
+#[derive(Debug, PartialEq)]
+pub enum Change {
+    /// A range of tokens that wasn't changed.
+    Unchanged(Range<u32>),
+    /// `(added_line_range, num_deleted_in_before)`
+    AddedOrReplaced(Range<u32>, u32),
+    /// `(line_to_start_deletion_at, num_deleted_in_before)`
+    Deleted(u32, u32),
+}

Diff for: gix-blame/src/file/mod.rs

@@ -1,4 +1,271 @@
+use std::path::PathBuf;
+
+use gix_hash::ObjectId;
+use gix_object::bstr;
+
+struct Baseline<'a> {
+    lines: bstr::Lines<'a>,
+}
+
+mod baseline {
+    use std::path::Path;
+
+    use gix_blame::BlameEntry;
+    use gix_hash::ObjectId;
+    use gix_ref::bstr::ByteSlice;
+
+    use super::Baseline;
+
+    // These fields are used by `git` in its porcelain output.
+    const HEADER_FIELDS: [&str; 12] = [
+        // https://github.com/git/git/blob/6258f68c3c1092c901337895c864073dcdea9213/builtin/blame.c#L256-L280
+        "author",
+        "author-mail",
+        "author-time",
+        "author-tz",
+        "committer",
+        "committer-mail",
+        "committer-time",
+        "committer-tz",
+        "summary",
+        "boundary",
+        // https://github.com/git/git/blob/6258f68c3c1092c901337895c864073dcdea9213/builtin/blame.c#L239-L248
+        "previous",
+        "filename",
+    ];
+
+    fn is_known_header_field(field: &&str) -> bool {
+        HEADER_FIELDS.contains(field)
+    }
+
+    impl Baseline<'_> {
+        pub fn collect(baseline_path: impl AsRef<Path>) -> std::io::Result<Vec<BlameEntry>> {
+            let content = std::fs::read(baseline_path)?;
+
+            Ok(Baseline { lines: content.lines() }.collect())
+        }
+    }
+
+    impl Iterator for Baseline<'_> {
+        type Item = BlameEntry;
+
+        fn next(&mut self) -> Option<Self::Item> {
+            let mut ranges = None;
+            let mut commit_id = gix_hash::Kind::Sha1.null();
+            let mut skip_lines: u32 = 0;
+
+            for line in self.lines.by_ref() {
+                if line.starts_with(b"\t") {
+                    // Each group consists of a header and one or more lines. We break from the
+                    // loop, thus returning a `BlameEntry` from `next` once we have seen the number
+                    // of lines starting with "\t" as indicated in the group’s header.
+                    skip_lines -= 1;
+
+                    if skip_lines == 0 {
+                        break;
+                    } else {
+                        continue;
+                    }
+                }
+
+                let fields: Vec<&str> = line.to_str().unwrap().split(' ').collect();
+                if fields.len() == 4 {
+                    // We’re possibly dealing with a group header.
+                    // If we can’t parse the first field as an `ObjectId`, we know this is not a
+                    // group header, so we continue. This can yield false positives, but for
+                    // testing purposes, we don’t bother.
+                    commit_id = match ObjectId::from_hex(fields[0].as_bytes()) {
+                        Ok(id) => id,
+                        Err(_) => continue,
+                    };
+
+                    let line_number_in_source_file = fields[1].parse::<u32>().unwrap();
+                    let line_number_in_final_file = fields[2].parse::<u32>().unwrap();
+                    // The last field indicates the number of lines this group contains info for
+                    // (this is not equal to the number of lines in git blame’s porcelain output).
+                    let number_of_lines_in_group = fields[3].parse::<u32>().unwrap();
+
+                    skip_lines = number_of_lines_in_group;
+
+                    let source_range =
+                        (line_number_in_source_file - 1)..(line_number_in_source_file + number_of_lines_in_group - 1);
+                    let blame_range =
+                        (line_number_in_final_file - 1)..(line_number_in_final_file + number_of_lines_in_group - 1);
+                    assert!(ranges.is_none(), "should not overwrite existing ranges");
+                    ranges = Some((blame_range, source_range));
+                } else if !is_known_header_field(&fields[0]) && ObjectId::from_hex(fields[0].as_bytes()).is_err() {
+                    panic!("unexpected line: '{:?}'", line.as_bstr());
+                }
+            }
+
+            let Some((range_in_blamed_file, range_in_source_file)) = ranges else {
+                // No new lines were parsed, so we assume the iterator is finished.
+                return None;
+            };
+            Some(BlameEntry::new(range_in_blamed_file, range_in_source_file, commit_id))
+        }
+    }
+}
+
+struct Fixture {
+    odb: gix_odb::Handle,
+    resource_cache: gix_diff::blob::Platform,
+    commits: Vec<Result<gix_traverse::commit::Info, gix_traverse::commit::topo::Error>>,
+}
+
+impl Fixture {
+    fn new() -> gix_testtools::Result<Fixture> {
+        Self::for_worktree_path(fixture_path())
+    }
+
+    fn for_worktree_path(worktree_path: PathBuf) -> gix_testtools::Result<Fixture> {
+        use gix_ref::store::WriteReflog;
+
+        let store = gix_ref::file::Store::at(
+            worktree_path.join(".git"),
+            gix_ref::store::init::Options {
+                write_reflog: WriteReflog::Disable,
+                ..Default::default()
+            },
+        );
+        let odb = gix_odb::at(worktree_path.join(".git/objects"))?;
+
+        let mut reference = gix_ref::file::Store::find(&store, "HEAD")?;
+
+        // Needed for `peel_to_id_in_place`.
+        use gix_ref::file::ReferenceExt;
+
+        let head_id = reference.peel_to_id_in_place(&store, &odb)?;
+
+        let commits: Vec<_> = gix_traverse::commit::topo::Builder::from_iters(&odb, [head_id], None::<Vec<ObjectId>>)
+            .build()?
+            .collect();
+
+        let git_dir = worktree_path.join(".git");
+        let index = gix_index::File::at(git_dir.join("index"), gix_hash::Kind::Sha1, false, Default::default())?;
+        let stack = gix_worktree::Stack::from_state_and_ignore_case(
+            worktree_path.clone(),
+            false,
+            gix_worktree::stack::State::AttributesAndIgnoreStack {
+                attributes: Default::default(),
+                ignore: Default::default(),
+            },
+            &index,
+            index.path_backing(),
+        );
+        let capabilities = gix_fs::Capabilities::probe(&git_dir);
+        let resource_cache = gix_diff::blob::Platform::new(
+            Default::default(),
+            gix_diff::blob::Pipeline::new(
+                gix_diff::blob::pipeline::WorktreeRoots {
+                    old_root: None,
+                    new_root: None,
+                },
+                gix_filter::Pipeline::new(Default::default(), Default::default()),
+                vec![],
+                gix_diff::blob::pipeline::Options {
+                    large_file_threshold_bytes: 0,
+                    fs: capabilities,
+                },
+            ),
+            gix_diff::blob::pipeline::Mode::ToGit,
+            stack,
+        );
+        Ok(Fixture {
+            odb,
+            resource_cache,
+            commits,
+        })
+    }
+}
+
+macro_rules! mktest {
+    ($name:ident, $case:expr, $number_of_lines:literal) => {
+        #[test]
+        fn $name() -> gix_testtools::Result<()> {
+            let Fixture {
+                odb,
+                mut resource_cache,
+                commits,
+            } = Fixture::new()?;
+
+            let lines_blamed = gix_blame::file(
+                &odb,
+                commits,
+                &mut resource_cache,
+                format!("{}.txt", $case).as_str().into(),
+            )?
+            .entries;
+
+            assert_eq!(lines_blamed.len(), $number_of_lines);
+
+            let git_dir = fixture_path().join(".git");
+            let baseline = Baseline::collect(git_dir.join(format!("{}.baseline", $case)))?;
+
+            assert_eq!(baseline.len(), $number_of_lines);
+            assert_eq!(lines_blamed, baseline);
+            Ok(())
+        }
+    };
+}
+
+mktest!(simple_case, "simple", 4);
+mktest!(multiline_hunks, "multiline-hunks", 3);
+mktest!(deleted_lines, "deleted-lines", 1);
+mktest!(deleted_lines_multiple_hunks, "deleted-lines-multiple-hunks", 2);
+mktest!(changed_lines, "changed-lines", 1);
+mktest!(
+    changed_line_between_unchanged_lines,
+    "changed-line-between-unchanged-lines",
+    3
+);
+mktest!(added_lines, "added-lines", 2);
+mktest!(added_lines_around, "added-lines-around", 3);
+mktest!(switched_lines, "switched-lines", 4);
+mktest!(added_line_before_changed_line, "added-line-before-changed-line", 3);
+mktest!(same_line_changed_twice, "same-line-changed-twice", 2);
+mktest!(coalesce_adjacent_hunks, "coalesce-adjacent-hunks", 1);
+
+mktest!(resolved_conflict, "resolved-conflict", 2);
+mktest!(file_in_one_chain_of_ancestors, "file-in-one-chain-of-ancestors", 1);
+mktest!(
+    different_file_in_another_chain_of_ancestors,
+    "different-file-in-another-chain-of-ancestors",
+    1
+);
+mktest!(file_only_changed_in_branch, "file-only-changed-in-branch", 2);
+
+/// As of 2024-09-24, these tests are expected to fail.
+///
+/// Context: https://github.com/Byron/gitoxide/pull/1453#issuecomment-2371013904
 #[test]
-fn it_works() {
-    let _worktree = gix_testtools::scripted_fixture_read_only("make_blame_repo.sh").unwrap();
+#[should_panic = "empty-lines-myers"]
+fn diff_disparity() {
+    for case in ["empty-lines-myers", "empty-lines-histogram"] {
+        let Fixture {
+            odb,
+            mut resource_cache,
+            commits,
+        } = Fixture::new().unwrap();
+
+        let lines_blamed = gix_blame::file(
+            &odb,
+            commits,
+            &mut resource_cache,
+            format!("{case}.txt").as_str().into(),
+        )
+        .unwrap()
+        .entries;
+
+        assert_eq!(lines_blamed.len(), 5);
+
+        let git_dir = fixture_path().join(".git");
+        let baseline = Baseline::collect(git_dir.join(format!("{case}.baseline"))).unwrap();
+
+        assert_eq!(lines_blamed, baseline, "{case}");
+    }
+}
+
+fn fixture_path() -> PathBuf {
+    gix_testtools::scripted_fixture_read_only("make_blame_repo.sh").unwrap()
 }

Diff for: gix-blame/src/file/tests.rs

@@ -1,23 +1,206 @@
 #!/usr/bin/env bash
 set -eu -o pipefail
 
-
 git init -q
+git config --local diff.algorithm histogram
+
 git config merge.ff false
 
 git checkout -q -b main
-git commit -q --allow-empty -m c1
-git tag at-c1
-git commit -q --allow-empty -m c2
-git commit -q --allow-empty -m c3
-git commit -q --allow-empty -m c4
-
-git checkout -q -b branch1
-git commit -q --allow-empty -m b1c1
-git tag at-b1c1
-git commit -q --allow-empty -m b1c2
-
-git checkout -q main
-git commit -q --allow-empty -m c5
-git tag at-c5
-git merge branch1 -m m1b1
+
+echo "line 1" >> simple.txt
+git add simple.txt
+git commit -q -m c1
+
+echo -e "line 1\nline 2\nline 3" >> multiline-hunks.txt
+git add multiline-hunks.txt
+git commit -q -m c1.1
+
+echo -e "line 1\nline 2" > changed-lines.txt
+echo -e "line 1\nline 2\nline 3\nline 4\nline 5\nline 6" >> changed-line-between-unchanged-lines.txt
+git add changed-lines.txt
+git add changed-line-between-unchanged-lines.txt
+git commit -q -m c1.2
+
+echo "line 2" >> added-lines.txt
+echo "line 2" >> added-lines-around.txt
+echo -e "line 1\nline 2" > coalesce-adjacent-hunks.txt
+git add added-lines.txt
+git add added-lines-around.txt
+git add coalesce-adjacent-hunks.txt
+git commit -q -m c1.3
+
+echo "line 2" >> simple.txt
+git add simple.txt
+git commit -q -m c2
+
+echo -e "line 4\nline 5\nline 6" >> multiline-hunks.txt
+git add multiline-hunks.txt
+git commit -q -m c2.1
+
+echo -e "line 1\nline 2\nline 3\nline 4\nline 5\nline 6" >> deleted-lines.txt
+echo -e "line 1\nline 2\nline 3\nline 4\nline 5\nline 6" >> deleted-lines-multiple-hunks.txt
+git add deleted-lines.txt
+git add deleted-lines-multiple-hunks.txt
+git commit -q -m c2.2
+
+echo -e "line 1\nline 2\nline 3" > added-line-before-changed-line.txt
+git add added-line-before-changed-line.txt
+git commit -q -m c2.3
+
+echo -e "line 1\nline 2" > same-line-changed-twice.txt
+echo -e "line 1\nline in between\nline 2" > coalesce-adjacent-hunks.txt
+git add same-line-changed-twice.txt
+git add coalesce-adjacent-hunks.txt
+git commit -q -m c2.4
+
+echo "line 3" >> simple.txt
+git add simple.txt
+git commit -q -m c3
+
+echo -e "line 3\nline 4" > deleted-lines.txt
+echo -e "line 2\nline 4" > deleted-lines-multiple-hunks.txt
+git add deleted-lines.txt
+git add deleted-lines-multiple-hunks.txt
+git commit -q -m c3.1
+
+echo -e "line 3\nline 4" > changed-lines.txt
+echo -e "line 1\nline 2\nline 3 changed\nline 4\nline 5\nline 6" > changed-line-between-unchanged-lines.txt
+git add changed-lines.txt
+git add changed-line-between-unchanged-lines.txt
+git commit -q -m c3.2
+
+echo -e "line 2\nline 3" > added-line-before-changed-line.txt
+echo -e "line 1\nline 2" > coalesce-adjacent-hunks.txt
+git add added-line-before-changed-line.txt
+git add coalesce-adjacent-hunks.txt
+git commit -q -m c3.3
+
+echo -e "line 1\nline 2 changed" > same-line-changed-twice.txt
+git add same-line-changed-twice.txt
+git commit -q -m c3.4
+
+echo "line 4" >> simple.txt
+git add simple.txt
+git commit -q -m c4
+
+echo -e "line 7\nline 8\nline 9" >> multiline-hunks.txt
+git add multiline-hunks.txt
+git commit -q -m c4.1
+
+echo -e "line 1\nline 3\nline 2\nline 4" > switched-lines.txt
+git add switched-lines.txt
+git commit -q -m c4.2
+
+echo -e "line 2 changed\nline 3" > added-line-before-changed-line.txt
+git add added-line-before-changed-line.txt
+git commit -q -m c4.3
+
+echo -e "line 1\nline 2 changed a second time" > same-line-changed-twice.txt
+git add same-line-changed-twice.txt
+git commit -q -m c4.4
+
+echo -e "  line 1\n\n  line 2\n\n  line 3" > empty-lines-histogram.txt
+cp empty-lines-histogram.txt empty-lines-myers.txt
+git add empty-lines-histogram.txt empty-lines-myers.txt
+git commit -q -m c4.5
+
+echo -e "line 0\nline 1\nline 2" > added-lines.txt
+echo -e "line 0\nline 1\nline 2\nline 3" > added-lines-around.txt
+git add added-lines.txt
+git add added-lines-around.txt
+git commit -q -m c5
+
+echo -e "line 4" > deleted-lines.txt
+git add deleted-lines.txt
+git commit -q -m c5.1
+
+echo -e "line 1\nline 2\nline 3\nline 4" > switched-lines.txt
+git add switched-lines.txt
+git commit -q -m c5.2
+
+echo -e "line 1\nline 2 changed\nline 3" > added-line-before-changed-line.txt
+git add added-line-before-changed-line.txt
+git commit -q -m c5.3
+
+echo -e "  line 1\n\n  line in between\n\n  line 2\n\n  line in between\n\n  line 3" > empty-lines-histogram.txt
+cp empty-lines-histogram.txt empty-lines-myers.txt
+git add empty-lines-histogram.txt empty-lines-myers.txt
+git commit -q -m c5.4
+
+# The commit history created by the commits above this line is linear, it only
+# contains commits that have exactly one parent.
+# Below this line, there’s also commits that have more than one parent.
+
+echo -e "line 1 original\nline 2\n line 3" > resolved-conflict.txt
+git add resolved-conflict.txt
+git commit -q -m c6
+
+echo -e "line 1 changed\nline 2\n line 3" > resolved-conflict.txt
+git add resolved-conflict.txt
+git commit -q -m c7
+
+git checkout -b different-branch-to-create-a-conflict
+git reset --hard HEAD~1
+
+echo -e "line 1 changed in a different way\nline 2\n line 3" > resolved-conflict.txt
+git add resolved-conflict.txt
+git commit -q -m c8
+
+git checkout main
+git merge different-branch-to-create-a-conflict || true
+
+echo -e "line 1 conflict resolved\nline 2\n line 3" > resolved-conflict.txt
+git add resolved-conflict.txt
+git commit -q -m c9
+
+echo -e "line 1\nline 2\n line 3" > file-in-one-chain-of-ancestors.txt
+git add file-in-one-chain-of-ancestors.txt
+git commit -q -m c10
+
+git checkout -b different-branch-that-does-not-contain-file
+git reset --hard HEAD~1
+
+echo -e "line 4\nline 5\n line 6" > different-file-in-another-chain-of-ancestors.txt
+git add different-file-in-another-chain-of-ancestors.txt
+git commit -q -m c11
+
+git checkout main
+git merge different-branch-that-does-not-contain-file || true
+
+echo -e "line 1\nline 2\n line 3" > file-only-changed-in-branch.txt
+git add file-only-changed-in-branch.txt
+git commit -q -m c12
+
+git checkout -b branch-that-has-one-commit
+
+echo -e "line 1 changed\nline 2\n line 3" > file-only-changed-in-branch.txt
+git add file-only-changed-in-branch.txt
+git commit -q -m c13
+
+git checkout main
+git merge branch-that-has-one-commit || true
+
+git blame --porcelain simple.txt > .git/simple.baseline
+git blame --porcelain multiline-hunks.txt > .git/multiline-hunks.baseline
+git blame --porcelain deleted-lines.txt > .git/deleted-lines.baseline
+git blame --porcelain deleted-lines-multiple-hunks.txt > .git/deleted-lines-multiple-hunks.baseline
+git blame --porcelain changed-lines.txt > .git/changed-lines.baseline
+git blame --porcelain changed-line-between-unchanged-lines.txt > .git/changed-line-between-unchanged-lines.baseline
+git blame --porcelain added-lines.txt > .git/added-lines.baseline
+git blame --porcelain added-lines-around.txt > .git/added-lines-around.baseline
+git blame --porcelain switched-lines.txt > .git/switched-lines.baseline
+git blame --porcelain added-line-before-changed-line.txt > .git/added-line-before-changed-line.baseline
+git blame --porcelain same-line-changed-twice.txt > .git/same-line-changed-twice.baseline
+git blame --porcelain coalesce-adjacent-hunks.txt > .git/coalesce-adjacent-hunks.baseline
+
+git blame --porcelain resolved-conflict.txt > .git/resolved-conflict.baseline
+git blame --porcelain file-in-one-chain-of-ancestors.txt > .git/file-in-one-chain-of-ancestors.baseline
+git blame --porcelain different-file-in-another-chain-of-ancestors.txt > .git/different-file-in-another-chain-of-ancestors.baseline
+git blame --porcelain file-only-changed-in-branch.txt > .git/file-only-changed-in-branch.baseline
+
+git blame --porcelain empty-lines-histogram.txt > .git/empty-lines-histogram.baseline
+
+git config --local diff.algorithm myers
+
+git blame --porcelain empty-lines-myers.txt > .git/empty-lines-myers.baseline

Diff for: gix-blame/src/lib.rs

@@ -141,6 +141,9 @@ blob-diff = ["gix-diff/blob", "attributes"]
 ## Add functions to specifically merge files, using the standard three-way merge that git offers.
 merge = ["tree-editor", "blob-diff", "dep:gix-merge", "attributes"]
 
+## Add blame command similar to `git blame`.
+blame = ["dep:gix-blame"]
+
 ## Make it possible to turn a tree into a stream of bytes, which can be decoded to entries and turned into various other formats.
 worktree-stream = ["gix-worktree-stream", "attributes"]
 
@@ -371,6 +374,7 @@ gix-command = { version = "^0.4.0", path = "../gix-command", optional = true }
 
 gix-worktree-stream = { version = "^0.18.0", path = "../gix-worktree-stream", optional = true }
 gix-archive = { version = "^0.18.0", path = "../gix-archive", default-features = false, optional = true }
+gix-blame = { version= "^0.0.0", path ="../gix-blame", optional = true }
 
 # For communication with remotes
 gix-protocol = { version = "^0.47.0", path = "../gix-protocol" }

Diff for: gix-blame/src/types.rs

@@ -95,6 +95,8 @@
 pub use gix_actor as actor;
 #[cfg(feature = "attributes")]
 pub use gix_attributes as attrs;
+#[cfg(feature = "blame")]
+pub use gix_blame as blame;
 #[cfg(feature = "command")]
 pub use gix_command as command;
 pub use gix_commitgraph as commitgraph;

Diff for: gix-blame/tests/blame.rs

@@ -1533,6 +1533,17 @@ pub fn main() -> Result<()> {
                 },
             ),
         },
+        Subcommands::Blame { statistics, file } => prepare_and_run(
+            "blame",
+            trace,
+            verbose,
+            progress,
+            progress_keep_open,
+            None,
+            move |_progress, out, err| {
+                core::repository::blame::blame_file(repository(Mode::Lenient)?, &file, out, statistics.then_some(err))
+            },
+        ),
         Subcommands::Completions { shell, out_dir } => {
             let mut app = Args::command();
 

Diff for: gix-blame/tests/fixtures/make_blame_repo.sh

@@ -151,6 +151,14 @@ pub enum Subcommands {
     /// Subcommands that need no git repository to run.
     #[clap(subcommand)]
     Free(free::Subcommands),
+    /// Blame lines in a file
+    Blame {
+        /// Print additional statistics to help understanding performance.
+        #[clap(long, short = 's')]
+        statistics: bool,
+        /// The file to create the blame information for.
+        file: std::ffi::OsString,
+    },
     /// Generate shell completions to stdout or a directory.
     #[clap(visible_alias = "generate-completions", visible_alias = "shell-completions")]
     Completions {