Crate git_spawn 

git-spawn

A Rust wrapper around the git CLI. Each git subcommand is a struct with a builder-style API; calling .execute().await spawns git as a subprocess and returns typed output.

Unlike libraries that link against libgit2, this crate shells out to the git binary installed on the host. That choice has trade-offs:

Pro	Con
Behavior matches the user’s local git	Requires git on PATH at runtime
Supports every flag — escape hatches for all	Higher per-call overhead than libgit2
Honors core.* config, hooks, credentials	Output parsing is up to you (or us!)

If you want a scripting-like experience with the same flags you’d type in a shell, this crate is for you. For in-process object database manipulation, reach for git2 instead.

Quick start

use git_spawn::{GitCommand, Repository};

let repo = Repository::open("/path/to/repo")?;

// Stage everything and commit.
repo.add().all().execute().await?;
repo.commit().message("snapshot").execute().await?;

// Push to origin/main.
repo.push().remote("origin").refspec("main").execute().await?;

Core concepts

The GitCommand trait

Every command struct implements GitCommand. That trait provides:

• execute() — run the command and decode output
• arg() / args() — append raw CLI arguments (the universal escape hatch)
• current_dir() — choose the working directory
• env() — set environment variables
• with_timeout() — cap execution time

Repository

Repository is a cheap, cloneable handle to a working tree. Its accessor methods return commands pre-scoped to that path, so you rarely need to set .current_dir() explicitly:

let repo = Repository::open("/path/to/repo")?;
let status = repo.status().format(
    git_spawn::command::status::StatusFormat::PorcelainV2
).execute().await?;
println!("{}", status.stdout);

Typed parsers (the parse module)

By default commands return CommandOutput — raw stdout/stderr plus the exit status. For common outputs the parse module provides structured types behind the parse feature (on by default):

use git_spawn::command::status::StatusFormat;
use git_spawn::parse::{parse_status, StatusKind};

let repo = Repository::open("/path/to/repo")?;
let out = repo.status()
    .format(StatusFormat::PorcelainV1)
    .null_terminate()
    .execute()
    .await?;
for entry in parse_status(&out.stdout)? {
    if entry.index == StatusKind::Modified {
        println!("modified in index: {}", entry.path);
    }
}

Feature flags

Flag	Default	Purpose
parse	on	Typed parsers for status/log/diff output
serde	off	Serialize/Deserialize on parsed types
workflow	off	Higher-level helpers (info, branches, tags, history, workflow)

Error handling

All methods return Result<T>. The Error enum distinguishes common failure modes — git missing from PATH, a non-zero exit, a timeout, an invalid builder configuration, a path that isn’t a git repo, and so on. The Error::CommandFailed variant carries the captured stdout, stderr, and exit code so you can present a good error message or retry.

Design principles

• One struct per subcommand under command
• Async-first on tokio
• Raw output by default; typed parsing is opt-in via the parse module
• Escape hatches everywhere so the crate is useful for flags we haven’t wrapped yet
• No unsafe code, no global state, no hidden config

Re-exports

pub use command::CommandExecutor;

pub use command::CommandOutput;

pub use command::GitCommand;

pub use command::add::AddCommand;

pub use command::bisect::BisectCommand;

pub use command::branch::BranchCommand;

pub use command::cat_file::CatFileCommand;

pub use command::checkout::CheckoutCommand;

pub use command::cherry_pick::CherryPickCommand;

pub use command::clone::CloneCommand;

pub use command::commit::CommitCommand;

pub use command::config::ConfigCommand;

pub use command::describe::DescribeCommand;

pub use command::diff::DiffCommand;

pub use command::fetch::FetchCommand;

pub use command::for_each_ref::ForEachRefCommand;

pub use command::grep::GrepCommand;

pub use command::hash_object::HashObjectCommand;

pub use command::init::InitCommand;

pub use command::log::LogCommand;

pub use command::ls_files::LsFilesCommand;

pub use command::ls_tree::LsTreeCommand;

pub use command::merge::MergeCommand;

pub use command::mv::MvCommand;

pub use command::pull::PullCommand;

pub use command::push::PushCommand;

pub use command::rebase::RebaseCommand;

pub use command::reflog::ReflogCommand;

pub use command::remote::RemoteCommand;

pub use command::reset::ResetCommand;

pub use command::restore::RestoreCommand;

pub use command::rev_parse::RevParseCommand;

pub use command::rm::RmCommand;

pub use command::show::ShowCommand;

pub use command::show_ref::ShowRefCommand;

pub use command::stash::StashCommand;

pub use command::status::StatusCommand;

pub use command::submodule::SubmoduleCommand;

pub use command::switch::SwitchCommand;

pub use command::symbolic_ref::SymbolicRefCommand;

pub use command::tag::TagCommand;

pub use command::update_ref::UpdateRefCommand;

pub use command::worktree::WorktreeCommand;

pub use error::Error;

pub use error::Result;

pub use repo::Repository;

Modules

branchesworkflow

Typed listing and bulk operations on local branches.

command

Command execution primitives.

error

Error types for git-spawn.

historyworkflow

Walk a repository’s commit history into typed Commit structs.

infoworkflow

Repository overview in a single call.

parseparse

Typed parsers for common git outputs.

repo

High-level handle for operating on a git repository.

tagsworkflow

Typed listing and bulk operations on tags.

workflowworkflow

Common multi-step compositions, one call apiece.