GitElephant drives the git binary from PHP

The git binary does the work, PHP wraps it

GitElephant is an abstraction layer to manage your git repositories with PHP, and the README explains the mechanism in a couple of sentences. It mostly relies on the git binary to retrieve information about the repository, reads the output, and creates an object oriented layer to interact with it. Some parts are, or will be, implemented by reading directly inside the .git folder.

That design has an important consequence, and the README states it plainly: the API is completely transparent to the end user, and you do not have to worry about which method is used. The same call works whether it is implemented by parsing git's output or by reading the repository's own files, which means the library is free to pick the faster route per operation without the caller having to know.

It is also a design with a floor. Anything that shells out to a binary inherits that binary's requirements, so GitElephant officially supports git 1.8 and later, with older versions supported with some caveat. The requirements are PHP 7.2 or later and a Unix-like system with git installed.

For the audience, this is a library for PHP applications that already deal with repositories. It is not a git client and it is not a deployment tool. The value is that a PHP developer can ask a repository what its branches and tags are, and get objects back, without writing and parsing command output at every call site.

Reading branches, tags, commits and remotes

The Repository class is the main class, and the README's usage examples show the shape of the API. You construct one with a path, or use the factory method:

use GitElephant\Repository;
$repo = new Repository('/path/to/git/repository');
// or the factory method
$repo = Repository::open('/path/to/git/repository');

Everything else hangs off that object. Branches come back as Branch instances, with a method for the current checkout and a lookup by name, and there is a static checkout that can also create the branch:

$repo->getBranches(); // return an array of Branch objects
$repo->getMainBranch(); // return the Branch instance of the current checked out branch
$repo->getBranch('master'); // return a Branch instance by its name
$develop = Branch::checkout($repo, 'develop');
$develop = Branch::checkout($repo, 'develop', true); // create and checkout

Tags work the same way, with getTags, getTag by name, a static pick, and a getLastTag for the most recent one by date.

Commits are addressed in several ways: the current HEAD, a tag, or a short or full sha, and the Commit class can also be constructed directly. The commit object is countable, so countCommits on the repository and count on the commit give the same number.

Remotes are exposed as Remote objects, and the log is a collection of commit objects with a documented signature, getLog(<tree-ish>, path = null, limit = 15, offset = null), which means you can walk a subdirectory of history or page through it, and the log itself is both countable and iterable, so a foreach over it yields commits whose message you can read.

Status comes back as a collection of files

The status API is the part of the library that feels most like a framework rather than a wrapper, and it is worth reading closely because it is where the design pays off.

Building a GitElephant\Status\Status class gives you an API for the actual state of the working tree and the staging area, and the static factory is the same thing:

$status = $repo->getStatus();
$status = GitElephant\Status\Status::get($repo); // it's the same...

$status->all(); // A Sequence of StatusFile objects
$status->untracked();
$status->modified();
$status->added();
$status->deleted();
$status->renamed();
$status->copied();

Every one of those methods returns a Sequence of StatusFile objects, and the credit for the sequence type goes to PhpCollection. The alternative to a library like this in PHP is usually to run git status --porcelain and parse the two-character code yourself, which is a small amount of work that has to be redone correctly in every project that needs it.

The StatusFile object carries the details: the file name and, for renamed objects, the new file name, the index and working tree status, and a git style description such as added to index or deleted in work tree. That last field is the useful one in a report, because it turns a code into a phrase a human can read without consulting the git documentation.

The renamed and copied filters are the reason the set exists rather than a single status call. A plain git status does not distinguish them for you, and a deployment tool that wants to know what is about to be deleted needs to ask that question precisely.

Writing: clone, stage, commit, branch and checkout

GitElephant is not read only. The README is explicit that you can also use it to manage your git repositories via PHP, and it gives the same treatment to the write side as to the read side.

$repo->init(); // init
$repo->cloneFrom("git://github.com/matteosister/GitElephant.git"); // clone

// stage changes
$repo->stage('file1.php');
$repo->stage(); // stage all

// commit
$repo->commit('my first commit');
$repo->commit('my first commit', true); // commit and stage every pending changes in the working tree

There is also addRemote, checkout of a tag or a branch, and branch management, with createBranch taking either the current checked out branch as the base or an explicit one.

The operational note that comes with this is about permissions. The README says your web server user, such as www-data, needs to have access to the folder of the git repository. That is the constraint that decides where the library can run. It cannot manage a repository the process cannot see, and a web server user typically has no access to a developer's home directory or to a build agent's workspace.

