Manual

VersionControl_Git is a library that provides OO interface to handle Git repository. You can use Git command via the wrapper class. Some features are provided by high-featured interface.

Tutorial

Initialize a new repository

The VersionControl_Git class represents your Git repository.

You should specified a path to repository to VersionControl_Git.

<?php
require_once 'VersionControl/Git.php';

// Specify a directory
$git = new VersionControl_Git('/path/to/repository');

Do you want to create new repository? It is easy.

First, create an instance of VersionControl_Git and pass a directory what you want to create new Git repository.

Next, call the VersionControl_Git::initRepository() method.

<?php
require_once 'VersionControl/Git.php';

// Specify a directory
$git = new VersionControl_Git('/path/to/repository');

// create new repository
$git->initRepository();

// If you want to create bare repository, pass true as the first argument
$git->initRepository(true);

Do you want to create clone repository? In this case, you can use the VersionControl_Git::createClone()

<?php
require_once 'VersionControl/Git.php';

// Specify a directory
$git = new VersionControl_Git('/path/to/repository');

// create new repository
$git->createClone('http://example.com/repository.git');

// If you want to create bare repository, pass true as the second argument
$git->createClone('http://example.com/repository.git', true);

Now, you've readied to use full futures of VersionControl_Git.

Getting commits

The commit object in Git is provided as VersionControl_Git_Object_Commit.

There are some ways to get a list of VersionControl_Git_Object_Commit objects.

Use VersionControl_Git::getCommits()

You can get commits by calling VersionControl_Git::getCommits().

<?php
require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/path/to/repository');
var_dump($git->getCommits());
/*
results:

array(100) {
  [0]=>
  object(VersionControl_Git_Object_Commit)#3 (9) {
    :
  }
  [1]=>
  object(VersionControl_Git_Object_Commit)#6 (9) {
    :
  }

  :
*/

Calling without arguments, VersionControl_Git::getCommits() returns a list of a hundred VersionControl_Git_Object_Commit instances from master branch. You can specify branch name, commit object name, tag name, tree object name and an instance of VersionControl_Git_Object.

<?php
require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/path/to/repository');

// from master branch
$git->getCommits();

// specify stable branch
$git->getCommits('stable');

// specify object name
$git->getCommits('6c8284e4902c3adaf356adeed40d8bda715b73a0');

// specify tag name
$git->getCommits('v1.0');

// specify an instance of VersionControl_Git_Object
$commits = $git->getCommits();
$git->getCommits($commits[0]);

You can specify the maximum number of commits by the second argument.

<?php
require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/path/to/repository');

// get 1000 commits from master branch
$git->getCommits('master', 1000);

You can specify the starting point of fetching by the third argument.

<?php
require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/path/to/repository');

// get 100 commits from master branch (starting at 100 th commit)
$git->getCommits('master', 100, 100);

Use VersionControl_Git_Util_RevListFetcher

The VersionControl_Git_Util_RevListFetcher is utility class for wrapping "git-rev-list" command. So you can use any feature of "git-rev-list" by this. VersionControl_Git::getCommits() provides by using VersionControl_Git_Util_RevListFetcher.

You can use VersionControl_Git_Util_RevListFetcher to specify your VersionControl_Git instance to the constructor

<?php
require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/path/to/repository');
$fetcher = new VersionControl_Git_Util_RevListFetcher($git);

The VersionControl_Git provides the getRevListFetcher() convenience method. Use this normally.

<?php
require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/path/to/repository');
$fetcher = $git->getRevListFetcher();

After specifying target (branch name, commit name, tree name, etc) and options, you can get an array of VersionControl_Git_Object_Commit by calling the fetch() method.

<?php
require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/path/to/repository');
$result = $git->getRevListFetcher()
    ->target('master')
    ->setOption('max-count', 10)
    ->setOption('grep', 'initial')
    ->setOption('date', '3 hours ago')
    ->fetch();

The commit object (VersionControl_Git_Object_Commit)

An instance of the VersionControl_Git_Object_Commit provides information about a commit.

<?php
require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/path/to/repository');
$commits = $git->getCommits();

var_dump($commits[0]->getAuthor());
/*
string(35) "Kousuke Ebihara <kousuke@co3k.org>"
*/

var_dump($commits[0]->getCreatedAt());
/*
int(1503517047)
*/

var_dump($commits[0]->getCommitter());
/*
string(35) "Kousuke Ebihara <kousuke@co3k.org>"
*/

var_dump($commits[0]->getCommittedAt());
/*
int(1503517047)
*/

var_dump($commits[0]->getMessage());
/*
string(62) "changed url to JSON version of dashboard contents (fixes #509)"
*/

var_dump($commits[0]->getParents());
/*
array(1) {
  [0]=>
    object(VersionControl_Git_Object_Commit)#303 (9) {
    }
}
*/

