Git State Laravel Package

Product Decisions This Supports

• CI/CD Pipeline Validation: Enforce Git state checks (e.g., clean working directory, correct branch) as gating conditions in deployment pipelines to prevent accidental deploys with uncommitted changes or from incorrect branches.
• Feature Flagging & Rollback Logic: Use commit hashes or branch names to dynamically enable/disable features or automate rollback triggers (e.g., deploy only from main or release/* branches).
• DevOps Tooling & Observability: Build internal dashboards or audit logs that track Git metadata (e.g., commit history, branch context) for debugging or compliance purposes.
• Security & Compliance Checks: Integrate Git state validation into pre-deployment hooks to ensure code meets security policies (e.g., no uncommitted changes, specific branch restrictions).
• Build vs. Buy Decision: Opt for this lightweight, open-source package over custom scripts or heavier frameworks (e.g., GitHub API) when the sole requirement is Git metadata inspection without additional Git operations.
• Developer Experience (DX) Improvements: Surface Git state in IDE plugins, CLI tools, or onboarding flows to reduce friction (e.g., "You’re on branch feature/x with 3 uncommitted changes—commit or stash?").

When to Consider This Package

• Use this when:

  • You need programmatic access to Git metadata (branch, commit hash, remote URL, working directory status) in a Laravel/PHP environment.
  • Your use case is Git-centric (e.g., CI/CD validation, deployment checks, or workflow automation) and doesn’t require broader Git operations like cloning, pushing, or merging.
  • You’re building internal tools (e.g., status dashboards, audit logs) where dependency overhead is undesirable (the package is ~100 lines of code with no external dependencies).
  • You’re already using Sebastian Bergmann’s ecosystem (e.g., PHPUnit) and prefer consistency in tooling.
  • You need a lightweight, dependency-free solution for Git state inspection, avoiding the complexity of full Git libraries.

• Look elsewhere when:

  • You require Git operations beyond state inspection (e.g., commits, merges, rebases) → Use Laravel Git or PHP-Git.
  • You need cross-platform Git wrappers with robust error handling (e.g., Windows support) → Evaluate GitPHP or native shell commands via exec() or Process facade.
  • Your team lacks PHP/Laravel expertise → Consider language-agnostic tools (e.g., GitHub Actions, GitLab CI) or shell scripts.
  • You need real-time Git events (e.g., webhooks, push notifications) → Use Git’s native hooks or a dedicated service like GitHub/GitLab APIs.
  • You’re working in a non-PHP environment → Use language-specific Git libraries (e.g., gitpython for Python, jgit for Java).

How to Pitch It (Stakeholders)

For Executives: "This package enables us to programmatically inspect Git state—like branch, commit hash, and working directory status—to automate critical workflows such as deployment validation, feature flagging, and security checks. It’s a lightweight, open-source solution that reduces manual errors and improves reliability without adding complexity. Since it’s maintained by the creator of PHPUnit, it’s stable and low-risk. For example, we could use it to block deployments with uncommitted changes or dynamically enable features based on the commit history."

For Engineering/DevOps: *"Need to check Git state in Laravel? This package gives you a clean, dependency-free way to access:

• Current branch/commit: For feature flags, audit trails, or rollback logic.
• Remote URL: To validate deployments or sync configurations.
• Working directory status: To block dirty deploys in CI/CD pipelines. It’s a single Composer install (sebastian/git-state) and works alongside existing Git tools. Perfect for quick scripts, CI checks, or scaling to pipeline automation. No bloat—just Git metadata when you need it."*

For Developers: *"Want to validate Git state in your Laravel app? This package lets you:

• Check if the working directory is clean before running migrations or deployments.
• Fetch the current branch or commit hash for version-aware features.
• Access the remote URL to ensure deployments target the correct environment. It’s as simple as:

$state = (new \SebastianBergmann\GitState\Builder())->build();
if (!$state->isClean()) {
    throw new \RuntimeException('Dirty working directory!');
}

No external dependencies, no Git library bloat—just what you need."*