git_fast_import/

lib.rs

//! A library for generating [`git fast-import`] streams.
//!
//! This crate provides a simple, type-safe API for creating git commits programmatically
//! by generating a stream that can be piped to `git fast-import`.
//!
//! # Example
//!
//! Write to a buffer:
//!
//! ```no_run
//! use git_fast_import::{GitFastImporter, GITHUB_BOT_AUTHOR};
//!
//! let mut output = Vec::new();
//! let mut importer = GitFastImporter::new(
//!     &mut output,
//!     "main".to_string(),
//!     None,
//!     GITHUB_BOT_AUTHOR.to_string(),
//! );
//!
//! let mut commit = importer.start_commit("Initial commit", chrono::Utc::now());
//! commit.add_file("hello.txt", b"Hello, World!").unwrap();
//! commit.finish().unwrap();
//! importer.finish().unwrap();
//!
//! // `output` now contains a valid git fast-import stream
//! ```
//!
//! Pipe directly to `git fast-import`:
//!
//! ```no_run
//! use git_fast_import::{GitFastImporter, GITHUB_BOT_AUTHOR};
//! use std::process::{Command, Stdio};
//!
//! let mut child = Command::new("git")
//!     .args(["fast-import", "--quiet"])
//!     .stdin(Stdio::piped())
//!     .spawn()
//!     .expect("failed to spawn git fast-import");
//!
//! let stdin = child.stdin.take().unwrap();
//! let mut importer = GitFastImporter::new(
//!     stdin,
//!     "main".to_string(),
//!     None,
//!     GITHUB_BOT_AUTHOR.to_string(),
//! );
//!
//! let mut commit = importer.start_commit("Initial commit", chrono::Utc::now());
//! commit.add_file("src/lib.rs", b"// new file").unwrap();
//! commit.finish().unwrap();
//! importer.finish().unwrap();
//!
//! let status = child.wait().expect("failed to wait on git fast-import");
//! assert!(status.success());
//! ```
//!
//! [`git fast-import`]: https://git-scm.com/docs/git-fast-import

use chrono::{DateTime, TimeZone};
use std::io;
use std::io::Write;

/// A committer string for GitHub Actions bot.
pub const GITHUB_BOT_AUTHOR: &str = "committer Bot <github-actions[bot]@users.noreply.github.com>";

/// Generates a git fast-import stream.
///
/// Write the stream to any [`Write`] implementor, then pipe it to `git fast-import`.
#[derive(Debug)]
pub struct GitFastImporter<T: Write> {
    output: T,
    current_mark: usize,
    branch: String,
    initial_parent: Option<String>,
    author: String,
}

/// Builder for constructing a single commit.
///
/// Created by [`GitFastImporter::start_commit`]. Add files with [`add_file`](Self::add_file),
/// then call [`finish`](Self::finish) to write the commit. Dropping without calling `finish`
/// discards the commit (but any blobs written remain in the stream).
pub struct CommitBuilder<'a, T: Write> {
    importer: &'a mut GitFastImporter<T>,
    message: String,
    timestamp: String,
    files: Vec<(usize, String)>,
}

impl<'a, T: Write> CommitBuilder<'a, T> {
    /// Adds a file to this commit.
    pub fn add_file(&mut self, path: &str, data: &[u8]) -> io::Result<&mut Self> {
        let mark = self.importer.write_blob(data)?;
        self.files.push((mark, path.to_string()));
        Ok(self)
    }

    /// Writes the commit to the output stream.
    pub fn finish(self) -> io::Result<()> {
        self.importer
            .write_commit(&self.message, &self.timestamp, self.files)
    }
}

