Git Profiler Bundle Laravel Package

Getting Started

This package wraps Git operations in a Laravel-friendly API, letting you run version control tasks from your application code or Artisan commands instead of shelling out with exec().

1. Install the package via Composer and, if the service provider isn't auto-discovered, register it in config/app.php.
2. Publish the config file so you have something to edit:

   php artisan vendor:publish --provider="<Package>ServiceProvider" --tag=config
   

3. Look first at the published config file. In 1.1.0 this is where the new binary (or equivalently named) key lives — set it to the absolute path of your Git executable if git isn't on the PATH the PHP process sees.
4. Resolve the package from the container (app(...) / constructor injection / facade, depending on how it's exposed) and run your first read-only operation — a status, log, or branch listing — against a repository you can safely inspect. Never start with push, reset --hard, or checkout against a real working tree.

First realistic use case: a deploy or release Artisan command that checks the current branch and commit hash, then tags a release. That exercises the config, the binary resolution, and the output parsing all at once without risking data.

Implementation Patterns

Configuration-driven binary (new in 1.1.0). The main workflow shift is that binary resolution is now a config concern rather than a hardcoded assumption. Set it per environment:

// config/<package>.php
'binary' => env('GIT_BINARY', 'git'),

Then in .env:

GIT_BINARY=/usr/local/bin/git

This matters when PHP's PATH differs from your shell's — common under FPM, Horizon workers, or CI containers. Resolve the correct path with which git in the same user context the worker runs as, not your interactive shell.

Environment-specific overrides. Keep git as the default and only override where needed: Windows dev machines (C:\Program Files\Git\cmd\git.exe), Nix/macOS Homebrew paths (/opt/homebrew/bin/git), or a pinned binary inside a container image. This keeps the config portable across the team.

Service-layer wrapping. Don't call Git operations directly from controllers. Wrap them in a dedicated class (ReleaseService, RepoStatus) so you can inject the package, mock it in tests, and centralize timeouts and error handling. Controllers should receive plain arrays/DTOs.

Read vs. write separation. Use the package for read operations (status, log, diff, branch listing) directly. For write operations (commit, tag, push), funnel through a service with explicit logging and a guard on the target branch/environment. This is the single biggest safety pattern for day-to-day use.

Queued jobs for anything slow. Network-touching operations (fetch, pull, push) belong in a queued job with a timeout and retry policy. Long-running synchronous Git calls will block your request and can time out under FPM.

Diagnostics command. Build an Artisan command (git:doctor) that reports the resolved binary path, the Git version, and the working directory. When 1.1.0's config key is wrong, this is the fastest way to see it — and it gives new team members a one-command setup check.

Gotchas and Tips

The binary path is not expanded or shell-interpolated. A configured ~/bin/git or $HOME/bin/git will typically fail because the process isn't a login shell. Always use absolute paths in the config, and verify with realpath.

Config caching bites. After changing the binary in .env, run php artisan config:clear (or re-run config:cache in deploy). A stale cached config is the number one cause of "I changed it and nothing happened" — especially when the override is added during a deploy but the cache was built earlier.

Windows paths need escaping attention. Backslashes in double-quoted PHP strings are escape sequences. Use single quotes ('C:\Program Files\Git\cmd\git.exe') or forward slashes, and remember .env values with spaces should not be quoted in a way your env parser mishandles.

PATH differences between CLI and web requests. php artisan runs with your shell's environment; an HTTP request or queue worker may not. Always validate the binary from the same entry point that will use it — reproduce the failure in php artisan tinker via the queue/worker context if possible, not just your terminal.

Missing binary vs. missing repository. A bad binary path and a bad working directory produce different errors but both surface as generic failure messages. Log stderr and the exit code separately, and include the resolved binary in your exception message so the two are distinguishable in production logs.

Shell injection surface. If you pass user-supplied strings (branch names, tag messages, file paths) into Git operations, ensure they're passed as discrete arguments rather than concatenated into a command string. Treat branch names from request input as untrusted — Git's own refname rules help, but validate first.

Permissions in containers and CI. The binary must be executable by the PHP user, and the repository must be a safe directory. Recent Git versions refuse to operate on repos owned by a different user — if you mount a host repo into a container, add safe.directory or match UIDs.

Extension point. The config file is the correct seam for future environment variation (custom SSH command, core.sshCommand, timeouts). Keep your own overrides there rather than hardcoding flags in application code, so upgrades to the package — like this one — merge cleanly.