Git State Laravel Package

Product Decisions This Supports

• Build vs. buy for "deploy guardrails": If the roadmap includes blocking deploys from dirty working trees or wrong branches (a common source of self-inflicted incidents), this package remains a ~100-line, dependency-free way to ship that check in days rather than weeks. Decision: buy/integrate, don't build, and don't adopt a full Git library for one inspection use case. The 1.1.0 commit() addition doesn't change the calculus — it's still a utility, not a platform.
• Release-traceability and version surfacing (strengthened in 1.1.0): Exposing commit SHA, branch, and origin URL lets you stamp builds, /health endpoints, admin footers, and error reports with "what code is actually running." Previously the SHA came bundled with origin resolution; Builder::commit() now returns the checked-out hash without requiring an origin remote. That matters in exactly the environments where traceability is hardest: CI checkouts with remotes stripped, detached-HEAD deploys, vendored/mirrored repos, and repos where origin was renamed. Product implication: commit stamping is now a viable slice even for teams who can't guarantee a remote is configured — scope it as a small, standalone item rather than a platform initiative.
• Feature gating by environment/commit for internal tools: Enabling dev-only or canary-only behavior (debug panels, verbose logging, experimental routes) based on branch or commit rather than only APP_ENV. Useful for staging/canary verification, but should stay out of customer-facing logic.
• Standardize on commit() over build() for stamping: The new API is narrower and has fewer environmental preconditions (no remote needed). Decision: make commit() the default call for build-info banners and health fields; reserve the full build() snapshot for the deploy preflight where branch/dirty state is actually needed. This reduces the blast radius of the "no .git" failure mode for the most common use case.
• Roadmap prioritization signal — negative: Still 0 dependents, single maintainer, no Laravel integration (no service provider, no config, no facade). A minor version bump doesn't change that composition: "utility library, not a platform bet." It supports the decision to keep Git-awareness as a thin internal capability rather than a product surface or a reason to re-architect anything.
• Buy-vs-wrap decision (validated): The earlier decision to wrap it behind a small internal GitStateProvider interface is now demonstrably cheap insurance — 1.1.0 is additive, so the wrapper absorbs it without touching call sites. Benefit: swapping to symfony/process calls or a different library later is a config change, not a refactor. Cost: a few hours.
• Scope discipline on DevOps tooling: Reinforces that deployment validation belongs in CI (GitHub Actions/GitLab CI have Git natively) and that in-app Git checks should be limited to diagnostics and developer-facing tooling — not a substitute for pipeline policy.

When to Consider This Package

Adopt when:

• You need read-only Git facts (commit SHA, origin URL, branch, clean/dirty, raw git status) inside PHP — e.g., an Artisan command, a health endpoint, a deploy preflight, or a build-info banner.
• You only need the commit SHA. As of 1.1.0, Builder::commit() covers this without an origin remote — the best fit for build stamping in CI checkouts, detached-HEAD deploys, or renamed/mirrored remotes. This is now the lowest-precondition entry point into the package.
• You want zero transitive dependencies and a permissively licensed (BSD-3-Clause) dependency you can vendor or fork without legal friction.
• The consuming code is internal tooling or dev-only (require --dev), where a hard failure just fails a build, not a customer request.
• You're already comfortable with the Sebastian Bergmann ecosystem (PHPUnit lineage) and value consistency.
• You only need it in one or two call sites — the surface area is tiny enough to reason about fully, and 1.1.0 is additive (no breaking changes, no migration work).

Look elsewhere or skip when:

• You need to do anything to Git — commit, tag, branch, merge, clone, push. This library describes; it does not operate. Use symfony/process, Laravel's Process facade, or a dedicated Git wrapper.
• Customer-facing request paths. git status / build() are blocking subprocess I/O; on a large repo this can take hundreds of milliseconds. commit() is lighter but still shells out — don't put either in a hot path, and caching "is the tree dirty" is often worse than the cost.
• The code runs where a Git checkout may not exist — container images built via multi-stage builds, serverless/Lambda, or tarball deploys typically ship without .git and sometimes without the git binary. build()/commit() returning false is graceful, but the feature silently disappears; confirm that's acceptable, and note that commit() narrows but does not remove this precondition.
• You need Windows robustness or a guaranteed error taxonomy. The package shells out; missing binary, permission errors, and timeouts surface as generic false/failures rather than typed exceptions. If your environments are heterogeneous, wrap symfony/process yourself.
• Dependency-review gates are strict. 0 dependents and a single maintainer is a legitimate supply-chain objection; be prepared to vendor it or accept the risk explicitly.
• You're not on PHP/Laravel — use the native tooling of whatever runtime you're in.

Adoption gate to set before committing: confirm git is present and .git exists in every environment where the check must run (prod included). If you only need the SHA, validate with commit() alone — that removes the origin-remote requirement from the gate but keeps the git-binary and .git requirements. Also confirm worst-case subprocess latency on the largest repo you'd run it against.

How to Pitch It (Stakeholders)

To executives (30 seconds):

"We have a recurring class of incident: something ships that wasn't supposed to — wrong branch, uncommitted work, or a build we can't identify after the fact. This is a tiny, free, permissively-licensed library that lets our PHP app report exactly which branch and commit it's running and whether the code is in a clean state. The new release makes the commit stamp work even where we don't control the Git remote configuration, which covers our container and CI deploy paths. It closes a real reliability gap for roughly a day of engineering, adds no ongoing vendor cost, and carries no meaningful platform lock-in because we'll isolate it behind our own interface. The risk is low and the downside is contained."

To engineering leads and DevOps:

"It's a ~100-line, zero-dependency Composer package that returns origin URL, branch, commit SHA, and clean/dirty state. 1.1.0 adds Builder::commit() — the checked-out SHA without needing an origin remote — which is the API we'll use for build stamping since it survives CI checkouts with stripped remotes and detached-HEAD deploys. Two concrete uses: (1) a deploy preflight that hard-fails on a dirty tree or non-release branch, and (2) a /health or admin field that reports the deployed commit, which will cut time-to-diagnosis on every future incident. Caveats to plan for: it shells out to git, so git and .git must exist in the target environment (the new method drops the remote requirement but not these); it's blocking, so it does not go in hot request paths; and it has one maintainer and no dependents, so we wrap it in an internal GitStateProvider and keep our call sites to a handful. The version bump is additive, so the wrapper absorbs it with no call-site changes. Primary enforcement for branch/dirty policy still belongs in CI — this is the in-app complement, not a replacement."

To the team (what we're actually shipping):

"One small service class, one Artisan command, one health field. We'll call commit() for stamping and build() only for the preflight that needs branch/dirty state. Isolated behind an interface so it's replaceable. Explicit failure behavior: if it's not a repo, or git isn't installed, log and degrade — don't crash the app. Not in the request hot path. Bump to 1.1.0 is additive, no migration. Ship it this sprint; revisit only if we outgrow read-only inspection."