Add bindings for mailmap (#691)

* Add several bindings for mailmap

Add bindings for

- git_mailmap_free
- git_mailmap_from_repository
- git_mailmap_resolve_signature
- git_commit_author_with_mailmap
- git_commit_committer_with_mailmap

This is half the functions in the "mailmap" group and the two
convenience functions in the "commit" group, which is enough to make
mailmap support useful. I omitted git_mailmap_resolve because of the
slightly awkward function signature.

I also omitted

- git_mailmap_new
- git_mailmap_from_buffer
- git_mailmap_add_entry

which support in-memory manipulation of a mailmap representation: there
appears to be no way to write the representation to disk, neither
directly nor indirectly, so those functions seem a bit pointless.

* Add more mailmap bindings

Add bindings for

- git_mailmap_new
- git_mailmap_from_buffer
- git_mailmap_add_entry

to support in-memory manipulation of a mailmap representation. Commit
c5fe47d (Add several bindings for mailmap, 2021-03-26) notes that these
seem silly on account of offering no way to write the representation
back to disk. However, they are easy to support and effectively enable
an out-of-tree .mailmap file.

Author: commonquail

libgit2-sys/lib.rs

@@ -90,6 +90,7 @@ pub enum git_odb_stream {}
 pub enum git_odb_object {}
 pub enum git_worktree {}
 pub enum git_transaction {}
+pub enum git_mailmap {}
 
 #[repr(C)]
 pub struct git_revspec {
@@ -2598,7 +2599,17 @@ extern "C" {
 
     // commit
     pub fn git_commit_author(commit: *const git_commit) -> *const git_signature;
+    pub fn git_commit_author_with_mailmap(
+        out: *mut *mut git_signature,
+        commit: *const git_commit,
+        mailmap: *const git_mailmap,
+    ) -> c_int;
     pub fn git_commit_committer(commit: *const git_commit) -> *const git_signature;
+    pub fn git_commit_committer_with_mailmap(
+        out: *mut *mut git_signature,
+        commit: *const git_commit,
+        mailmap: *const git_mailmap,
+    ) -> c_int;
     pub fn git_commit_free(commit: *mut git_commit);
     pub fn git_commit_id(commit: *const git_commit) -> *const git_oid;
     pub fn git_commit_lookup(
@@ -3941,6 +3952,31 @@ extern "C" {
     pub fn git_transaction_remove(tx: *mut git_transaction, refname: *const c_char) -> c_int;
     pub fn git_transaction_commit(tx: *mut git_transaction) -> c_int;
     pub fn git_transaction_free(tx: *mut git_transaction);
+
+    // Mailmap
+    pub fn git_mailmap_new(out: *mut *mut git_mailmap) -> c_int;
+    pub fn git_mailmap_from_buffer(
+        out: *mut *mut git_mailmap,
+        buf: *const c_char,
+        len: size_t,
+    ) -> c_int;
+    pub fn git_mailmap_from_repository(
+        out: *mut *mut git_mailmap,
+        repo: *mut git_repository,
+    ) -> c_int;
+    pub fn git_mailmap_free(mm: *mut git_mailmap);
+    pub fn git_mailmap_resolve_signature(
+        out: *mut *mut git_signature,
+        mm: *const git_mailmap,
+        sig: *const git_signature,
+    ) -> c_int;
+    pub fn git_mailmap_add_entry(
+        mm: *mut git_mailmap,
+        real_name: *const c_char,
+        real_email: *const c_char,
+        replace_name: *const c_char,
+        replace_email: *const c_char,
+    ) -> c_int;
 }
 
 pub fn init() {

src/commit.rs

@@ -6,7 +6,7 @@ use std::ptr;
 use std::str;
 
 use crate::util::Binding;
-use crate::{raw, signature, Buf, Error, IntoCString, Object, Oid, Signature, Time, Tree};
+use crate::{raw, signature, Buf, Error, IntoCString, Mailmap, Object, Oid, Signature, Time, Tree};
 
 /// A structure to represent a git [commit][1]
 ///
@@ -183,6 +183,20 @@ impl<'repo> Commit<'repo> {
         }
     }
 
+    /// Get the author of this commit, using the mailmap to map names and email
+    /// addresses to canonical real names and email addresses.
+    pub fn author_with_mailmap(&self, mailmap: &Mailmap) -> Result<Signature<'static>, Error> {
+        let mut ret = ptr::null_mut();
+        unsafe {
+            try_call!(raw::git_commit_author_with_mailmap(
+                &mut ret,
+                &*self.raw,
+                &*mailmap.raw()
+            ));
+            Ok(Binding::from_raw(ret))
+        }
+    }
+
     /// Get the committer of this commit.
     pub fn committer(&self) -> Signature<'_> {
         unsafe {
@@ -191,6 +205,20 @@ impl<'repo> Commit<'repo> {
         }
     }
 
+    /// Get the committer of this commit, using the mailmap to map names and email
+    /// addresses to canonical real names and email addresses.
+    pub fn committer_with_mailmap(&self, mailmap: &Mailmap) -> Result<Signature<'static>, Error> {
+        let mut ret = ptr::null_mut();
+        unsafe {
+            try_call!(raw::git_commit_committer_with_mailmap(
+                &mut ret,
+                &*self.raw,
+                &*mailmap.raw()
+            ));
+            Ok(Binding::from_raw(ret))
+        }
+    }
+
     /// Amend this existing commit with all non-`None` values
     ///
     /// This creates a new commit that is exactly the same as the old commit,

src/lib.rs

@@ -98,6 +98,7 @@ pub use crate::index::{
     Index, IndexConflict, IndexConflicts, IndexEntries, IndexEntry, IndexMatchedPath,
 };
 pub use crate::indexer::{IndexerProgress, Progress};
+pub use crate::mailmap::Mailmap;
 pub use crate::mempack::Mempack;
 pub use crate::merge::{AnnotatedCommit, MergeOptions};
 pub use crate::message::{message_prettify, DEFAULT_COMMENT_CHAR};
@@ -660,6 +661,7 @@ mod diff;
 mod error;
 mod index;
 mod indexer;
+mod mailmap;
 mod mempack;
 mod merge;
 mod message;

src/mailmap.rs

@@ -0,0 +1,134 @@
+use std::ffi::CString;
+use std::ptr;
+
+use crate::util::Binding;
+use crate::{raw, Error, Signature};
+
+/// A structure to represent a repository's .mailmap file.
+///
+/// The representation cannot be written to disk.
+pub struct Mailmap {
+    raw: *mut raw::git_mailmap,
+}
+
+impl Binding for Mailmap {
+    type Raw = *mut raw::git_mailmap;
+
+    unsafe fn from_raw(ptr: *mut raw::git_mailmap) -> Mailmap {
+        Mailmap { raw: ptr }
+    }
+
+    fn raw(&self) -> *mut raw::git_mailmap {
+        self.raw
+    }
+}
+
+impl Drop for Mailmap {
+    fn drop(&mut self) {
+        unsafe {
+            raw::git_mailmap_free(self.raw);
+        }
+    }
+}
+
+impl Mailmap {
+    /// Creates an empty, in-memory mailmap object.
+    pub fn new() -> Result<Mailmap, Error> {
+        crate::init();
+        let mut ret = ptr::null_mut();
+        unsafe {
+            try_call!(raw::git_mailmap_new(&mut ret));
+            Ok(Binding::from_raw(ret))
+        }
+    }
+
+    /// Creates an in-memory mailmap object representing the given buffer.
+    pub fn from_buffer(buf: &str) -> Result<Mailmap, Error> {
+        crate::init();
+        let mut ret = ptr::null_mut();
+        let len = buf.len();
+        let buf = CString::new(buf)?;
+        unsafe {
+            try_call!(raw::git_mailmap_from_buffer(&mut ret, buf, len));
+            Ok(Binding::from_raw(ret))
+        }
+    }
+
+    /// Adds a new entry to this in-memory mailmap object.
+    pub fn add_entry(
+        &mut self,
+        real_name: Option<&str>,
+        real_email: Option<&str>,
+        replace_name: Option<&str>,
+        replace_email: &str,
+    ) -> Result<(), Error> {
+        let real_name = crate::opt_cstr(real_name)?;
+        let real_email = crate::opt_cstr(real_email)?;
+        let replace_name = crate::opt_cstr(replace_name)?;
+        let replace_email = CString::new(replace_email)?;
+        unsafe {
+            try_call!(raw::git_mailmap_add_entry(
+                self.raw,
+                real_name,
+                real_email,
+                replace_name,
+                replace_email
+            ));
+            Ok(())
+        }
+    }
+
+    /// Resolves a signature to its real name and email address.
+    pub fn resolve_signature(&self, sig: &Signature<'_>) -> Result<Signature<'static>, Error> {
+        let mut ret = ptr::null_mut();
+        unsafe {
+            try_call!(raw::git_mailmap_resolve_signature(
+                &mut ret,
+                &*self.raw,
+                sig.raw()
+            ));
+            Ok(Binding::from_raw(ret))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn smoke() {
+        let sig_name = "name";
+        let sig_email = "email";
+        let sig = t!(Signature::now(sig_name, sig_email));
+
+        let mut mm = t!(Mailmap::new());
+
+        let mailmapped_sig = t!(mm.resolve_signature(&sig));
+        assert_eq!(mailmapped_sig.name(), Some(sig_name));
+        assert_eq!(mailmapped_sig.email(), Some(sig_email));
+
+        t!(mm.add_entry(None, None, None, sig_email));
+        t!(mm.add_entry(
+            Some("real name"),
+            Some("real@email"),
+            Some(sig_name),
+            sig_email,
+        ));
+
+        let mailmapped_sig = t!(mm.resolve_signature(&sig));
+        assert_eq!(mailmapped_sig.name(), Some("real name"));
+        assert_eq!(mailmapped_sig.email(), Some("real@email"));
+    }
+
+    #[test]
+    fn from_buffer() {
+        let buf = "<prøper@emæil> <email>";
+        let mm = t!(Mailmap::from_buffer(&buf));
+
+        let sig = t!(Signature::now("name", "email"));
+        let mailmapped_sig = t!(mm.resolve_signature(&sig));
+        assert_eq!(mailmapped_sig.name(), Some("name"));
+        assert_eq!(mailmapped_sig.email(), Some("prøper@emæil"));
+    }
+}

src/repo.rs

@@ -11,6 +11,7 @@ use crate::build::{CheckoutBuilder, RepoBuilder};
 use crate::diff::{
     binary_cb_c, file_cb_c, hunk_cb_c, line_cb_c, BinaryCb, DiffCallbacks, FileCb, HunkCb, LineCb,
 };
+use crate::mailmap::Mailmap;
 use crate::oid_array::OidArray;
 use crate::stash::{stash_cb, StashApplyOptions, StashCbData};
 use crate::string_array::StringArray;
@@ -2962,6 +2963,15 @@ impl Repository {
             Ok(Binding::from_raw(raw))
         }
     }
+
+    /// Gets this repository's mailmap.
+    pub fn mailmap(&self) -> Result<Mailmap, Error> {
+        let mut ret = ptr::null_mut();
+        unsafe {
+            try_call!(raw::git_mailmap_from_repository(&mut ret, self.raw));
+            Ok(Binding::from_raw(ret))
+        }
+    }
 }
 
 impl Binding for Repository {
@@ -3144,7 +3154,9 @@ impl RepositoryInitOptions {
 mod tests {
     use crate::build::CheckoutBuilder;
     use crate::CherrypickOptions;
-    use crate::{ObjectType, Oid, Repository, ResetType, SubmoduleIgnore, SubmoduleUpdate};
+    use crate::{
+        ObjectType, Oid, Repository, ResetType, Signature, SubmoduleIgnore, SubmoduleUpdate,
+    };
     use std::ffi::OsStr;
     use std::fs;
     use std::path::Path;
@@ -3836,4 +3848,94 @@ mod tests {
 
         Ok(())
     }
+
+    #[test]
+    fn smoke_mailmap_from_repository() {
+        let (_td, repo) = crate::test::repo_init();
+
+        let commit = {
+            let head = t!(repo.head()).target().unwrap();
+            t!(repo.find_commit(head))
+        };
+
+        // This is our baseline for HEAD.
+        let author = commit.author();
+        let committer = commit.committer();
+        assert_eq!(author.name(), Some("name"));
+        assert_eq!(author.email(), Some("email"));
+        assert_eq!(committer.name(), Some("name"));
+        assert_eq!(committer.email(), Some("email"));
+
+        // There is no .mailmap file in the test repo so all signature identities are equal.
+        let mailmap = t!(repo.mailmap());
+        let mailmapped_author = t!(commit.author_with_mailmap(&mailmap));
+        let mailmapped_committer = t!(commit.committer_with_mailmap(&mailmap));
+        assert_eq!(mailmapped_author.name(), author.name());
+        assert_eq!(mailmapped_author.email(), author.email());
+        assert_eq!(mailmapped_committer.name(), committer.name());
+        assert_eq!(mailmapped_committer.email(), committer.email());
+
+        let commit = {
+            // - Add a .mailmap file to the repository.
+            // - Commit with a signature identity different from the author's.
+            // - Include entries for both author and committer to prove we call
+            //   the right raw functions.
+            let mailmap_file = Path::new(".mailmap");
+            let p = Path::new(repo.workdir().unwrap()).join(&mailmap_file);
+            t!(fs::write(
+                p,
+                r#"
+Author Name <author.proper@email> name <email>
+Committer Name <committer.proper@email> <committer@email>"#,
+            ));
+            let mut index = t!(repo.index());
+            t!(index.add_path(&mailmap_file));
+            let id_mailmap = t!(index.write_tree());
+            let tree_mailmap = t!(repo.find_tree(id_mailmap));
+
+            let head = t!(repo.commit(
+                Some("HEAD"),
+                &author,
+                t!(&Signature::now("committer", "committer@email")),
+                "Add mailmap",
+                &tree_mailmap,
+                &[&commit],
+            ));
+            t!(repo.find_commit(head))
+        };
+
+        // Sanity check that we're working with the right commit and that its
+        // author and committer identities differ.
+        let author = commit.author();
+        let committer = commit.committer();
+        assert_ne!(author.name(), committer.name());
+        assert_ne!(author.email(), committer.email());
+        assert_eq!(author.name(), Some("name"));
+        assert_eq!(author.email(), Some("email"));
+        assert_eq!(committer.name(), Some("committer"));
+        assert_eq!(committer.email(), Some("committer@email"));
+
+        // Fetch the newly added .mailmap from the repository.
+        let mailmap = t!(repo.mailmap());
+        let mailmapped_author = t!(commit.author_with_mailmap(&mailmap));
+        let mailmapped_committer = t!(commit.committer_with_mailmap(&mailmap));
+
+        let mm_resolve_author = t!(mailmap.resolve_signature(&author));
+        let mm_resolve_committer = t!(mailmap.resolve_signature(&committer));
+
+        // Mailmap Signature lifetime is independent of Commit lifetime.
+        drop(author);
+        drop(committer);
+        drop(commit);
+
+        // author_with_mailmap() + committer_with_mailmap() work
+        assert_eq!(mailmapped_author.name(), Some("Author Name"));
+        assert_eq!(mailmapped_author.email(), Some("author.proper@email"));
+        assert_eq!(mailmapped_committer.name(), Some("Committer Name"));
+        assert_eq!(mailmapped_committer.email(), Some("committer.proper@email"));
+
+        // resolve_signature() works
+        assert_eq!(mm_resolve_author.email(), mailmapped_author.email());
+        assert_eq!(mm_resolve_committer.email(), mailmapped_committer.email());
+    }
 }