var_dump($commits[0]->getTree());
/*
string(40) "ba2dd3d861f68c6ea31c4cd4444a5d86869a3401"
*/

The tree object (VersionControl_Git_Object_Tree)

An instance of the VersionControl_Git_Object_Tree represents tree object in Git. It has pointers to contents of the direcotry.

An instance of VersionControl_Git_Object_Tree can get via VersionControl_Git::getTree().

<?php
require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/path/to/repository');
$commits = $git->getCommits();

$tree = $git->getTree($commits[0]->getTree());

The instance doesn't have any contents at the first. If you want to get contents, you must call "fetch()" method.

<?php
require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/path/to/repository');
$commits = $git->getCommits();

$tree = $git->getTree($commits[0]->getTree());
$tree->fetch();

The VersionControl_Git_Object_Commit implements the SeekableIterator interface. You can iterate and seek contents of tree.

<?php
require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/path/to/repository');
$commits = $git->getCommits();

$tree = $git->getTree($commits[0]->getTree());
$tree->fetch();

foreach ($tree as $content) {
   var_dump($content);
}

/*
results:

object(VersionControl_Git_Object_Blob)#304 (3) {
}
object(VersionControl_Git_Object_Blob)#305 (3) {
}
object(VersionControl_Git_Object_Blob)#306 (3) {
}
object(VersionControl_Git_Object_Blob)#307 (3) {
}
object(VersionControl_Git_Object_Tree)#308 (4) {
}
object(VersionControl_Git_Object_Tree)#309 (4) {
}
object(VersionControl_Git_Object_Tree)#311 (4) {
}
object(VersionControl_Git_Object_Tree)#312 (4) {
}
object(VersionControl_Git_Object_Tree)#313 (4) {
}
object(VersionControl_Git_Object_Tree)#314 (4) {
}
object(VersionControl_Git_Object_Tree)#315 (4) {
}
object(VersionControl_Git_Object_Tree)#316 (4) {
}
object(VersionControl_Git_Object_Blob)#317 (3) {
}
object(VersionControl_Git_Object_Tree)#318 (4) {
}
*/

The blob object (VersionControl_Git_Object_Blob)

An instance of the VersionControl_Git_Object_Blob represents tree object in Git. It has contents of the file.

It can get via VersionControl_Git_Object_Tree

<?php

require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/home/co3k/sf/op3-ebihara');
$commits = $git->getCommits();

$tree = $git->getTree($commits[0]->getTree());
$tree->fetch();

$blob = $tree->current();
var_dump($blob);
/*
results:

object(VersionControl_Git_Object_Blob)#304 (3) {
}
*/

The instance doesn't have any contents at the first. If you want to get contents, call the getContents() after calling the fetch() method.

<?php

require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/home/co3k/sf/op3-ebihara');
$commits = $git->getCommits();

$tree = $git->getTree($commits[0]->getTree());
$tree->fetch();

$blob = $tree->current()->fetch();
var_dump($blob->getContent());

Handle command

The VersionControl_Git prepares OO interface of some Git feature, but it is not completely.

If you want to use full feature of Git by using VersionControl_Git, you should run Git command via VersionControl_Git_Util_Command.

To tell the truth, most of the feature of VersionControl_Git uses VersionControl_Git_Util_Command.

Now, I explain you how to use VersionControl_Git_Util_Command.

<?php

require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/home/co3k/sf/op3-ebihara');
$command = $git->getCommand('show');

You can get an instance of VersionControl_Git_Util_Command by calling VersionControl_Git::getCommand() with sub-command name.

If you want to use options, add calling the setOption() method or the setOptions() method.

<?php

require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/home/co3k/sf/op3-ebihara');
$command = $git->getCommand('show')
    ->setOptions(array(
        'pretty' => 'raw',
    ))
    ->setOptions('pretty', 'raw');

The boolean option value is special. "true" is specified as option value, it doesn't have value. "false" is specified as option value, the option will not be used.

<?php

require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/home/co3k/sf/op3-ebihara');
$command = $git->getCommand('show')
    ->setOptions('oneline', true);

If you want to use arguments, add calling the addArgument() method or the setArguemnts() method.

<?php

require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/home/co3k/sf/op3-ebihara');
$command = $git->getCommand('show')
    ->setArguments(array('master', 'branch1'))
    ->addArgument('branch2');

Ready to execute the command? Now you can call "execute()" method and get result.

<?php

require_once 'VersionControl/Git.php';

$git = new VersionControl_Git('/home/co3k/sf/op3-ebihara');
$result = $git->getCommand('show')
    ->setOption('oneline', true)
    ->addArgument('master')
    ->execute();
var_dump($result);

/*
result:

string(829) "9a259a5 changed url to JSON version of dashboard contents (fixes #509)
diff --git a/apps/pc_backend/modules/default/templates/topSuccess.php b/apps/pc_backend/modules/default/templates/topSuccess.php
index 3c7764e..cbfcf26 100644
  :
*/