Git Component

This component helps interacting with the Git command line tool and the Git-Flow extension., _(*1)

This tool is built using the Symfony Process Component (https://github.com/symfony/Process) but can be used in any PHP projects. The requirements are specified in the composer.json file:, _(*2)

PHP version >=5.4
symfony/process version >= 2.4
symfony/filesystem version >= 2.2 (only for running the tests in development environment)
git
git-flow (required only for using the Git-Flow wrapper extension)

, _(*3)

Installation

This component is available for installation through composer. From command line run:, _(*4)

$ composer require "ggioffreda/git" "~0.1"

Or add the following to your composer.json in the require section:, _(*5)

"require": {
    ... other requirements ...,
    "ggioffreda/git": "~0.1"
}

For more information check the project page on Packagist., _(*6)

Usage - Git

The list of shortcut and self-explanatory methods implemented for Git:, _(*7)

init, initializes the Git repository if not already initialized;
config, sets or requests a configuration variable, when getting it you need to call the output method afterward to get the value;
add, adds the files matching the provided pattern to the next commit;
rm, removes the files matching the provided pattern to the next commit;
mv, moves the file from origin to destination;
diff, returns the output of the diff command on the whole project or for the specified pattern;
show, returns the output of the show command for the specified object;
commit, commits the changes to the current branch;
branchAdd, creates a new branch with the given name;
branchDelete, deletes the branch with the given name;
branchList, lists the branches of the Git repository;
checkout, checks out the required entity (can be anything allowed by Git, like a branch, a file or an hash);
status, returns the output of the Git status command on the Git project;
merge, merges the given branch to the current one;
log, returns the output of the Git log command, by default the last 10 commits;
push, pushes the commits to the remote repository;
pull, pulls the commits from the remote repository;
fetch, fetches the remote branches;
remoteAdd, adds a remote;
remoteRename, renames a remote;
remoteRemove, removes a remote;
remoteSetHead, sets the HEAD for a remote;
remoteSetBranches, set the branches for a remote;
remoteGetUrl, get the URL of a remote;
remoteSetUrl, set the URL of a remote;
remoteShow, shows information of a remote;
remotePrune, prunes a remote;
flow, access the git-flow wrapper extension.

List of other methods provided for Git:, _(*8)

run, allows you to run any custom Git command you could think of;
getConfiguration, return an array of Git configuration key and values;
getBranches, returns an array of branches with related last commit hash and message;
getStatuses, returns an array of non commited changes with a status each (in "porcelain" Git flavour);
getLogs, returns the array of last commits with related messages, you can specify the size of the array;
output, returns the output of the last command executed on the Git project;
history, returns the array of all the commands and related outputs executed on the Git project.

List of static methods and basic features for Git:, _(*9)

create (static), returns a new instance for the specified path and Git executable (optional);
cloneRemote (static), returns a new instance cloning the remote repository in the local path;
getPath, returns the path of the Git project;
getDefaults, returns the default options for the shortcut method (see above the list of shortcut methods);
setDefaults, sets the default options for the shortcut method (see above the list of shortcut methods).

When the execution of a Git command fails because of wrong options or for unknown reasons the any method can return a Gioffreda\Component\Git\Exception\GitProcessException, while if the error happens parsing the output of the command the exception will be of Gioffreda\Component\Git\Exception\GitParsingOutputException. Both share the same parent so they can be caught at once if needed Gioffreda\Component\Git\Exception\GitException., _(*10)

Usage - GitFlow

List of shortcut and self-explanatory methods implemented for Git-Flow:, _(*11)

init, initialized git-flow for the Git project with the default values, to use custom values call the run method instead providing the desired options;
featureList, lists existing features;
featureStart, starts a new feature, optionally basing it on another base instead of "develop";
featureFinish, finishes the feature;
featurePublish, starts sharing the feature;
featureTrack, starts tracking the feature;
featureDiff, shows all changes that are not in "develop";
featureRebase, rebases on "develop";
featureCheckout, switches to the feature branch;
featurePull, pull the feature from the remote repository;
releaseList, lists existing releases;
releaseStart, start a new release;
releaseFinish, finishes the release;
releasePublish, starts sharing the release;
releaseTrack, starts tracking the release;
hotfixList, lists existing hotfixes;
hotfixStart, start a new hotfix, optionally basing it on a different base than "master";
hotfixFinish, finishes the hotfix;
supportList, lists existing support branches;
supportStart, starts a new support branch;
getConfiguration, returns the git-flow current configuration;
getVersion, returns the git-flow current version;
run, allows you to run any custom command through git-flow;
output, returns the output for the last executed command, it's an alias for the parent Git::output() method;
extend (static), return the git-flow extension wrapper for the given Git project.

Beware if the git-flow extension is not available all the above methods (but output and extend) will throw an exception., _(*12)

Example

For a real life example check this out: Git-Guardian. It's a command line interface for backing up locally all your remote repositories from either GitHub or BitBucket., _(*13)

The following example shows how to use the component. All non getter methods not used to read properties or command output implement a fluent interface to improve readability:, _(*14)

<?php

namespace MyNamespace;

use Gioffreda\Component\Git\Git;

class MyJob
{

    public function doSomething($remoteUri, $localPath)
    {
        // cloning a remote repository
        $git = Git::cloneRemote($remoteUri, $localPath);
        // switches to the develop branch
        $git->checkout('develop');

        // your logic here, change some files
        // ...

        $git
            // adds all the files
            ->add('.')
            // commits the changes to the develop branch
            ->commit('Changed some files')
            // switches to the master branch
            ->checkout('master')
            // merges the develop branch into the master branch
            ->merge('develop')
            // commits the changes into the master branch
            ->commit('Merged the changes into master.')
            // pushes the changes to the remote repository using a custom command line
            ->run(['push', '--all'])
        ;

        // or you can use a local one even if not initialized yet
        // new Git project using a custom executable
        $git = Git::create($localPath, '/usr/local/custom/git');
        $git
            // this will initialize the Git project if not initialized already
            ->init()
            // adds all the files in the folder ./src
            ->add('./src')
            // commits the changes
            ->commit('Initial commit (only sources).')
        ;

        // retrieves the last commits hashes and messages
        $logs = $git->getLogs();
        // retrieves the list of branches with latest commit hash and message
        $branches = $git->getBranches()

        // using git-flow, initializing it first
        $git->flow()->init();
        // starts a new feature
        $git->flow()->featureStart('test1');

        // your logic here, change some files
        // ...

        $git
            // mark the changes so they'll be committed
            ->add('.')
            // commits the the changes
            ->commit('feature finished')
            // finishes the feature
            ->flow()->featureFinish('test1')
        ;
    }

}

Resources

You can run the unit tests with the following command (requires phpunit):, _(*15)

$ cd path/to/Gioffreda/Component/Git/
$ composer.phar install
$ phpunit

License

This software is distributed under the following licenses: GNU GPL v2, GNU GPL v3 and MIT License. You may choose the one that best suits your needs., _(*16)