feat: add gix blame to the CLI

That way it's possible to see the `blame` result of any file in the
repository.

Co-authored-by: Sebastian Thiel <[email protected]>

Author: cruessler

README.md

@@ -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)

crate-status.md

@@ -361,6 +361,15 @@ Check out the [performance discussion][gix-diff-performance] as well.
 * [x] API documentation
     * [ ] Examples
 
+### gix-blame
+
+* [ ] commit-annotations for a single file
+    - [ ] progress
+    - [ ] interruptability
+    - [ ] streaming
+* [x] API documentation
+    * [ ] Examples
+
 ### gix-traverse
 
 Check out the [performance discussion][gix-traverse-performance] as well.

gitoxide-core/Cargo.toml

@@ -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"] }

gitoxide-core/src/repository/blame.rs

@@ -0,0 +1,62 @@
+use std::{ffi::OsStr, path::PathBuf, str::Lines};
+
+use anyhow::anyhow;
+use gix::bstr::BStr;
+
+pub fn blame_file(mut repo: gix::Repository, file: &OsStr, out: impl std::io::Write) -> anyhow::Result<()> {
+    repo.object_cache_size_if_unset(repo.compute_object_cache_size_for_tree_diffs(&**repo.index_or_empty()?));
+
+    let suspect = repo.head()?.peel_to_commit_in_place()?;
+    let traverse: Vec<_> =
+        gix::traverse::commit::topo::Builder::from_iters(&repo.objects, [suspect.id], None::<Vec<gix::ObjectId>>)
+            .build()?
+            .collect();
+    let mut resource_cache = repo.diff_resource_cache_for_tree_diff()?;
+
+    let work_dir: PathBuf = repo
+        .work_dir()
+        .ok_or_else(|| anyhow!("blame needs a workdir, but there is none"))?
+        .into();
+    let file_path: &BStr = gix::path::os_str_into_bstr(file)?;
+
+    let blame_entries = gix::blame::blame_file(
+        &repo.objects,
+        traverse,
+        &mut resource_cache,
+        suspect.id,
+        work_dir.clone(),
+        file_path,
+    )?;
+
+    let absolute_path = work_dir.join(file);
+    let file_content = std::fs::read_to_string(absolute_path)?;
+    let lines = file_content.lines();
+
+    write_blame_entries(out, lines, blame_entries)?;
+
+    Ok(())
+}
+
+fn write_blame_entries(
+    mut out: impl std::io::Write,
+    mut lines: Lines<'_>,
+    blame_entries: Vec<gix::blame::BlameEntry>,
+) -> Result<(), std::io::Error> {
+    for blame_entry in blame_entries {
+        for line_number in blame_entry.range_in_blamed_file {
+            let line = lines.next().unwrap();
+
+            writeln!(
+                out,
+                "{} {} {}",
+                blame_entry.commit_id.to_hex_with_len(8),
+                // `line_number` is 0-based, but we want to show 1-based line numbers (as `git`
+                // does).
+                line_number + 1,
+                line
+            )?;
+        }
+    }
+
+    Ok(())
+}

gitoxide-core/src/repository/mod.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;

src/plumbing/main.rs

@@ -1533,6 +1533,15 @@ pub fn main() -> Result<()> {
                 },
             ),
         },
+        Subcommands::Blame { 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),
+        ),
         Subcommands::Completions { shell, out_dir } => {
             let mut app = Args::command();
 

src/plumbing/options/mod.rs

@@ -151,6 +151,10 @@ pub enum Subcommands {
     /// Subcommands that need no git repository to run.
     #[clap(subcommand)]
     Free(free::Subcommands),
+    /// Blame lines in a file
+    Blame {
+        file: std::ffi::OsString,
+    },
     /// Generate shell completions to stdout or a directory.
     #[clap(visible_alias = "generate-completions", visible_alias = "shell-completions")]
     Completions {