The second commit form is the one to look at twice. Passing true stages every pending change in the working tree and commits it, which is convenient in a script and dangerous in anything that runs unattended, because it will include files that were never meant to be committed. The single-file stage call is the safer default for a service that writes to a repository.

Version mapping, platform support and the Windows question

The requirements section is short but has an important detail in it: GitElephant maintains a version map for old PHP runtimes. For PHP 7.1 the README asks you to use version 3.x, for PHP 7.0 version 2.x, and for PHP 5.x version 1.x. The current line requires PHP 7.2 or later.

That mapping is a decent signal about the project's longevity. A library that has kept a path for every PHP generation since 5 is one that has been maintained across a decade of PHP, and the version list in the release history shows the same: 4.5.0 in October 2022, 4.6.0 in November 2024 and 5.0.0 in October 2026.

The platform story is narrower. The library is tested on Linux, and the README says it should work well with any Unix system as far as a git binary is available. Windows support is a single sentence, and it is an invitation rather than a promise: for windows support, well, if someone want to help. That is a clear signal that Windows is not a supported target, and a PHP developer on Windows should look elsewhere.

The README also notes that older git versions are supported with some caveat, so a server with an ancient git is a case where the caveats are undocumented in the text available here and worth checking in the issue tracker before committing to it.

Installing with Composer, and the container used for tests

Installation is a Composer requirement, and the README gives the manifest fragment to add to your project root:

{
    "require": {
        "cypresslab/gitelephant": "~4.0"
    }
}

and then the two commands to fetch it:

$ curl -s https://getcomposer.org/installer | php
$ composer install

The library then lives in vendor/cypresslab/gitelephant, and the autoload file to include in your project is vendor/autoload.php. The package name on Packagist is cypresslab/GitElephant.

One detail here deserves a second look, because it is the kind of thing that bites. The install example pins ~4.0, while the newest published release is 5.0.0. A version constraint of that shape will not pick up the 5.x line, so the example and the current release are out of step, and a team that copies the documented snippet will get the 4.x series rather than the newest one. That is worth checking against the changelog and the migration notes in the repository before you pin anything.

For running the test suite, the repository ships a container setup. The Dockerfile starts from php:7.2-alpine, installs git and zlib-dev, sets a global git user name and email for the tests, installs the zip extension and installs Composer. The compose file defines a single service named git that builds from that image, mounts the working tree at /code and works there.

The rest of the repository shows a mature PHP project: a src directory, a tests directory with phpunit.xml and phpunit.xml.dist, an examples directory with a single script that shows file contents, and the tooling files a modern PHP project carries, ecs.php for coding standards, phpstan.neon for static analysis, rector.php for automated refactoring, a Dockerfile, a .scrutinizer.yml and a Travis configuration alongside GitHub Actions.

LGPL-3.0, the develop branch and the 5.0 release

The licence is LGPL-3.0, which is a weak copyleft licence. For a library that is consumed by a PHP application, the practical question is how the library is distributed. If it is installed as a Composer dependency alongside your application, the obligations attach to modifications to the library itself rather than to your application code. If you vendor it into a closed product, the analysis is more involved, and this is a reading of the licence type rather than legal advice.

The default branch is develop, and the release history shows that the project now treats a major version as a routine event. Version 4.6.0 came out on 2024-11-26 and 5.0.0 on 2026-10-05, with 4.5.0 in October 2022 before that. The last push to the repository was on 2026-10-05, the same day as the 5.0.0 tag, and the repository is not archived.

The repository also carries a ROADMAP.md, a SECURITY.md and a CHANGELOG.md, which is the set of documents to read before you upgrade across a major version. With a library whose API is the product, the changelog between 4.x and 5.x is the document that tells you whether the upgrade is a weekend or a fortnight.

The overall picture is a long-lived, carefully maintained library with an explicit version policy, a permissive-in-practice API surface and one honest gap, which is Windows.

Editorial conclusion

GitElephant fits a PHP application that has to inspect or drive a git repository as part of its job, such as a deployment tool, a review system or a content pipeline, and that would rather call a typed PHP API than shell out to git in a dozen places. It is the wrong choice for a build system, where calling git from the shell is simpler, and it is the wrong choice on Windows, which the README effectively leaves unsupported. Before adopting it, check the PHP version you are on against the version mapping in the README, since the library targets PHP 7.2 and up while the install example still pins the 4.0 series, and note that the package is licensed LGPL-3.0, which carries obligations for a distributor that a permissive licence would not.

Frequently asked questions

Official sources

1. Issues
2. License: LGPL-3.0
3. matteosister/GitElephant on GitHub
4. README
5. Releases