Skip to content

docs: add 'Why Pure Rust (and not libgit2)?' section to README#36

Merged
Ink-dark merged 1 commit into
mainfrom
docs/why-pure-rust
Jul 9, 2026
Merged

docs: add 'Why Pure Rust (and not libgit2)?' section to README#36
Ink-dark merged 1 commit into
mainfrom
docs/why-pure-rust

Conversation

@Ink-dark

@Ink-dark Ink-dark commented Jul 9, 2026

Copy link
Copy Markdown
Contributor

Summary

Add a new section to the README titled `### Why Pure Rust (and not libgit2)?` that explains the deliberate engineering choice to reimplement Git in pure Rust rather than wrap `libgit2` or shell out to the `git` binary.

Why

The current README describes what agit is and how it works, but does not explain why it is built the way it is. Contributors and evaluators landing on the project from gitoxide or libgit2 frequently ask the same question: "why not just use X?" This section gives a direct, opinionated answer with the technical specifics they care about.

What the section covers

  • FFI overhead and blocking issue — why `libgit2` (even via `libgit2-sys`) is problematic for long-running agents: blocking I/O, TTY assumptions, multi-threaded corruption of internal state.
  • Shelling out is a security and portability liability — env-var leakage (`$GIT_DIR`, `SSH_AUTH_SOCK`, credential helpers) across concurrent agent threads, plus the deployability pain of forcing a Git install in distroless Docker images and Windows school labs.
  • Performance via zero-copy — no FFI translation per object, O(1) OID lookups via borrowed slices over the packfile.
  • Positioning vs gitoxide — explicit differentiation: agit is narrower, plumbing-only, agent-focused; gitoxide aims to be a full porcelain `git` replacement.
  • Static linking — ~10MB Lite binary with no `libssl` / `libz` runtime dependency.

Constraints

  • ~290 words, professional but opinionated tone.
  • No marketing fluff, no "TWiR" mention.
  • Inserts after the `Architecture` section, before `Supported Commands`, so it justifies the architecture described just above it.

Checklist

  • Documentation only — no code change.
  • Follows Conventional Commits (`docs:`).

Explain the rationale for reimplementing Git in pure Rust instead of
wrapping libgit2 or shelling out to the git binary. Cover FFI blocking
issues, env-var leakage and portability concerns of shelling out,
zero-copy performance, the narrower plumbing-only scope vs gitoxide,
and the static-linking benefit of the Lite edition.
@Ink-dark Ink-dark merged commit f86b51a into main Jul 9, 2026
18 checks passed
@Ink-dark Ink-dark deleted the docs/why-pure-rust branch July 9, 2026 04:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants