VersionControl_Git
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.
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.
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()
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().
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.
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.
getCommits('master', 1000);
]]>
You can specify the starting point of fetching by the third argument.
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
The VersionControl_Git provides the getRevListFetcher() convenience method. Use this normally.
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.
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.
getCommits();
var_dump($commits[0]->getAuthor());
/*
string(35) "Kousuke Ebihara "
*/
var_dump($commits[0]->getCreatedAt());
/*
object(DateTime)#5 (3) {
}
*/
var_dump($commits[0]->getCommitter());
/*
string(35) "Kousuke Ebihara "
*/
var_dump($commits[0]->getCommittedAt());
/*
object(DateTime)#6 (3) {
}
*/
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().
getCommits();
$tree = $git->getTree($commits[0]->getTree());
]]>
The instance doesn't have any contents at the first. If you want to get contents and names, you must call "fetch()" method.
getCommits();
$tree = $git->getTree($commits[0]->getTree());
$tree->fetch();
]]>
The VersionControl_Git_Object_Tree implements the SeekableIterator interface. You can iterate and seek contents of tree.
getCommits();
$tree = $git->getTree($commits[0]->getTree());
$tree->fetch();
foreach ($tree as $content) {
echo $content->getName().':'.PHP_EOL;
var_dump($content);
}
/*
results:
file1:
object(VersionControl_Git_Object_Blob)#304 (3) {
}
file2:
object(VersionControl_Git_Object_Blob)#305 (3) {
}
file3:
object(VersionControl_Git_Object_Blob)#306 (3) {
}
file4:
object(VersionControl_Git_Object_Blob)#307 (3) {
}
dir1:
object(VersionControl_Git_Object_Tree)#308 (4) {
}
dir2:
object(VersionControl_Git_Object_Tree)#309 (4) {
}
dir3:
object(VersionControl_Git_Object_Tree)#311 (4) {
}
dir4:
object(VersionControl_Git_Object_Tree)#312 (4) {
}
dir5:
object(VersionControl_Git_Object_Tree)#313 (4) {
}
dir6:
object(VersionControl_Git_Object_Tree)#314 (4) {
}
dir7:
object(VersionControl_Git_Object_Tree)#315 (4) {
}
dir8:
object(VersionControl_Git_Object_Tree)#316 (4) {
}
file5:
object(VersionControl_Git_Object_Blob)#317 (3) {
}
dir9:
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
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.
getCommits();
$tree = $git->getTree($commits[0]->getTree());
$tree->fetch();
$blob = $tree->current()->fetch();
var_dump($blob->getContent());
]]>
Be aware that the VersionControl_Git_Object_Blob can't understand its filename unless a tree object specified it.
Named blob will teach you its name by calling the getName() method.
current()->fetch();
var_dump($blob->getName());
]]>
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.
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.
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.
getCommand('show')
->setOptions('oneline', true);
]]>
If you want to use arguments, add calling the addArgument() method or the setArguemnts() method.
getCommand('show')
->setArguments(array('master', 'branch1'))
->addArgument('branch2');
]]>
Ready to execute the command? Now you can call "execute()" method and get result.
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
:
*/
]]>