commit.md

Commit

To access a Commit, starting from a repository object:

$repository = new Gitonomy\Git\Repository('/path/to/repository');
$commit = $repository->getCommit('a7c8d2b4');

Browsing parents

A Commit can have a natural number of parents:

• no parent: it's an initial commit, the root of a tree
• one parent: it means it's not a merge, just a regular commit
• many parents: it's a merge-commit

You have 2 methods available for accessing parents:

// Access parent hashes
$hashes = $commit->getParentHashes();

// Access parent commit objects
$commits = $commit->getParents();

For example, if you want to display all parents, starting from a commit:

function displayLog(Gitonomy\Git\Commit $commit) {
    echo '- '.$commit->getShortMessage().PHP_EOL;
    foreach ($commit->getParents() as $parent) {
        displayLog($parent);
    }
}

Notice that this function will first display all commits from first merged branch and then display all commits from next branch, and so on.

Accessing tree

The tree object contains the reference to the files associated to a given commit. Every commit has one and only one tree, referencing all files and folders of a given state for a project. For more informations about the tree, see the chapter dedicated to it.

To access a tree starting from a commit:

// Returns the tree hash
$tree = $commit->getTreeHash();

// Returns the tree object
$tree = $commit->getTree();

Author & Committer informations

Each commit has two authoring informations: an author and a committer. The author is the creator of the modification, authoring a modification in the repository. The committer is responsible of introducing this modification to the repository.

You can access informations from author and committer using those methods:

// Author
$commit->getAuthorName();
$commit->getAuthorEmail();
$commit->getAuthorDate(); // returns a DateTime object

// Committer
$commit->getCommitterName();
$commit->getCommitterEmail();
$commit->getCommitterDate(); // returns a DateTime object

Commit message and short message

Each commit also has a message, associated to the modification. This message can be multilined.

To access the message, you can use the getMessage method:

$commit->getMessage();

For your convenience, this library provides a shortcut method to keep only the first line or first 50 characters if the first line is too long:

$commit->getShortMessage();

You can customize it like this:

$commit->getShortMessage(45, true, '.');

• The first parameter is the max length of the message.
• The second parameter determine if the last word should be cut or preserved
• The third parameter is the separator

There are also two other methods for your convenience:

// The first line
$commit->getSubjectMessage();

// The body (rest of the message)
$commit->getBodyMessage();

Diff of a commit

You can check the modifications introduced by a commit using the getDiff method. When you request a diff for a commit, depending of the number of parents, the strategy will be different:

• If you have no parent, the diff will be the content of the tree
• If you only have one parent, the diff will be between the commit and his parent
• If you have multiple parents, the diff will be the difference between the commit and the first common ancestor of all parents

For more informations about the diff API, read the related chapter.

To access the Diff object of a commit, use the method getDiff:

$diff = $commit->getDiff();

Last modification of a file

To know the last modification of a file, you can use the getLastModification method on a commit.

Here is a very straightforward example:

$last = $commit->getLastModification('README');

echo 'Last README modification'.PHP_EOL;
echo '  Author: '.$last->getAuthorName().PHP_EOL;
echo '    Date: '.$last->getAuthorDate()->format('d/m/Y').PHP_EOL;
echo ' Message: '.$last->getMessage();

Find every branches containing a commit

$branches       = $commit->getIncludingBranches($includeLocalBranches, $includeRemoteBranches);
$localBranches  = $commit->getIncludingBranches(true, false);
$remoteBranches = $commit->getIncludingBranches(false, true);