impl<T: Write> GitFastImporter<T> {
    /// Creates a new importer that writes to the given output.
    ///
    /// # Arguments
    ///
    /// * `output` - The writer to output the fast-import stream to
    /// * `branch` - The branch name to create commits on (e.g., `"main"`)
    /// * `initial_parent` - Optional parent ref for the first commit (e.g., `"refs/heads/main"`)
    /// * `author` - The committer string (e.g., [`GITHUB_BOT_AUTHOR`])
    pub fn new(output: T, branch: String, initial_parent: Option<String>, author: String) -> Self {
        GitFastImporter {
            output,
            current_mark: 0,
            branch,
            initial_parent,
            author,
        }
    }

    /// Starts building a new commit.
    ///
    /// # Arguments
    ///
    /// * `message` - The commit message
    /// * `timestamp` - The commit timestamp (e.g., `Utc::now()`)
    pub fn start_commit(
        &mut self,
        message: &str,
        timestamp: DateTime<impl TimeZone<Offset: std::fmt::Display>>,
    ) -> CommitBuilder<'_, T> {
        CommitBuilder {
            importer: self,
            message: message.to_string(),
            timestamp: timestamp.format("%s %z").to_string(),
            files: Vec::new(),
        }
    }

    /// Writes the `done` command to finalize the stream.
    pub fn finish(&mut self) -> io::Result<()> {
        writeln!(self.output, "done")?;
        Ok(())
    }

    fn write_blob(&mut self, data: &[u8]) -> io::Result<usize> {
        self.current_mark += 1;
        writeln!(self.output, "blob")?;
        writeln!(self.output, "mark :{}", self.current_mark)?;
        writeln!(self.output, "data {}", data.len())?;
        self.output.write_all(data)?;
        writeln!(self.output)?;
        Ok(self.current_mark)
    }

    fn write_commit(
        &mut self,
        message: &str,
        timestamp: &str,
        paths_to_nodes: Vec<(usize, String)>,
    ) -> io::Result<()> {
        self.current_mark += 1;
        writeln!(self.output, "commit refs/heads/{}", self.branch)?;
        writeln!(self.output, "mark :{}", self.current_mark)?;
        writeln!(self.output, "{} {}", self.author, timestamp)?;

        writeln!(self.output, "data {}", message.len())?;
        writeln!(self.output, "{}", message)?;

        if let Some(parent) = self.initial_parent.take() {
            writeln!(self.output, "from {parent}")?;
        }

        for (mark, path) in paths_to_nodes {
            if path.is_empty() {
                continue;
            }
            writeln!(self.output, "M 100644 :{mark} {path}")?;
        }
        writeln!(self.output)?;
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use chrono::Utc;

    fn ts() -> DateTime<Utc> {
        DateTime::UNIX_EPOCH
    }

    fn create_importer(output: &mut Vec<u8>) -> GitFastImporter<&mut Vec<u8>> {
        GitFastImporter::new(
            output,
            "main".to_string(),
            None,
            "committer Test <test@example.com>".to_string(),
        )
    }

    #[test]
    fn test_single_commit_with_file() {
        let mut output = Vec::new();
        let mut importer = create_importer(&mut output);

        let mut commit = importer.start_commit("Add test file", ts());
        commit.add_file("test.txt", b"hello world").unwrap();
        commit.finish().unwrap();
        importer.finish().unwrap();

        assert_eq!(
            String::from_utf8(output).unwrap(),
            "\
blob
mark :1
data 11
hello world
commit refs/heads/main
mark :2
committer Test <test@example.com> 0 +0000
data 13
Add test file
M 100644 :1 test.txt

done
"
        );
    }

    #[test]
    fn test_multiple_files_in_commit() {
        let mut output = Vec::new();
        let mut importer = create_importer(&mut output);

        let mut commit = importer.start_commit("Add multiple files", ts());
        commit.add_file("a.txt", b"aaa").unwrap();
        commit.add_file("b.txt", b"bbb").unwrap();
        commit.finish().unwrap();

        assert_eq!(
            String::from_utf8(output).unwrap(),
            "\
blob
mark :1
data 3
aaa
blob
mark :2
data 3
bbb
commit refs/heads/main
mark :3
committer Test <test@example.com> 0 +0000
data 18
Add multiple files
M 100644 :1 a.txt
M 100644 :2 b.txt

"
        );
    }

    #[test]
    fn test_multiple_commits() {
        let mut output = Vec::new();
        let mut importer = create_importer(&mut output);

        let mut commit1 = importer.start_commit("First commit", ts());
        commit1.add_file("first.txt", b"first").unwrap();
        commit1.finish().unwrap();

        let mut commit2 = importer.start_commit("Second commit", ts());
        commit2.add_file("second.txt", b"second").unwrap();
        commit2.finish().unwrap();

        assert_eq!(
            String::from_utf8(output).unwrap(),
            "\
blob
mark :1
data 5
first
commit refs/heads/main
mark :2
committer Test <test@example.com> 0 +0000
data 12
First commit
M 100644 :1 first.txt

blob
mark :3
data 6
second
commit refs/heads/main
mark :4
committer Test <test@example.com> 0 +0000
data 13
Second commit
M 100644 :3 second.txt

"
        );
    }

    #[test]
    fn test_initial_parent() {
        let mut output = Vec::new();
        let mut importer = GitFastImporter::new(
            &mut output,
            "main".to_string(),
            Some("refs/heads/existing".to_string()),
            "committer Test <test@example.com>".to_string(),
        );

        let mut commit = importer.start_commit("Child commit", ts());
        commit.add_file("file.txt", b"data").unwrap();
        commit.finish().unwrap();

        assert_eq!(
            String::from_utf8(output).unwrap(),
            "\
blob
mark :1
data 4
data
commit refs/heads/main
mark :2
committer Test <test@example.com> 0 +0000
data 12
Child commit
from refs/heads/existing
M 100644 :1 file.txt

"
        );
    }

    #[test]
    fn test_initial_parent_only_on_first_commit() {
        let mut output = Vec::new();
        let mut importer = GitFastImporter::new(
            &mut output,
            "main".to_string(),
            Some("refs/heads/existing".to_string()),
            "committer Test <test@example.com>".to_string(),
        );

        let mut commit1 = importer.start_commit("First", ts());
        commit1.add_file("a.txt", b"a").unwrap();
        commit1.finish().unwrap();

        let mut commit2 = importer.start_commit("Second", ts());
        commit2.add_file("b.txt", b"b").unwrap();
        commit2.finish().unwrap();

        assert_eq!(
            String::from_utf8(output).unwrap(),
            "\
blob
mark :1
data 1
a
commit refs/heads/main
mark :2
committer Test <test@example.com> 0 +0000
data 5
First
from refs/heads/existing
M 100644 :1 a.txt

blob
mark :3
data 1
b
commit refs/heads/main
mark :4
committer Test <test@example.com> 0 +0000
data 6
Second
M 100644 :3 b.txt

"
        );
    }

    #[test]
    fn test_empty_path_skipped() {
        let mut output = Vec::new();
        let mut importer = create_importer(&mut output);

        let mut commit = importer.start_commit("Test", ts());
        commit.add_file("", b"data").unwrap();
        commit.add_file("real.txt", b"data").unwrap();
        commit.finish().unwrap();

        assert_eq!(
            String::from_utf8(output).unwrap(),
            "\
blob
mark :1
data 4
data
blob
mark :2
data 4
data
commit refs/heads/main
mark :3
committer Test <test@example.com> 0 +0000
data 4
Test
M 100644 :2 real.txt

"
        );
    }

    #[test]
    fn test_dropped_commit_builder_no_commit() {
        let mut output = Vec::new();
        let mut importer = create_importer(&mut output);

        {
            let mut builder = importer.start_commit("Dropped commit", ts());
            builder.add_file("file.txt", b"data").unwrap();
            // Drop without calling finish()
        }

        importer.finish().unwrap();

        assert_eq!(
            String::from_utf8(output).unwrap(),
            "\
blob
mark :1
data 4
data
done
"
        );
    }
}