Git Wrapper Laravel Package

Product Decisions This Supports

• De-risks any "versioning" feature to a scoping exercise rather than a quarter-scale epic. A thin, MIT-licensed, object-oriented PHP wrapper over the git CLI gives you clone, commit, branch, tag, merge, diff, and status with structured output and exceptions on failure. Any spec that says "history," "diff," "rollback," or "release tagging" has its plumbing risk largely removed — no bespoke exec() layer, no hand-parsed stdout, no homegrown audit table.
• Content and configuration versioning is the highest-leverage use case. CMS pages, templates, prompts, policy docs, and feature-flag definitions get real history, diff, and restore-to-version-N backed by an actual repository. This is the roadmap enabler: it turns "versioning" from infrastructure into a scoped product feature with a known build size.
• Internal release and deployment tooling. Admin-triggered tag creation, changelog assembly from commit history, branch/tag inventories, per-repo last-activity, environment drift checks. Cheap to build, internal-facing, low customer risk — the right place to prove the capability before it touches a customer surface.
• Build vs. buy: buy. The alternative is a few hundred lines of fragile subprocess handling plus the long tail of exit codes, stderr handling, escaping, and missing-binary edge cases. This is small, replaceable, and the cost of being wrong is a refactor, not a migration.
• Roadmap signal, not a roadmap driver. Adoption makes git-backed features feel cheap, which tends to pull teams toward versioning work. Be explicit that this is enabling infrastructure; it should not generate roadmap items on its own. Decide the versioning feature on customer value, then use this to shorten the build.

When to Consider This Package

Adopt when:

• You need to do git things from PHP — clone, commit, branch, tag, merge, diff, status — not merely read repository metadata.
• All git work sits behind queued jobs with timeouts, never inline on a request path. Git is slow, blocking, and forks a process; a web request is the wrong place for it.
• You control the runtime: the git binary is installed and patched, the PHP process user can write to the working copies, and storage survives restarts.
• You accept that this is not a Laravel package — no service provider, no facade, no publishable config on this line. Integration means a container binding you write yourself (roughly 50 lines). That is a portability feature and a small ownership cost.
• You wrap it behind your own interface (RepositoryInspector, ReleaseTagger) so it stays an implementation detail rather than a dependency leaking across the codebase.

Look elsewhere when:

• You only need repository metadata — open PRs, issues, CI status, contributors. Use the GitHub/GitLab/Bitbucket APIs: faster, no binary dependency, no clone, no filesystem permissions.
• The environment can't fork: serverless, locked-down containers with disable_functions, read-only filesystems, or open_basedir restrictions.
• Untrusted input can reach command construction. The library escapes arguments, but user-supplied refs, remote URLs, and paths still need validation and a sandboxed working directory. If you cannot sandbox, do not ship user-triggered git.
• You want deep Laravel ergonomics out of the box — queued jobs, events, config publishing, a facade. You will be writing that glue yourself.
• It's genuinely CI's or the deploy pipeline's job. Don't move deployment logic into application code just because a library makes it possible.

Adoption caution worth flagging to planning: this is a low-signal dependency — effectively zero dependent packages, no stars, a single maintainer, and a legacy Laravel compatibility line. Expect resolution friction on Laravel 10+ and budget a spike to confirm it installs on your exact PHP/Laravel pair before any design work. Plan for the possibility that you depend on the underlying php-git library directly with your own binding instead.

How to Pitch It (Stakeholders)

For executives: A small, MIT-licensed PHP library that lets our application talk to git directly, without us building and maintaining subprocess plumbing. It removes roughly a sprint of undifferentiated engineering from any feature involving version history, rollback, changelog generation, or release tooling, and it carries no licensing cost and no vendor lock-in — we can pin it and remove it without touching product code. The honest risk framing: it's a niche dependency with a single maintainer and no downstream adoption signal, and it requires the git binary and writable repositories at runtime. That makes it a good fit for internal tooling and content-versioning features, and a poor fit for anything customer-facing on the request path. Recommendation: adopt behind our own interface, prove it on one low-risk internal workflow, and treat the real budget as operational on-call for git binary patching rather than the integration itself.

For engineering: Framework-agnostic wrapper over the git CLI — no service provider, no facade, no config to publish on this line, so the wiring is ours. It requires the git binary plus filesystem permissions on the working copies, so every call belongs in a queued job with a timeout, a capped output buffer, and GIT_TERMINAL_PROMPT=0 so a missing credential fails fast instead of hanging a worker. Arguments are escaped by the library, but user-supplied refs and paths still need validation and a sandboxed working directory. Pin git in the base image and assert a minimum patched version at boot — git CVEs become our CVEs and Composer audit won't surface them. Watch .git/index.lock contention: concurrent operations against the same working copy is the dominant failure mode, and adding workers does not solve it. Before committing, run a resolution spike on our Laravel version — this line targets much older illuminate/support constraints and may need a fork or a direct dependency on the underlying library.