e-butik / gittern

Making Git like music for PHP's ears. A library for reading from and writing to git repositories, that doesn't depend on the git binary.

Gittern

Making Git like music for PHP's ears.

Version 0.8 under development (because starting out at 0.1 or 1.0 is for squares)

Documentation is available at Read the Docs.

What is Gittern?

Gittern is a PHP library for reading from and writing to Git repositories. It doesn't depend on the git binary, it directly acccesses the repo files.

Gittern provides several interfaces for interacting with your Git repos. Firstly, there's a low level interface, where you manually create blobs, trees and commits. This can however become cumbersome very quickly. As such, there's also two different Gaufrette adapters included.

The first one, GitternCommitishReadOnlyAdapter is pretty much what it sounds like. It's an adapter to which you supply a commitish, and from which you may read the files associated with that commit.

The second one, GitternIndexAdapter allows you to read from and write to the Git index. The Git index is the staging area in which you stage new changes for a commit. Then, when you're ready, creating a commit from the index is quite simple. Just get the tree from the index, and use it to create your commit.

In addition to all of this functionality, Gittern is created with extensibility in mind. How Gittern reads data from the repository on disk is cleanly separated using the adapter pattern, so that if you have the need you could easily implement e.g. an adapter capable of maintaining multiple indexes, or Git object caching in something like MongoDB or Redis (in fact, if you don't care about accessing the repo from the git binary, you could just use this as a fast, distributed backend).

Who's behind all this?

E-butik.se, one of Sweden's foremost e-commerce platform providers. Visit our developer blog.

How do I install Gittern?

Use Composer. More detailed instructions are available in the docs.

How stable is the API?

Not very. We're still refactoring the API pretty much whenever we feel like it. What is semi-stable though is that the Gaufrette adapters will remain compatible with the Gaufrette master branch, so if you're mainly using the Gaufrette adapters, you'll not experience a lot of API breakage.

Kinda-sorta bugs

• The index flags field (see http://opensource.apple.com/source/Git/Git-26/src/git-htmldocs/technical/index-format.txt) contains an assume-valid flag that's not represented
• The file name length of the flags field should only be written in full if it's less than 0xFFF.
• The stage flag isn't desiccated properly.
• Indexes in conflict (i.e. with stage > 0, see http://opensource.apple.com/source/Git/Git-26/src/git-htmldocs/technical/index-format.txt) should be handled somehow, even if just by an exception.
• The mtime of a file in GitternCommitishReadOnlyAdapter is always the same as for the commit, regardless of whether the file has been changed in the given commit or not.

Planned features

There are several planned features, which didn't make it in to version 0.8.

• Subclassing Repository with a git binary dependent subclass to allow some advanced commands
• Packfile creation (currently packfiles can only be read)
• Support for resolving lightweight tags
• Support for reading annotated tags
• Support for the link tree entry type
• Support for the commit tree entry type (i.e. submodules)
• Making the Gittern\Entity\GitObject\User class into an interface
• Support for all kinds of Git Treeishes
• Support for updating the reflog when moving a branch head

gittern's Issues

Tree diffs fail when comparing a tree from a commit with one created from the index

This is because equality tests between nodes with and nodes without SHAs always fail (because the ones without SHAs aren't by convention immutable). Generally speaking, this is a good thing.

Suggested solution is to make GitObjects forcibly immutable once they have a SHA (and nodes always immutable), and to have two options for the index, to create either a mutable or an immutable tree.

We should also keep track off whether a given SHA is persistent or not, then.

Signed-off commits aren't implemented

I haven't looked in to it closely, but Gittern has no concept of signing off a commit. I believe it should still parse the commits correctly, just not handle the sign-off information at all, but I haven't tested this.

Allow Gittern to wrap php-git's API

That way you could build an app that uses Git which works faster when the php-git module is available, and works when it isn't.

Committing equivalent objects may cause unnecessary writes (and semi-cloned live objects)

When an object that is equivalent with another object, e.g. two blobs with the same contents, or two trees with the same nodes; is persisted to the transport, it may cause an unnecessary write, since neither the repository nor the transport keeps track of which objects are already persisted.

Also, in such a case, two distinct objects with the same SHA but different object identities may be alive in the program memory. This is unfavorable, both from a memory standpoint, and from a object equivalency standpoint.